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.
Migrator Phase 3, milestone 1: settle the golden format before S7 freezes it
Louis Choquel9eea2219fb8e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 69e716f97..a50dade2c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@### Added+- **A migration operation can now remap every value beneath an open mapping**: `remap_value` accepts `key = "*"`, meaning "each key of the addressed table" — the same "each of these" reading the wildcard already had in a `table_path`, applied to keys. A mapping from the user's own keys to an enumerated value (`dict[str, LogLevel]`) keeps its spellings under keys only the document can enumerate, so no fixed key reaches them and this is the only shape in which a member renamed beneath one can be repaired at all. On every other kind a `*` key is now refused when the operation is parsed: deleting every key of a table is `delete_table`, and renaming or moving every key onto one fixed name is the many-to-one that already rules a wildcard out of a `move_key`. Refused rather than tolerated, because an unrefused one is a *dead* operation that skips forever while looking like an accounting.+- **A schema change that narrows what a value may *be* is now caught, not waved through as additive**: A change can keep every path and every enumerated spelling and still break a user's file — `int` becomes `str`, a free string becomes an enum, a bound moves from `ge=1` to `ge=5`. Read as a path diff those look like additions, so the coverage gate used to ask for a golden regeneration, demand no version bump and no entry, and let the next boot reject a valid file with a green gate behind it. It now splits its verdict by *direction*: a widened type or a relaxed bound still costs only a regeneration, while a narrowing demands a bump and an entry carrying a `remap_value` for each narrowed path — or marked `unsafe`, which is the only remedy a tightened numeric bound has, since no structural operation can repair a value. The same rule applies to a stored entry, compared by origin so a narrowing hidden behind a rename is still caught, and to a `pre_history` entry, so the flag is not a way past it. To see a bound at all the fingerprint now records one: a **closed whitelist** over `gt`, `ge`, `lt`, `le`, `min_length`, `max_length` and `multiple_of`, read from `annotated_types` (now a declared dependency) and from the field metadata pydantic folds a top-level `Field(ge=1)` into, with anything unrecognized dropped rather than serialized — `pattern` excluded permanently, because regex containment is not decidable and every pattern edit would read as a tightening. One correction rides along: an enumerated type relaxed into a free string no longer reads as the loss of every spelling it had. The contract states in the same change what the gate structurally cannot see — narrowing expressed in a validator, which no projection of the annotations can reach.- **The telemetry configuration can now be migrated instead of thrown away, and the escape hatch that would have let it ship unverified is closed**: `telemetry.toml` carries the package's first migration entry, `telemetry-config@2`, which lifts a flat first-generation file — `telemetry_mode`, `host`, `project_api_key` and the rest at the document root — into today's `[custom_posthog]` section, keeping every value the user chose; four settings the current shape has no home for are dropped, and the entry says which and why. Because that change predates the first fingerprint, no diff describes it, and such an entry is marked `pre_history` and exempted from the coverage gate's accounting — so the verification that replaces it lands in the same change and neither ships without the other. A pre-history entry must declare the paths it removes (an empty declaration is refused when the ledger is parsed), none of those paths may appear in any fingerprint at or below its own version, the fingerprint pair it sits between must show no removal at all, and every operation must act inside the declaration. It also ships a hand-authored `[email protected]` beside the golden chain, which the transform check migrates and holds against the current shape and the current model — the same three claims every other entry answers. One comparator refinement came with it: a created path is now checked against `defaults@N` **or** `fingerprint@N`, because an optional key defaulting to `None` is a legal destination that no TOML document can carry.- **Configuration surfaces now have a migration ledger and a gate that forces one to be written**: Each of the three configuration surfaces — `pipelex.toml` and its tiers, `telemetry.toml`, `pipelex_service.toml` — carries a checked-in ledger at `pipelex/migration/ledgers/<surface-id>.toml` recording, as data, every shape change it has ever undergone, plus a golden chain (`fingerprint@N`, `defaults@N`) that pins what the schema looked like at each version. All three start at schema version 1 with no entries: this release cuts the baseline, it migrates nothing. The new `make check-migration-schemas` (alias `cmig`, in `make check`) recomputes each surface's fingerprint and refuses a change that would break a user's file without recording how to repair it — a removed path or a lost enumerated spelling demands a version bump and an operation accounting for it, a destination the new schema does not know is refused by name, and an entry that removes a path the schema still has is refused as over-deletion. Its counterpart `make up-migration-schemas` (alias `umig`, in `make up`) regenerates the goldens; the regeneration diff is the review artifact. One standing invariant is checked whether or not anything changed: every required path must have a value in its surface's defaults layer, because that is what makes an added key absorbable rather than breaking. The contract the whole thing implements is `docs/migration-ledger.md`.@@ -16,6 +18,10 @@### Changed+- **The fingerprint records the bounds a file actually meets, and the enumerated spellings where an operation can reach them**: A bound in a field's own metadata *binds* — pydantic applies it on top of whatever a union member declares — so the two sources are now merged separately and intersected instead of pooled and widened; a field whose own `Field(le=6)` was the real ceiling used to be recorded as `le=100` because a member said so, and a later tightening of that ceiling then read as a change to an already-looser one. Enumerated members beneath an open mapping are now recorded only on the wildcard record, whose own value is the enumerated one: recording them on the container as well made the coverage gate demand a remap of a table value, a demand no operation could satisfy. Every other container is still descended into, since a `list[enum]` has no child record — and there the gate now names `unsafe` as the only remedy rather than crediting a remap that would skip on every run. One golden moved with it: the duplicated member set on `pipelex.log_config.package_log_levels`.+- **The narrowing relation stopped crying wolf on four shapes**: A container whose argument widened (`list[int]` → `list[int | str]`) is read structurally instead of as one opaque string; `int` is absorbed by `float`, which accepts every integer in strict validation as well as lax; `enum` and `literal` absorb each other, because they are two renderings of one thing and what moved between two member *sets* is reported by the enumerated-spelling half; and over an integral type `gt=n` and `ge=n+1` are folded to the same bound, so swapping one spelling for the other stops reading as a tightening. Each was a false breaking verdict on a schema no user's file can tell apart, and the remedy the gate named — bump the version, write an `unsafe` entry — was work with no beneficiary.+- **`make up-migration-schemas` left `make up`, and refuses to erase a removal**: Every other regenerator in that aggregate rewrites a derived artifact from a live source, so running them out of habit is harmless; the head fingerprint golden is the proof obligation the coverage gate compares against, and rewriting it after deleting a field erases the very removal the gate exists to catch. It is now run on purpose, and it stops before overwriting a head golden recording a path, an enumerated spelling or a value domain the models no longer have. The refusal names both readings — a real removal wants a bump and an entry; a golden that merely predates a change to the fingerprint format wants the new `make umigf` — because the code cannot tell them apart.+- **The fix applier moves and renames a table whole even when a descendant is written in several places**: A `[a.b]` … `[a.c]` … `[a.b.d]` layout stores `a.b` as several chunks under one key, and tomlkit's own header-cache invalidation walks the merged dict facade — one chunk per key — so renaming or moving `a` used to leave the later chunks rendering under the old name: the file came out split between the old name and the new, with an `applied` verdict. The applier now refreshes every chunk beneath a renamed or moved table, so the file re-parses to the same value under the new path, in the original order. This reaches every caller of the applier, the `.mthds` fix loop included.- **Templating style is now an authoring decision (Breaking)**: How a pipe's inputs are tagged into a prompt is declared on the pipe — `templating_style` on `PipeLLM`, either a bare tag-style string (`"xml"`, `"ticks"`, `"square_brackets"`, `"no_tag"`) or a full `{ tag_style, text_format }` table — with a single runtime default for everything that declares nothing (`[pipelex.templating_config].default_templating_style`, shipped as `xml`). It is no longer derived from model metadata, so the same method renders the same prompt shape on every model. **Every prompt rendered for an OpenAI-family model changes shape, from back-tick fences to XML tags.** `PipelexKernel.llm_text` and `llm_object` take the same optional argument.- **Compose, image-generation, search and structuring prompts follow the same default (Breaking)**: These paths previously rendered style-less, which the Jinja2 filters silently absorbed as triple-backticks and plain text. They now resolve the same runtime default as the LLM path. Any template of yours that uses `| tag` — including `PipeCompose` templates and construct-mode template fields — changes shape accordingly, whichever model family you run on.diff --git a/Makefile b/Makefileindex 6a5828fd8..f651794de 100644--- a/Makefile+++ b/Makefile@@ -108,6 +108,8 @@ make check-migration-schemas - Check configuration surfaces have accounted formake cmig - Shorthand -> check-migration-schemasmake up-migration-schemas - Regenerate the migration fingerprint and defaults goldensmake umig - Shorthand -> up-migration-schemas+make up-migration-schemas-force - Same, over a head golden recording material the models lost+make umigf - Shorthand -> up-migration-schemas-forcemake generate-error-pages - Generate one docs page per PipelexError subclass under docs/errors/make gep - Shorthand -> generate-error-pagesmake generate-error-identity - Regenerate the committed PipelexError wire-identity snapshot@@ -120,7 +122,7 @@ make regenerate-test-models - Regenerate test model fixtures from backend confmake rtm - Shorthand -> regenerate-test-modelsmake insert-skeleton - Insert skeleton from $(SKELETON_DIR)-make up - Shorthand -> generate-mthds-schema update-gateway-models up-kit-configs up-migration-schemas rules+make up - Shorthand -> generate-mthds-schema update-gateway-models up-kit-configs rulesmake cleanenv - Remove virtual envmake cleanderived - Remove extraneous compiled files, caches, logs, etc.make cleanall - Remove all -> cleanenv + cleanderived@@ -217,7 +219,7 @@ export HELPli check-unused-imports fix-unused-imports check-TODOs check-uv \docs docs-check docs-serve-versioned docs-list docs-deploy docs-deploy-stable docs-deploy-specific-version docs-delete \generate-mthds-schema generate-mthds-schema-quiet gms check-mthds-schema cms \- check-ledger cl check-migration-schemas cmig up-migration-schemas up-migration-schemas-quiet umig \+ check-ledger cl check-migration-schemas cmig up-migration-schemas up-migration-schemas-force umig umigf \generate-error-pages generate-error-pages-quiet gep \generate-error-identity generate-error-identity-quiet gei \update-gateway-models update-gateway-models-quiet ugm check-gateway-models cgm up \@@ -434,12 +436,16 @@ up-migration-schemas: env$(call PRINT_TITLE,"Updating migration fingerprint and defaults goldens")$(VENV_PIPELEX_DEV) update-migration-schemas-up-migration-schemas-quiet: env- $(VENV_PIPELEX_DEV) update-migration-schemas --quiet+up-migration-schemas-force: env+ $(call PRINT_TITLE,"Re-recording migration goldens over material the models lost")+ $(VENV_PIPELEX_DEV) update-migration-schemas --forceumig: up-migration-schemas@echo "> done: umig = up-migration-schemas"+umigf: up-migration-schemas-force+ @echo "> done: umigf = up-migration-schemas-force"+generate-error-pages: env$(call PRINT_TITLE,"Generating per-class error documentation pages")$(VENV_PIPELEX_DEV) generate-error-pages@@ -1187,8 +1193,12 @@ c: check-keyword-only format lint pyright mypycc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet c@echo "> done: cc = cleanderived regenerate-test-models generate-mthds-schema update-gateway-models format lint pyright mypy"-up: generate-mthds-schema-quiet update-gateway-models-quiet up-kit-configs up-migration-schemas-quiet rules- @echo "> done: up = generate-mthds-schema update-gateway-models up-kit-configs up-migration-schemas rules"+# `up-migration-schemas` is deliberately NOT part of this aggregate. Every other regenerator here+# rewrites a derived artifact from a live source; the migration head golden is a *proof obligation*+# the coverage gate reads, so folding it into a habitual bulk regeneration would let a removal be+# erased by muscle memory. Run `make umig` on purpose, and read its diff.+up: generate-mthds-schema-quiet update-gateway-models-quiet up-kit-configs rules+ @echo "> done: up = generate-mthds-schema update-gateway-models up-kit-configs rules"check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-ledger check-migration-schemas check-keyword-only check-hub-layering drift-check format lint pyright mypy pylint@echo "> done: check"diff --git a/docs/errors/migration-snapshot-refused-error.md b/docs/errors/migration-snapshot-refused-error.mdnew file mode 100644index 000000000..2e379efa1--- /dev/null+++ b/docs/errors/migration-snapshot-refused-error.md@@ -0,0 +1,21 @@+---+title: "Migration snapshot refused"+description: "Reference for the `MigrationSnapshotRefusedError` Pipelex error class."+---++<!-- pipelex:generated -->++# Migration snapshot refused++The regenerator refused to overwrite a head golden that records material the models lost.++| Field | Value |+|---|---|+| `error_type` | `MigrationSnapshotRefusedError` |+| `title` | Migration snapshot refused |+| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-snapshot-refused-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.migration.exceptions` |+| Parent class | [`MigrationError`](migration-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.mdindex 313e98a24..1d24326e4 100644--- a/docs/errors/platform-and-tooling.md+++ b/docs/errors/platform-and-tooling.md@@ -108,5 +108,6 @@ own page. Classes are grouped by subsystem.- [`MigrationGoldenError`](migration-golden-error.md) — Migration golden error- [`MigrationLedgerError`](migration-ledger-error.md) — Migration ledger error- [`MigrationRegistryError`](migration-registry-error.md) — Migration registry error+- [`MigrationSnapshotRefusedError`](migration-snapshot-refused-error.md) — Migration snapshot refused[Back to Error Reference](index.md)diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex b4db03dda..ea600455d 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -206,6 +206,10 @@ Some configuration nodes are **open dictionaries** — fields typed as a mapping> **`move_key` takes no wildcard on either side.** A wildcard destination names no target: "move each entry's key into *some* entry" has no rule for which entry receives it. A wildcard *source* with the fixed destination that leaves it is many-to-one: on any file where two matched entries carry the key, the second lands on the destination the first just occupied and the whole operation conflicts. Both are refused when the ledger is parsed. The other kinds act on each matched entry in place, which is what makes a wildcard mean something for them.+> **A `key` may be `*` on `remap_value` and nowhere else.** In a `table_path` the segment expands over the tables at an open node; as a *key* it means "each key of the addressed table", and only a remap has a per-key answer to give. That reading is not a convenience: a mapping from the user's own keys to an enumerated value — `dict[str, LogLevel]` — keeps its spellings under keys only the document can enumerate, so no fixed key reaches them and this is the only shape in which a member renamed beneath an open mapping can be repaired at all. On the other kinds it is refused when the ledger is parsed: deleting every key of a table is `delete_table`, and renaming or moving every key onto one fixed name is the same many-to-one that rules the wildcard out of a `move_key`. Refused rather than tolerated, because an unrefused one is a *dead* operation — the applier looks up a key literally spelled `*`, never finds it, and reports a guarded skip forever.++> **A remap only reaches a path whose own value is a string.** A `list[enum]` holds a list, so a remap on it is a guarded skip on every run: the coverage gate does not credit one there, and names `unsafe` as the only remedy rather than sending an author to write an operation they will never see fire.+### OutcomesThe applier reports one outcome per operation:@@ -280,12 +284,20 @@ The bounds are recorded beside the type instead, and the same principle decides> **`pattern` is excluded, permanently.** Regex containment is not decidable for real expressions, so a gate that compared patterns would read every pattern edit as a tightening, produce false positives on changes that break nobody, and be waved through until it caught nothing. There are no `pattern` constraints on any surface today, so saying so costs nothing.-A bound is read from two places, because a bound written the ordinary way appears in neither the other: pydantic folds a top-level `Field(ge=1)` into the field's *metadata*, leaving the annotation bare, while a bound inside a union member (`Annotated[int, Field(ge=1)] | Literal["unbounded"]`) stays in the annotation. A generic container's arguments are deliberately not descended into — a bound inside `list[Annotated[int, Field(ge=1)]]` binds the items, not the list. Across union members the widest bound wins, since a union's value domain is the union of its members' and a bound on one never binds the others.+A bound is read from two places, because a bound written the ordinary way appears in neither the other: pydantic folds a top-level `Field(ge=1)` into the field's *metadata*, leaving the annotation bare, while a bound inside a union member (`Annotated[int, Field(ge=1)] | Literal["unbounded"]`) stays in the annotation. A generic container's arguments are deliberately not descended into — a bound inside `list[Annotated[int, Field(ge=1)]]` binds the items, not the list.++> **The two sources do not merge the same way, because they do not mean the same thing.** A bound in the field's metadata **binds**: pydantic applies it to the whole field, on top of whatever a member declares, so several of one kind intersect and the strictest is what a file meets. A bound inside a union member binds that member alone, so across members the widest wins — a union accepts a value if any member does. The two merged maps are then intersected, because a value must satisfy the binding bound *and* land inside some member's domain. Merging them into one pool and taking the widest recorded `le=100` for a field whose own `Field(le=6)` was the real ceiling, and a later tightening of that ceiling then read as a change to an already-looser one: the gate going quiet on exactly the values that stop validating.++Across members one overclaim is deliberate: a kind present on some members and not others is kept rather than dropped, though the honest union of an `int` bounded below with an unbounded member is unbounded. Dropping it would blind the gate to a tightening on the common `Annotated[int, Field(ge=1)] | Literal["auto"]` shape, where the literal member can carry no numeric bound at all. It is symmetric on both fingerprints, so it can report a tightening that is not one only if the *shape* of the union changes, never invent one out of a bound that moved.An enumerated member set is collected from both sources that produce one: an enum class and a string literal type. To a TOML file they are the same thing — a closed set of legal spellings — and either can lose one. A member is only *lost*, though, when the new shape stops accepting it — that is, when the new type does not admit `str`: an enumerated type relaxed into a free string records no members afterwards, and reading that raw set difference as the loss of every spelling would demand a bump and a remap for the most benign loosening a configuration model can undergo. The exemption is exactly that shape and not "the type did not change": `Literal['a']` becoming `Literal[1]` renders the same type on both sides and records no members after, and it loses `'a'`. A literal over non-string values records no members at all — its domain is one more thing the projection does not see.+> **Members beneath an open mapping are recorded on the wildcard record, not on the mapping.** `dict[str, LogLevel]` records its spellings at `levels.*`, whose own value is the enumerated one, and records none at `levels`, whose value is a table. Recording them twice made the coverage gate demand a `remap_value` at the mapping's own path as well, and a remap of a table value is a guarded skip on every run — a demand with no legal answer. Every *other* container is still descended into, because it has no such child record: a `list[enum]` keeps its members on the list's own path, where they are the only thing that makes a member lost inside one visible at all.+Two shapes are recorded as terminal rather than descended into, because no operation can address what lies beneath them: an array of tables, which has no path segment syntax and no wildcard form, and a model reachable from itself, which has no finite path set at all. Terminal means blind: a change to the model beneath an array of tables leaves the fingerprint unchanged, and the telemetry surface's `otlp` exporters are that shape today (see [Limits you will meet](#limits-you-will-meet)).+> **The array-of-tables blind spot stays, and the reason is that closing it would produce a demand nothing can answer.** Recording an item model's fields under a synthetic segment would make a renamed field inside an exporter entry visible to the coverage gate — and then demanded, with no operation in the vocabulary able to reach it and no remedy an author could write. A gate whose refusal has no legal answer is worse than a blind spot the contract names. Revisit on the day an addressing syntax for arrays of tables exists, and not before: the two are one change.+**What the fingerprint records is what the types say, and a validator can say something else.** Every recorded field is read from an annotation or from the metadata beside it, so a constraint expressed as a validator instead is invisible here — and that is not a corner case, it reaches the enum member set and the open-node marker alike. A telemetry mode is a member of the recorded set and is still rejected unless the document also carries the user id that mode requires. Several nodes typed `dict[str, X]` on the main configuration surface reject any key outside a fixed set, so the open-node marker claims a key space that is not the user's after all. A pair of validators demands every member of an enum as a key of every entry of an open mapping, which makes *adding* an enum member break a user's file — additively, as far as any projection can tell. Nothing here can be made to see any of it.> **The gate does not claim what it cannot see.** Domain narrowing expressed in a validator — a non-empty check, a cross-field invariant, a completeness rule over user-supplied keys — is not visible from the schema and stays the author's responsibility. The [coverage gate](#coverage-every-schema-change-is-accounted-for) catches the mechanical subset: types and the whitelisted bounds. It does not catch the rest, and the coverage table would overclaim without this sentence.@@ -373,10 +385,13 @@ Without this, every legitimate configuration change turns the gate's own suite r|---|---|---|---|| `make check-ledger` | `cl` | `check`, `agent-check` | The ledger parses into migration operations, versions are contiguous and match ids, legality and remap legality hold, no entry reintroduces a reserved path, and replay over both reference documents applies nothing. Reads checked-in data only — no live model is fingerprinted and nothing is regenerated. || `make check-migration-schemas` | `cmig` | `check` | Fingerprints every surface, diffs against the goldens, demands a bump and full accounting for every removal, cross-checks destinations, and verifies the pairwise transform-golden chain. |-| `make up-migration-schemas` | `umig` | `up` | Regenerates the fingerprint goldens, and snapshots the reference documents into the transform-golden chain when a schema version bumped. |+| `make up-migration-schemas` | `umig` | — | Regenerates the fingerprint goldens, and snapshots the reference documents into the transform-golden chain when a schema version bumped. Refuses a head golden whose material the models have lost. |+| `make up-migration-schemas-force` | `umigf` | — | The same, over that refusal. For a change to the fingerprint *format* on an unreleased schema version, and nothing else. |Only `check-ledger` joins `agent-check`: it regenerates nothing and each failure has one obvious next action. `check-migration-schemas` is a golden check, and in the loop agents run constantly it would produce a fail-regenerate-fail cycle with no single right answer, so it stays in `check` alone.+> **The regenerator is not part of `make up`, and refuses to erase a removal.** Every other regenerator in that aggregate rewrites a derived artifact from a live source, so running them all out of habit is harmless. The head fingerprint golden is not derived — it is the *proof obligation* the coverage gate compares against, and rewriting it after deleting a field erases the very removal the gate exists to catch, leaving it green over a change that breaks every user's file. So the target is run on purpose and its diff is read, and it stops before overwriting a head golden that records a path, an enumerated spelling or a value domain the models no longer have. The refusal names both readings — a real removal wants a bump and an entry; a golden that merely predates a change to the fingerprint format wants `make umigf` — because the code cannot tell them apart and picking one on the author's behalf is how the wrong one gets chosen.+The checked-in data it all reads:```diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.pyindex b830bac1c..4b46aafc4 100644--- a/pipelex/cli/dev_cli/_dev_cli.py+++ b/pipelex/cli/dev_cli/_dev_cli.py@@ -332,10 +332,11 @@ def check_migration_schemas_command(@app.command(name="update-migration-schemas", help="Regenerate the migration fingerprint and defaults goldens")def update_migration_schemas_command(quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Output only a single status line")] = False,+ force: Annotated[bool, typer.Option("--force", help="Overwrite a head golden that records material the models lost")] = False,) -> None:"""Regenerate the migration golden chain for every configuration surface."""try:- update_migration_schemas_cmd(quiet=quiet)+ update_migration_schemas_cmd(quiet=quiet, force=force)except (typer.Exit, typer.Abort):# Typer control-flow exits carry an intended exit code — not a failure. Let them through.raisediff --git a/pipelex/cli/dev_cli/commands/update_migration_schemas_cmd.py b/pipelex/cli/dev_cli/commands/update_migration_schemas_cmd.pyindex 743149edf..a1386cfe9 100644--- a/pipelex/cli/dev_cli/commands/update_migration_schemas_cmd.py+++ b/pipelex/cli/dev_cli/commands/update_migration_schemas_cmd.py@@ -2,7 +2,8 @@Writes each surface's fingerprint and complete reference document for the schema version itsledger currently declares. Older versions are never rewritten — a bump leaves the previous-version's snapshot behind as the frozen history the chain is made of.+version's snapshot behind as the frozen history the chain is made of — and the head version is+only rewritten when doing so erases nothing (see `pipelex/migration/snapshot.py`).The regeneration diff is the point. A fingerprint golden is checked in so that a reviewer sees,line by line, which paths a change added, removed or renamed; running this command without reading@@ -19,11 +20,14 @@ from pipelex.migration.surfaces import build_config_surface_registry, packaged_mfrom pipelex.runtime_hub import get_console-def update_migration_schemas_cmd(*, quiet: bool = False) -> None:+def update_migration_schemas_cmd(*, quiet: bool = False, force: bool = False) -> None:"""Regenerate the fingerprint and defaults goldens for every configuration surface.Args:quiet: If True, output only a single status line (for use in Make targets).+ force: If True, overwrite a head golden even when the models have lost material it+ records. Reserved for a change to the fingerprint *format* over an unreleased schema+ version; a real removal wants a bump and an entry instead."""console = get_console()@@ -34,7 +38,7 @@ def update_migration_schemas_cmd(*, quiet: bool = False) -> None:registry = build_config_surface_registry()try:- snapshots = snapshot_registry(registry=registry, migration_dir=packaged_migration_dir())+ snapshots = snapshot_registry(registry=registry, migration_dir=packaged_migration_dir(), force=force)except MigrationError as exc:console.print(f"[red]✗ Migration schema update: FAILED[/red] - {escape(str(exc))}")sys.exit(1)diff --git a/pipelex/migration/coverage.py b/pipelex/migration/coverage.pyindex f6ef386ad..41fdca41e 100644--- a/pipelex/migration/coverage.py+++ b/pipelex/migration/coverage.py@@ -46,7 +46,7 @@ from pydantic import BaseModel, ConfigDict, Fieldfrom pipelex.migration.fingerprint import PATH_SEPARATOR, TABLE_TYPE, SurfaceFingerprint, compute_fingerprintfrom pipelex.migration.goldens import defaults_golden_path, read_fingerprint_goldenfrom pipelex.migration.ledger import MigrationEntry, MigrationLedger, MigrationSafety, load_ledger-from pipelex.migration.narrowing import describe_narrowing, lost_enumerated_spellings+from pipelex.migration.narrowing import describe_narrowing, is_remappable, lost_enumerated_spellingsfrom pipelex.migration.surfaces import Surface, SurfaceRegistryfrom pipelex.migration.walk import EntryWalk, walk_entryfrom pipelex.suggested_fix import WILDCARD_SEGMENT@@ -298,15 +298,24 @@ def _check_enum_accounting(# check has already said so in terms the author can act on.continueremoved_members = set(lost_enumerated_spellings(before=before_record, after=after_record))- unaccounted = sorted(removed_members - remapped_by_origin.get(origin, set()))+ # A remap only reaches a path whose own value is a string. Where it cannot — an enumerated+ # type inside a list — crediting one would be crediting an operation that skips on every+ # run, and offering one as a remedy would send the author to write it and never see it fire.+ reachable = is_remappable(record=before_record)+ unaccounted = sorted(removed_members - remapped_by_origin.get(origin, set())) if reachable else sorted(removed_members)if unaccounted:+ remedy = (+ "so the entry needs a remap_value for each, or must be marked unsafe"+ if reachable+ else "and no operation can rewrite a value inside a container, so the entry must be marked unsafe"+ )issues.append(CoverageIssue(surface_id=surface_id,kind=CoverageIssueKind.ENUM_MEMBER_NOT_REMAPPED,message=(f"entry '{entry.id}': '{final_path}' no longer accepts {unaccounted} — a file carrying one of those "- f"values no longer validates, so the entry needs a remap_value for each, or must be marked unsafe"+ f"values no longer validates, {remedy}"),))@@ -567,7 +576,8 @@ def _check_head_link(*, surface_id: str, current_version: int, live: SurfaceFingmessage=(f"the models no longer have {diff.render_removals()}, which breaks every file that carries them. Bump "f"current_schema_version to {current_version + 1}, add the entry '{surface_id}@{current_version + 1}' "- f"accounting for each, then run `make umig`"+ f"accounting for each, then run `make umig` — or, if schema version {current_version} has not been "+ f"released and the golden merely predates a change to the fingerprint format, re-record it with `make umigf`"),))@@ -584,7 +594,9 @@ def _check_head_link(*, surface_id: str, current_version: int, live: SurfaceFingf"{diff.render_narrowings()}. A file valid before this change is not valid after it, so this is a "f"removal like any other. Bump current_schema_version to {current_version + 1}, add the entry "f"'{surface_id}@{current_version + 1}' carrying a remap_value for each narrowed path — or marked "- f"unsafe, where no remap can express it — then run `make umig`"+ f"unsafe, where no remap can express it — then run `make umig`. If schema version {current_version} "+ f"has not been released and the golden merely predates a change to the fingerprint format, re-record "+ f"it with `make umigf` instead"),))diff --git a/pipelex/migration/exceptions.py b/pipelex/migration/exceptions.pyindex 3aca4dde3..1e7b02b2d 100644--- a/pipelex/migration/exceptions.py+++ b/pipelex/migration/exceptions.py@@ -24,3 +24,13 @@ class MigrationGoldenError(MigrationError):"""A checked-in golden is missing or unreadable, so no verdict can be produced."""_declared_title = "Migration golden error"+++class MigrationSnapshotRefusedError(MigrationError):+ """The regenerator refused to overwrite a head golden that records material the models lost.++ Raised so that a habitual regeneration cannot quietly erase the very removal the coverage gate+ exists to catch. The refusal names both readings of the situation and the flag that resolves it.+ """++ _declared_title = "Migration snapshot refused"diff --git a/pipelex/migration/fingerprint.py b/pipelex/migration/fingerprint.pyindex 7e7749ecc..2786ed4ee 100644--- a/pipelex/migration/fingerprint.py+++ b/pipelex/migration/fingerprint.py@@ -54,6 +54,13 @@ LITERAL_TYPE = "literal"STRING_TYPE = "str""""The rendering of `str` — the type every enumerated spelling widens into."""+INTEGER_TYPE = "int"+"""The rendering of `int`. Named because two relations read it: `int` widens into `float`, and a+bound over the integers has two equivalent spellings (`gt=n` and `ge=n+1`)."""++REAL_TYPE = "float"+"""The rendering of `float` — the type every integer widens into, strict validation included."""+class ConstraintKind(StrEnum):"""The closed whitelist of constraint kinds the fingerprint records.@@ -337,46 +344,77 @@ def _render_bare(*, annotation: Any) -> str:def _collect_constraints(*, annotation: Any, field_metadata: Sequence[Any]) -> dict[ConstraintKind, int | float] | None:- """The whitelisted bounds on one path's value, merged across the annotation's union members.-- Two sources are read and no others: the field's own metadata, which is where a top-level- `Field(ge=1)` ends up, and the `Annotated` wrappers reachable through unions — the shape- `Annotated[int, Field(ge=1)] | Literal["unbounded"]` that the walk would otherwise miss.+ """The whitelisted bounds on one path's value — what the schema really lets a file carry.++ Two sources are read and no others, and **they do not merge the same way**, because they do+ not mean the same thing:++ - The **binding** source is the field's own metadata plus any `Annotated` wrapper outside the+ union — where a top-level `Field(ge=1)` ends up. Pydantic applies it to the whole field, on+ top of whatever a member declares, so several binding bounds of one kind intersect and the+ *strictest* is the one a file meets.+ - The **member** source is the `Annotated` wrappers reachable inside a union's members — the+ shape `Annotated[int, Field(ge=1)] | Literal["unbounded"]`. A union accepts a value if any+ member does, so a bound on one member never binds the others and the *widest* is the one+ the path really has.++ Mixing the two pools into one and taking the widest was the hole: a binding `Field(le=6)`+ beside a member's own `le=100` recorded `le=100`, and a later tightening of the binding bound+ then read as a change to an already-looser one — the gate going quiet on exactly the values+ that stop validating. The two pools are merged separately and then intersected, since a value+ must satisfy the binding bound *and* some member's.A generic container's arguments are deliberately **not** descended into. A bound inside`list[Annotated[int, Field(ge=1)]]` binds the items, not the list, and recording it at thelist's path would attribute to one path a constraint belonging to another — the value schemabeneath an open node gets its own `*` record and its own constraints there."""- carriers: list[Any] = list(field_metadata)- _gather_constraint_carriers(annotation=annotation, carriers=carriers)- collected: dict[ConstraintKind, int | float] = {}- _absorb_constraint_carriers(carriers=carriers, collected=collected)+ binding_carriers: list[Any] = list(field_metadata)+ member_pools: list[list[Any]] = []+ _split_constraint_carriers(annotation=annotation, binding_carriers=binding_carriers, member_pools=member_pools)++ collected = _merge_carriers(carriers=binding_carriers, keep_widest=False)+ across_members: dict[ConstraintKind, int | float] = {}+ for pool in member_pools:+ _fold_bound(collected=across_members, other=_merge_carriers(carriers=pool, keep_widest=False), keep_widest=True)+ # The two pools intersect: a value must satisfy the binding bound *and* land inside some+ # member's domain, so the strictest of the two is what a file actually meets.+ _fold_bound(collected=collected, other=across_members, keep_widest=False)return {kind: collected[kind] for kind in sorted(collected)} if collected else None-def _gather_constraint_carriers(*, annotation: Any, carriers: list[Any]) -> None:+def _split_constraint_carriers(*, annotation: Any, binding_carriers: list[Any], member_pools: list[list[Any]]) -> None:+ """Sort an annotation's constraint carriers into the binding pool and one pool per union member.++ An `Annotated` wrapper met before any union binds the whole field; one met inside a member+ binds that member alone. A union nested inside a union is flat — a union of unions accepts+ exactly what the flattened one does — so its members become sibling pools.+ """if get_origin(annotation) is Annotated:args = get_args(annotation)- carriers.extend(args[1:])- _gather_constraint_carriers(annotation=args[0], carriers=carriers)+ binding_carriers.extend(args[1:])+ _split_constraint_carriers(annotation=args[0], binding_carriers=binding_carriers, member_pools=member_pools)returnif _is_union(annotation=annotation):for member in get_args(annotation):- _gather_constraint_carriers(annotation=member, carriers=carriers)+ pool: list[Any] = []+ _split_constraint_carriers(annotation=member, binding_carriers=pool, member_pools=member_pools)+ if pool:+ member_pools.append(pool)-def _absorb_constraint_carriers(*, carriers: Sequence[Any], collected: dict[ConstraintKind, int | float]) -> None:- """Fold every carrier the whitelist recognizes into the projection, and drop the rest silently.+def _merge_carriers(*, carriers: Sequence[Any], keep_widest: bool) -> dict[ConstraintKind, int | float]:+ """Fold every carrier the whitelist recognizes into a bound map, dropping the rest silently.Dropping is the whole point: a carrier this function does not recognize — a strictness flag, abefore-validator, a pattern object, a kind a future release invents — must leave no trace inthe golden, or the gate starts moving for reasons that are not about our schema."""+ collected: dict[ConstraintKind, int | float] = {}for carrier in carriers:if isinstance(carrier, FieldInfo):# `Field(...)` inside an `Annotated` arrives as a `FieldInfo` carrying its own metadata.- _absorb_constraint_carriers(carriers=carrier.metadata, collected=collected)+ _fold_bound(collected=collected, other=_merge_carriers(carriers=carrier.metadata, keep_widest=keep_widest), keep_widest=keep_widest)continuekind = CONSTRAINT_ATTRIBUTE_BY_CARRIER.get(cast("type[Any]", type(carrier)))if kind is None:@@ -386,13 +424,26 @@ def _absorb_constraint_carriers(*, carriers: Sequence[Any], collected: dict[Cons# A bound expressed over dates, decimals or anything else is outside the projection:# it has no stable rendering here and no comparison this gate could make.continue+ _fold_bound(collected=collected, other={kind: value}, keep_widest=keep_widest)+ return collected+++def _fold_bound(*, collected: dict[ConstraintKind, int | float], other: dict[ConstraintKind, int | float], keep_widest: bool) -> None:+ """Merge one bound map into another, keeping the widest or the strictest of each kind.++ A kind present on only one side is kept as it is. For the member pools that is a deliberate+ overclaim — a union member with no bound of that kind is unbounded in it, so the honest union+ would drop the kind entirely — and the overclaim is what keeps a tightening visible on the+ common `Annotated[int, Field(ge=1)] | Literal["auto"]` shape, where the literal member can+ carry no numeric bound at all. Symmetric on both fingerprints, so it cannot invent a narrowing.+ """+ for kind, value in other.items():existing = collected.get(kind)if existing is None:collected[kind] = value- elif kind.widest_is_the_lower_value:- collected[kind] = min(existing, value)- else:- collected[kind] = max(existing, value)+ continue+ prefer_lower = kind.widest_is_the_lower_value if keep_widest else not kind.widest_is_the_lower_value+ collected[kind] = min(existing, value) if prefer_lower else max(existing, value)def _collect_enum_members(*, annotation: Any) -> list[str] | None:@@ -414,6 +465,14 @@ def _gather_enum_members(*, annotation: Any, members: set[str]) -> None:if get_origin(annotation) is Literal:members.update(str(arg) for arg in get_args(annotation) if isinstance(arg, str))return+ if _as_open_mapping_value(annotation=annotation) is not None:+ # The value schema of an open mapping gets its own record beneath the `*` segment, and its+ # members belong there. Recording them on the container as well made the coverage gate+ # demand a `remap_value` at a path whose value is a table — an operation that can never+ # fire, so the demand had no answer an author could give. Descending into every *other*+ # container stays right: a `list[enum]` gets no child record, so a member lost inside one+ # would otherwise be invisible.+ returnfor arg in get_args(annotation):_gather_enum_members(annotation=arg, members=members)diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]index 507d2c72f..0be9e70fc 100644--- a/pipelex/migration/goldens/pipelex-config/[email protected]+++ b/pipelex/migration/goldens/pipelex-config/[email protected]@@ -692,16 +692,6 @@"pipelex.log_config.package_log_levels": {"value_type": "dict[str, enum]","required": true,- "enum_members": [- "CRITICAL",- "DEBUG",- "DEV",- "ERROR",- "INFO",- "OFF",- "VERBOSE",- "WARNING"- ],"default": {"anthropic": "INFO","asyncio": "INFO",diff --git a/pipelex/migration/narrowing.py b/pipelex/migration/narrowing.pyindex ee62153bb..77a6558d6 100644--- a/pipelex/migration/narrowing.py+++ b/pipelex/migration/narrowing.py@@ -26,13 +26,24 @@ string is read as the widening it is instead of as the loss of every member it hfrom fractions import Fraction-from pipelex.migration.fingerprint import ENUM_TYPE, LITERAL_TYPE, STRING_TYPE, UNION_SEPARATOR, ConstraintKind, PathFingerprint+from pipelex.migration.fingerprint import (+ ENUM_TYPE,+ INTEGER_TYPE,+ LITERAL_TYPE,+ REAL_TYPE,+ STRING_TYPE,+ UNION_SEPARATOR,+ ConstraintKind,+ PathFingerprint,+)_LOWER_VALUE_BOUND_KINDS: tuple[tuple[ConstraintKind, bool], ...] = ((ConstraintKind.GT, True), (ConstraintKind.GE, False))_UPPER_VALUE_BOUND_KINDS: tuple[tuple[ConstraintKind, bool], ...] = ((ConstraintKind.LT, True), (ConstraintKind.LE, False))_LOWER_LENGTH_BOUND_KINDS: tuple[tuple[ConstraintKind, bool], ...] = ((ConstraintKind.MIN_LENGTH, False),)_UPPER_LENGTH_BOUND_KINDS: tuple[tuple[ConstraintKind, bool], ...] = ((ConstraintKind.MAX_LENGTH, False),)_STRING_TYPED_MEMBERS: frozenset[str] = frozenset({STRING_TYPE, ENUM_TYPE, LITERAL_TYPE})+_ENUMERATED_MEMBERS: frozenset[str] = frozenset({ENUM_TYPE, LITERAL_TYPE})+_ARGUMENT_SEPARATOR = ", "def describe_narrowing(*, before: PathFingerprint, after: PathFingerprint, remapped: bool = False) -> list[str]:@@ -51,7 +62,13 @@ def describe_narrowing(*, before: PathFingerprint, after: PathFingerprint, remapexempt = _STRING_TYPED_MEMBERS if remapped else frozenset[str]()if before.value_type != after.value_type and not _is_type_widening(before=before.value_type, after=after.value_type, exempt=exempt):reasons.append(f"its type went from '{before.value_type}' to '{after.value_type}'")- reasons.extend(_describe_tightenings(before=before.constraints or {}, after=after.constraints or {}))+ reasons.extend(+ _describe_tightenings(+ before=before.constraints or {},+ after=after.constraints or {},+ over_integers=_is_integral(rendered=before.value_type) and _is_integral(rendered=after.value_type),+ )+ )return reasons@@ -74,6 +91,20 @@ def lost_enumerated_spellings(*, before: PathFingerprint, after: PathFingerprintreturn sorted(set(before.enum_members) - set(after.enum_members or []))+def is_remappable(*, record: PathFingerprint) -> bool:+ """Whether a `remap_value` on this path can ever rewrite anything.++ The operation rewrites a *string* value, so it reaches a path whose own value is string-typed+ — `str`, `enum`, `literal`, or a union carrying one. A `list[enum]` is not: its value is a+ list, so the operation is a guarded skip on every run. Crediting such a remap in the+ accounting would leave a green gate over a file that stops validating, and offering it as a+ remedy would send the author to write an operation they will never see fire. The enumerated+ members beneath an *open mapping* are recorded on that mapping's `*` child, whose own value+ is the enumerated one, so they are remappable there — through `key = "*"`.+ """+ return bool(_union_members(rendered=record.value_type) & _STRING_TYPED_MEMBERS)++def _is_type_widening(*, before: str, after: str, exempt: frozenset[str]) -> bool:"""Whether every value the old type accepted the new one still accepts.@@ -89,9 +120,51 @@ def _is_type_widening(*, before: str, after: str, exempt: frozenset[str]) -> boodef _is_member_absorbed(*, member: str, after_members: set[str]) -> bool:+ """Whether one old union member's values all survive somewhere in the new type.++ Four readings, and each closes a shape the plain set comparison called a narrowing while every+ file survived it:++ - the member is still there verbatim;+ - an enumerated member (`enum`, `literal`) absorbed by `str`, or by the *other* enumerated+ rendering — `enum` and `literal` are two spellings of one thing, a closed set of string+ values, and what moved between two member *sets* is reported by `lost_enumerated_spellings`+ rather than by this half;+ - `int` absorbed by `float`, which accepts every integer, in strict validation as well as lax;+ - a container whose head and arity are unchanged and each of whose arguments is itself+ absorbed — `list[int]` becoming `list[int | str]` widens the list.+ """if member in after_members:return True- return member in {ENUM_TYPE, LITERAL_TYPE} and STRING_TYPE in after_members+ if member in _ENUMERATED_MEMBERS and (STRING_TYPE in after_members or after_members & _ENUMERATED_MEMBERS):+ return True+ if member == INTEGER_TYPE and REAL_TYPE in after_members:+ return True+ return any(_is_container_widening(before=member, after=candidate) for candidate in after_members)+++def _is_container_widening(*, before: str, after: str) -> bool:+ """Whether two rendered container types have the same shape and every argument widened."""+ before_head, before_args = _split_container(rendered=before)+ after_head, after_args = _split_container(rendered=after)+ if before_head is None or before_head != after_head or len(before_args) != len(after_args):+ return False+ return all(+ _is_type_widening(before=before_arg, after=after_arg, exempt=frozenset[str]())+ for before_arg, after_arg in zip(before_args, after_args, strict=True)+ )+++def _split_container(*, rendered: str) -> tuple[str | None, list[str]]:+ """A rendered `head[arg, arg]` split into its head and its top-level arguments.++ `(None, [])` for anything that is not a parameterized container, which is what makes the+ caller's comparison say "not the same shape" rather than "no arguments, so vacuously equal".+ """+ if not rendered.endswith("]") or "[" not in rendered:+ return None, []+ head, _, inside = rendered.partition("[")+ return head, _split_top_level(rendered=inside[:-1], separator=_ARGUMENT_SEPARATOR)def _union_members(*, rendered: str) -> set[str]:@@ -100,7 +173,12 @@ def _union_members(*, rendered: str) -> set[str]:Splitting has to respect brackets: `list[int | str]` is one member, not two, and treating itas two would let a genuine narrowing inside a container read as a widening."""- members: set[str] = set()+ return set(_split_top_level(rendered=rendered, separator=UNION_SEPARATOR))+++def _split_top_level(*, rendered: str, separator: str) -> list[str]:+ """Split a rendered type on a separator that appears outside every bracket pair, in order."""+ parts: list[str] = []depth = 0current = ""for character in rendered:@@ -109,30 +187,45 @@ def _union_members(*, rendered: str) -> set[str]:elif character == "]":depth -= 1current += character- if depth == 0 and current.endswith(UNION_SEPARATOR):- members.add(current[: -len(UNION_SEPARATOR)])+ if depth == 0 and current.endswith(separator):+ parts.append(current[: -len(separator)])current = ""- members.add(current)- return members+ parts.append(current)+ return parts++def _is_integral(*, rendered: str) -> bool:+ """Whether every numeric value this type accepts is a whole number.-def _describe_tightenings(*, before: dict[ConstraintKind, int | float], after: dict[ConstraintKind, int | float]) -> list[str]:+ Only then are `gt=n` and `ge=n+1` the same bound. The string-typed members are set aside — a+ real shape is `int | literal`, where the literal spellings are not what a numeric bound is+ about — and what remains has to be exactly `int`.+ """+ numeric_members = _union_members(rendered=rendered) - _STRING_TYPED_MEMBERS+ return numeric_members == {INTEGER_TYPE}+++def _describe_tightenings(*, before: dict[ConstraintKind, int | float], after: dict[ConstraintKind, int | float], over_integers: bool) -> list[str]:"""Every bound family whose new form admits fewer values than its old one.A bound that appears where there was none is a tightening; one that disappears is a wideningand says nothing. The `gt`/`ge` pair is compared as a single lower bound rather than key bykey, so swapping `gt=0` for `ge=0` reads as the widening it is instead of one key vanishingand another appearing.++ ``over_integers`` says the path's numeric values are whole numbers, which makes `gt=n` and+ `ge=n+1` the same bound. Length bounds are counts and are integral whatever the value type is,+ so they are compared that way always."""reasons: list[str] = []- for label, kinds, sign in (- ("lower bound", _LOWER_VALUE_BOUND_KINDS, 1.0),- ("upper bound", _UPPER_VALUE_BOUND_KINDS, -1.0),- ("minimum length", _LOWER_LENGTH_BOUND_KINDS, 1.0),- ("maximum length", _UPPER_LENGTH_BOUND_KINDS, -1.0),+ for label, kinds, sign, integral in (+ ("lower bound", _LOWER_VALUE_BOUND_KINDS, 1.0, over_integers),+ ("upper bound", _UPPER_VALUE_BOUND_KINDS, -1.0, over_integers),+ ("minimum length", _LOWER_LENGTH_BOUND_KINDS, 1.0, True),+ ("maximum length", _UPPER_LENGTH_BOUND_KINDS, -1.0, True),):- before_bound = _strictest_bound(constraints=before, kinds=kinds, sign=sign)- after_bound = _strictest_bound(constraints=after, kinds=kinds, sign=sign)+ before_bound = _strictest_bound(constraints=before, kinds=kinds, sign=sign, integral=integral)+ after_bound = _strictest_bound(constraints=after, kinds=kinds, sign=sign, integral=integral)if after_bound is not None and (before_bound is None or after_bound > before_bound):reasons.append(f"its {label} tightened from {_render_bounds(constraints=before, kinds=kinds)} to {_render_bounds(constraints=after, kinds=kinds)}"@@ -146,6 +239,7 @@ def _strictest_bound(constraints: dict[ConstraintKind, int | float],kinds: tuple[tuple[ConstraintKind, bool], ...],sign: float,+ integral: bool,) -> tuple[float, bool] | None:"""The binding constraint of one family, as a key that sorts by strictness — `None` for none.@@ -153,8 +247,20 @@ def _strictest_bound(binds a lower bound harder, a *lower* one binds an upper bound harder, and negating the secondmakes `max` mean "strictest" in both. Exclusivity breaks the tie, since `gt=0` admits one fewervalue than `ge=0` at the same threshold.++ Over the integers exclusivity is not a tie-break but a step: `gt=0` *is* `ge=1`, so the+ exclusive form is folded into the inclusive one before comparing, and the two spellings of one+ bound stop reading as a tightening of each other."""- keys = [(sign * constraints[kind], exclusive) for kind, exclusive in kinds if kind in constraints]+ keys: list[tuple[float, bool]] = []+ for kind, exclusive in kinds:+ if kind not in constraints:+ continue+ threshold = sign * constraints[kind]+ if integral and exclusive:+ keys.append((threshold + 1.0, False))+ continue+ keys.append((threshold, exclusive))return max(keys) if keys else Nonediff --git a/pipelex/migration/snapshot.py b/pipelex/migration/snapshot.pyindex 2153690c6..891fb4a62 100644--- a/pipelex/migration/snapshot.py+++ b/pipelex/migration/snapshot.py@@ -4,6 +4,16 @@the fingerprint and the complete reference document. Older versions are never rewritten, so abump leaves the previous version's files behind as the frozen history the chain is made of.+**The head snapshot is not written blindly.** The head link is the only one that tracks, which+makes it the only one a regeneration can damage: run after deleting a field and it rewrites+`fingerprint@N` with the field gone, erasing the very removal the coverage gate exists to catch —+and the gate is then green over a change that breaks every user's file. So the regenerator reads+the stored head first, and refuses the surface when the models have lost a path, an enumerated+spelling or a slice of a value domain against it. Two situations produce that diff and they have+different remedies, which is why the refusal names both rather than picking one: a real removal+wants a version bump and an entry, and a change to the fingerprint *format* over an unreleased+schema wants the same regeneration under `--force`.+The reference document is the defaults layer verbatim: for a packaged-document surface a byte copyof the shipped TOML, for a model-defaults surface the document synthesized from the model's owndefaults. Neither carries a generated-by banner, because these files are not reports about a@@ -14,8 +24,10 @@ from pathlib import Pathfrom pydantic import BaseModel, ConfigDict+from pipelex.migration.coverage import diff_fingerprints+from pipelex.migration.exceptions import MigrationSnapshotRefusedErrorfrom pipelex.migration.fingerprint import SurfaceFingerprint, compute_fingerprint-from pipelex.migration.goldens import write_defaults_golden, write_fingerprint_golden+from pipelex.migration.goldens import read_fingerprint_golden, write_defaults_golden, write_fingerprint_goldenfrom pipelex.migration.ledger import load_ledgerfrom pipelex.migration.surfaces import Surface, SurfaceRegistry@@ -32,10 +44,12 @@ class SurfaceSnapshot(BaseModel):path_count: int-def snapshot_surface(*, surface: Surface, migration_dir: Path) -> SurfaceSnapshot:+def snapshot_surface(*, surface: Surface, migration_dir: Path, force: bool = False) -> SurfaceSnapshot:ledger = load_ledger(migration_dir=migration_dir, surface_id=surface.surface_id)schema_version = ledger.surface.current_schema_versionfingerprint = compute_surface_fingerprint(surface=surface, schema_version=schema_version)+ if not force:+ _refuse_a_destructive_head_overwrite(surface=surface, fingerprint=fingerprint, schema_version=schema_version, migration_dir=migration_dir)fingerprint_path = write_fingerprint_golden(migration_dir=migration_dir, fingerprint=fingerprint)defaults_path = write_defaults_golden(migration_dir=migration_dir,@@ -61,5 +75,41 @@ def compute_surface_fingerprint(*, surface: Surface, schema_version: int) -> Sur)-def snapshot_registry(*, registry: SurfaceRegistry, migration_dir: Path) -> list[SurfaceSnapshot]:- return [snapshot_surface(surface=surface, migration_dir=migration_dir) for surface in registry.surfaces]+def _refuse_a_destructive_head_overwrite(+ *,+ surface: Surface,+ fingerprint: SurfaceFingerprint,+ schema_version: int,+ migration_dir: Path,+) -> None:+ """Stop before overwriting a head golden that records material the models no longer have.++ Raises:+ MigrationSnapshotRefusedError: the stored head has a path, an enumerated spelling or a+ value domain the live models lost.+ """+ stored = read_fingerprint_golden(migration_dir=migration_dir, surface_id=surface.surface_id, schema_version=schema_version)+ if stored is None:+ # Nothing to erase: the first snapshot of a version is what the gate is asking for.+ return+ diff = diff_fingerprints(before=stored, after=fingerprint)+ if not diff.has_removals and not diff.narrowed_paths:+ return+ lost: list[str] = []+ if diff.has_removals:+ lost.append(f"it no longer has {diff.render_removals()}")+ if diff.narrowed_paths:+ lost.append(f"it accepts fewer values at {diff.render_narrowings()}")+ msg = (+ f"surface '{surface.surface_id}': refusing to overwrite the golden for schema version {schema_version}, because "+ f"{' and '.join(lost)}. Rewriting the head link here would erase exactly what the coverage gate exists to catch, "+ f"leaving it green over a change that breaks every file carrying that material. If this is a real removal, bump "+ f"current_schema_version to {schema_version + 1} and add the entry '{surface.surface_id}@{schema_version + 1}' "+ f"accounting for it. If schema version {schema_version} has not been released and the golden merely predates a "+ f"change to the fingerprint format itself, re-record it with `--force`"+ )+ raise MigrationSnapshotRefusedError(msg)+++def snapshot_registry(*, registry: SurfaceRegistry, migration_dir: Path, force: bool = False) -> list[SurfaceSnapshot]:+ return [snapshot_surface(surface=surface, migration_dir=migration_dir, force=force) for surface in registry.surfaces]diff --git a/pipelex/pipeline/fixes/applier.py b/pipelex/pipeline/fixes/applier.pyindex bef2cba68..928a10395 100644--- a/pipelex/pipeline/fixes/applier.py+++ b/pipelex/pipeline/fixes/applier.py@@ -382,18 +382,45 @@ def _apply_at_table_path(*, toml_doc: TOMLDocument, fix_op: FixOp, table_path: lreturn _apply_move_key(toml_doc=toml_doc, fix_op=fix_op, table_path=table_path)case RemapValueOp():target_table = _resolve_table(toml_doc=toml_doc, table_path=table_path)- if target_table is None or fix_op.key not in target_table:+ if target_table is None:+ return _OpResult(FixOpOutcome.SKIPPED, f"table '{table_path_str}' not found in document")+ if fix_op.key == WILDCARD_SEGMENT:+ return _remap_every_value(target_table=target_table, mapping=fix_op.mapping, table_path_str=table_path_str)+ if fix_op.key not in target_table:return _OpResult(FixOpOutcome.SKIPPED, f"key '{fix_op.key}' not found in table '{table_path_str}'")- current_value = target_table[fix_op.key]- if not isinstance(current_value, str):- return _OpResult(FixOpOutcome.SKIPPED, f"value of '{table_path_str}.{fix_op.key}' is not a string")- new_value = fix_op.mapping.get(str(current_value))- if new_value is None:- # The current value is deliberately not named: a report must never echo a value- # read from a user's file (docs/migration-ledger.md, "What the engine reports").- return _OpResult(FixOpOutcome.SKIPPED, f"value of '{table_path_str}.{fix_op.key}' is not in this operation's mapping")- target_table[fix_op.key] = new_value- return _OpResult(FixOpOutcome.APPLIED)+ return _remap_one_value(target_table=target_table, key=fix_op.key, mapping=fix_op.mapping, table_path_str=table_path_str)+++def _remap_one_value(*, target_table: dict[str, Any], key: str, mapping: dict[str, str], table_path_str: str) -> _OpResult:+ """Rewrite one key's value through the mapping, skipping anything the mapping does not name."""+ current_value = target_table[key]+ if not isinstance(current_value, str):+ return _OpResult(FixOpOutcome.SKIPPED, f"value of '{table_path_str}.{key}' is not a string")+ new_value = mapping.get(str(current_value))+ if new_value is None:+ # The current value is deliberately not named: a report must never echo a value+ # read from a user's file (docs/migration-ledger.md, "What the engine reports").+ return _OpResult(FixOpOutcome.SKIPPED, f"value of '{table_path_str}.{key}' is not in this operation's mapping")+ target_table[key] = new_value+ return _OpResult(FixOpOutcome.APPLIED)+++def _remap_every_value(*, target_table: dict[str, Any], mapping: dict[str, str], table_path_str: str) -> _OpResult:+ """Rewrite every value of the addressed table through the mapping — the ``*`` key.++ This is the "each of these" reading the wildcard already has in a ``table_path``, applied to+ keys instead of to tables, and it is what a mapping from the user's own keys to an enumerated+ value needs: the keys are the user's, so only the document can enumerate them, and no fixed+ ``key`` reaches them. A remap never collides, so folding many entries into one outcome needs+ no conflict rule: any rewrite makes the operation applied, none makes it skipped.+ """+ remapped = 0+ for key in list(target_table):+ if _remap_one_value(target_table=target_table, key=key, mapping=mapping, table_path_str=table_path_str).outcome.did_apply:+ remapped += 1+ if not remapped:+ return _OpResult(FixOpOutcome.SKIPPED, f"no value in '{table_path_str}' is one this operation's mapping names")+ return _OpResult(FixOpOutcome.APPLIED, f"remapped {remapped} of {len(target_table)} values in '{table_path_str}'")def _refresh_table_headers(*, item: Any) -> None:diff --git a/pipelex/suggested_fix.py b/pipelex/suggested_fix.pyindex af2821986..be12a2ec2 100644--- a/pipelex/suggested_fix.py+++ b/pipelex/suggested_fix.py@@ -91,6 +91,21 @@ class FixOpBase(BaseModel):table_path: list[str]+def _refuse_wildcard_key(*, key: str, what: str) -> str:+ """Refuse ``*`` where a fixed key is the only thing the semantics can mean.++ The segment means "each of these", and only a remap has a per-key answer to give. Deleting+ every key of a table is ``delete_table``; renaming or moving every key onto one fixed name is+ many-to-one and conflicts on the second match; writing a value under ``*`` names no key at+ all. Left unrefused each is a *dead* operation rather than a wrong one — the applier looks up+ a key literally spelled ``*``, never finds it, and reports a guarded skip forever.+ """+ if key == WILDCARD_SEGMENT:+ msg = f"{what} may not be the wildcard segment '{WILDCARD_SEGMENT}': only remap_value has a per-key meaning for it"+ raise ValueError(msg)+ return key++class SetKeyOp(FixOpBase):"""Write ``key = value`` in the addressed table, whatever it currently holds."""@@ -98,6 +113,11 @@ class SetKeyOp(FixOpBase):key: strvalue: TomlValue+ @field_validator("key")+ @classmethod+ def refuse_wildcard_key(cls, key: str) -> str:+ return _refuse_wildcard_key(key=key, what="a set_key key")+class EnsureTableOp(FixOpBase):"""Create the addressed table when it is absent, leaving an existing one untouched.@@ -116,6 +136,11 @@ class DeleteKeyOp(FixOpBase):kind: Literal[FixOpKind.DELETE_KEY] = FixOpKind.DELETE_KEYkey: str+ @field_validator("key")+ @classmethod+ def refuse_wildcard_key(cls, key: str) -> str:+ return _refuse_wildcard_key(key=key, what="a delete_key key")+class DeleteTableOp(FixOpBase):"""Drop the addressed table, including every chunk of one written out of order.@@ -135,6 +160,11 @@ class RenameTableKeyOp(FixOpBase):key: strnew_key: str+ @field_validator("key", "new_key")+ @classmethod+ def refuse_wildcard_key(cls, key: str) -> str:+ return _refuse_wildcard_key(key=key, what="a rename_table_key key")+class MoveKeyOp(FixOpBase):"""Relocate ``key`` from the addressed table into ``new_table_path``, under ``new_key``.@@ -150,6 +180,11 @@ class MoveKeyOp(FixOpBase):new_table_path: list[str]new_key: str+ @field_validator("key", "new_key")+ @classmethod+ def refuse_wildcard_key(cls, key: str) -> str:+ return _refuse_wildcard_key(key=key, what="a move_key key")+@field_validator("new_table_path")@classmethoddef refuse_wildcard_destination(cls, new_table_path: list[str]) -> list[str]:@@ -185,6 +220,12 @@ class RemapValueOp(FixOpBase):Only string values are remapped: the operation exists for renamed enumerated values, whoseTOML representation is always a string.++ ``key`` may be the wildcard segment, and this is the one kind for which it means anything:+ "each key of the addressed table". A mapping from the user's own keys to an enumerated value+ — ``dict[str, LogLevel]`` — keeps its spellings under keys only the document can enumerate,+ so no fixed ``key`` reaches them and this is the only shape in which a member renamed beneath+ an open mapping can be repaired at all."""kind: Literal[FixOpKind.REMAP_VALUE] = FixOpKind.REMAP_VALUEdiff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 5dff4acfe..b099df0b4 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -157,6 +157,7 @@ MigrationError | Migration error | https://docs.pipelex.com/latest/errors/migratMigrationGoldenError | Migration golden error | https://docs.pipelex.com/latest/errors/migration-golden-error/MigrationLedgerError | Migration ledger error | https://docs.pipelex.com/latest/errors/migration-ledger-error/MigrationRegistryError | Migration registry error | https://docs.pipelex.com/latest/errors/migration-registry-error/+MigrationSnapshotRefusedError | Migration snapshot refused | https://docs.pipelex.com/latest/errors/migration-snapshot-refused-error/MissingBundleValidatorError | Missing bundle validator | https://docs.pipelex.com/latest/errors/missing-bundle-validator-error/MissingDependencyError | Missing dependency | https://docs.pipelex.com/latest/errors/missing-dependency-error/MissingOrchestratorError | Missing orchestrator | https://docs.pipelex.com/latest/errors/missing-orchestrator-error/diff --git a/tests/unit/pipelex/migration/test_coverage_gate.py b/tests/unit/pipelex/migration/test_coverage_gate.pyindex 0f7fb6737..9504611e8 100644--- a/tests/unit/pipelex/migration/test_coverage_gate.py+++ b/tests/unit/pipelex/migration/test_coverage_gate.py@@ -625,6 +625,62 @@ mapping = { basic = "standard" }_snapshot(migration_dir=tmp_path, config_model=_SchemaTwoEnumMemberGone, schema_version=2)assert check_surface(surface=_surface(config_model=_SchemaTwoEnumMemberGone), migration_dir=tmp_path) == []+ def test_a_member_lost_inside_a_list_cannot_be_remapped_and_the_gate_says_so(self, tmp_path: Path) -> None:+ """A remap rewrites a string value, and the value here is a list.++ Crediting the remap would leave a green gate over a file that stops validating: the+ operation is a guarded skip on every run. `unsafe` is the only remedy, and the message+ has to say that rather than offer a remap the author would write and never see fire.+ """+ ops = """+[[migration.ops]]+kind = "remap_value"+table_path = []+key = "tiers"+mapping = { basic = "standard" }+"""+ _write_ledger(migration_dir=tmp_path, current_schema_version=2, entries=self._entry_with_ops(safety="safe", ops=ops))+ _snapshot(migration_dir=tmp_path, config_model=_ListOfTiers, schema_version=1)+ _snapshot(migration_dir=tmp_path, config_model=_ListOfTiersMemberGone, schema_version=2)+ issues = check_surface(surface=_surface(config_model=_ListOfTiersMemberGone), migration_dir=tmp_path)+ assert _kinds(issues) == [CoverageIssueKind.ENUM_MEMBER_NOT_REMAPPED]+ assert "must be marked unsafe" in issues[0].message+ assert "remap_value" not in issues[0].message++ def test_a_member_lost_beneath_an_open_mapping_is_remapped_through_the_wildcard_key(self, tmp_path: Path) -> None:+ """The keys are the user's, so `key = "*"` is the only operation that reaches the values."""+ ops = """+[[migration.ops]]+kind = "remap_value"+table_path = ["levels"]+key = "*"+mapping = { basic = "standard" }+"""+ _write_ledger(migration_dir=tmp_path, current_schema_version=2, entries=self._entry_with_ops(safety="safe", ops=ops))+ _snapshot(migration_dir=tmp_path, config_model=_MappingOfTiers, schema_version=1)+ _snapshot(migration_dir=tmp_path, config_model=_MappingOfTiersMemberGone, schema_version=2)+ assert check_surface(surface=_surface(config_model=_MappingOfTiersMemberGone), migration_dir=tmp_path) == []+++class _ListOfTiers(BaseModel):+ """An enumerated type inside a list: the members live on the list's own path, with no child record."""++ tiers: list[_Tier] = Field(default_factory=lambda: [_Tier.BASIC])+++class _ListOfTiersMemberGone(BaseModel):+ tiers: list[_TierWithoutBasic] = Field(default_factory=lambda: [_TierWithoutBasic.STANDARD])+++class _MappingOfTiers(BaseModel):+ """An enumerated type beneath an open mapping: the members live on the `*` record."""++ levels: dict[str, _Tier] = Field(default_factory=lambda: {"one": _Tier.BASIC})+++class _MappingOfTiersMemberGone(BaseModel):+ levels: dict[str, _TierWithoutBasic] = Field(default_factory=lambda: {"one": _TierWithoutBasic.STANDARD})+class TestValueDomainNarrowing:"""The change that keeps every path and every spelling, and still breaks a user's file.diff --git a/tests/unit/pipelex/migration/test_fingerprint.py b/tests/unit/pipelex/migration/test_fingerprint.pyindex 5190c9130..c3fcf6680 100644--- a/tests/unit/pipelex/migration/test_fingerprint.py+++ b/tests/unit/pipelex/migration/test_fingerprint.py@@ -33,8 +33,14 @@ class _Synthetic(BaseModel):optional_leaf: _Leaf | None = Nonedeck: dict[str, _Leaf]labels: dict[str, str]+ modes: dict[str, _Mode]+ mode_list: list[_Mode]tags: list[str]bounded: Annotated[int, Field(ge=1)] | Literal["unbounded"] = 1+ # A field-level bound binds the whole field, whatever a union member declares for itself —+ # pydantic applies it on top of the member's own. The field is never validated here; the+ # fingerprint reads the annotation and the metadata, and this is the shape that separates them.+ capped: Annotated[int, Field(le=100)] | Literal["auto"] = Field(default="auto", le=6)retries: int = Field(default=3, ge=0, le=10)lenient: str = Field(default="x", strict=False)item_bounded: list[Annotated[int, Field(ge=1)]] = Field(default_factory=list[int])@@ -80,8 +86,12 @@ class TestFingerprintPaths:"deck.*.count","labels","labels.*",+ "modes",+ "modes.*",+ "mode_list","tags","bounded",+ "capped","retries","lenient","item_bounded",@@ -152,6 +162,25 @@ class TestFingerprintRecords:assert record.value_type == ENUM_TYPEassert record.enum_members == ["fast", "slow"]+ def test_the_members_beneath_an_open_mapping_are_recorded_on_the_wildcard_and_not_on_the_table(self) -> None:+ """The container's own value is a table, not an enumerated spelling.++ Recording the members twice made the coverage gate demand a `remap_value` at the container+ path as well as at the wildcard one — and a remap of a table value can never fire, so the+ demand had no legal answer. The wildcard record is the one an operation can address.+ """+ fingerprint = _fingerprint()+ assert fingerprint.paths["modes"].enum_members is None+ assert fingerprint.paths["modes.*"].enum_members == ["fast", "slow"]++ def test_the_members_inside_a_list_are_recorded_on_the_list_itself(self) -> None:+ """A list gets no child record, so the list's own path is the only place they can live.++ Dropping them there would make a member removed from a `list[enum]` invisible to the gate;+ the remedy for one is an `unsafe` entry, which the coverage gate asks for by name.+ """+ assert _fingerprint().paths["mode_list"].enum_members == ["fast", "slow"]+def test_a_string_literal_counts_as_an_enumerated_spelling(self) -> None:"""A `Literal` and an `Enum` are the same thing to a TOML file: a closed set of spellings."""assert _fingerprint().paths["bounded"].enum_members == ["unbounded"]@@ -170,6 +199,15 @@ class TestFingerprintRecords:"""assert ConstraintKind.GE in (_fingerprint().paths["retries"].constraints or {})+ def test_a_field_level_bound_binds_the_whole_field_and_a_member_may_not_loosen_it(self) -> None:+ """`Field(le=6)` on the field is applied on top of whatever a union member declares.++ Merging the two sources by "widest wins" would record `le=100` and read a later tightening+ of the field-level bound as a change to an already-looser one — the gate going quiet on+ exactly the values that stop validating.+ """+ assert _fingerprint().paths["capped"].constraints == {ConstraintKind.LE: 6}+def test_a_bound_nested_inside_a_union_member_is_found_too(self) -> None:"""The shape `Annotated[int, Field(ge=1)] | Literal["unbounded"]`, which the type rendering strips."""assert _fingerprint().paths["bounded"].constraints == {ConstraintKind.GE: 1}diff --git a/tests/unit/pipelex/migration/test_ledger_check.py b/tests/unit/pipelex/migration/test_ledger_check.pyindex 5711ed8c9..8a11282c6 100644--- a/tests/unit/pipelex/migration/test_ledger_check.py+++ b/tests/unit/pipelex/migration/test_ledger_check.py@@ -77,6 +77,16 @@ class _SchemaTwoDeckFieldRenamed(BaseModel):deck: dict[str, _DeckEntryRenamed] = Field(default_factory=dict[str, _DeckEntryRenamed])+class _SchemaOneWithLevels(BaseModel):+ """A mapping from the user's own keys to an enumerated value — where `key = "*"` is the only reach."""++ levels: dict[str, _Tier] = Field(default_factory=dict[str, _Tier])+++class _SchemaTwoLevelMemberGone(BaseModel):+ levels: dict[str, _TierWithoutBasic] = Field(default_factory=dict[str, _TierWithoutBasic])++class _SchemaTwoEnumMemberGone(BaseModel):"""`basic` is no longer a legal spelling of `tier`."""@@ -293,6 +303,40 @@ new_key = "new_name"_snapshot(migration_dir=tmp_path, config_model=_SchemaTwoDeckFieldRenamed, schema_version=2)assert check_ledger(surface=_surface(config_model=_SchemaTwoDeckFieldRenamed), migration_dir=tmp_path) == []+ def test_a_wildcard_key_remap_beneath_an_open_node_is_legal_and_checked_like_any_other(self, tmp_path: Path) -> None:+ """`key = "*"` addresses the wildcard record, so the remap legality rule reads its member set.++ The keys under `levels` are the user's, so no fixed key reaches the values; the wildcard+ record is where the enumerated members live, and it is exactly what the rule is checked+ against — the operation is neither exempt nor unreachable.+ """+ ops = """+[[migration.ops]]+kind = "remap_value"+table_path = ["levels"]+key = "*"+mapping = { basic = "standard" }+"""+ _write_ledger(migration_dir=tmp_path, current_schema_version=2, entries=_entry(ops=ops))+ _snapshot(migration_dir=tmp_path, config_model=_SchemaOneWithLevels, schema_version=1)+ _snapshot(migration_dir=tmp_path, config_model=_SchemaTwoLevelMemberGone, schema_version=2)+ assert check_ledger(surface=_surface(config_model=_SchemaTwoLevelMemberGone), migration_dir=tmp_path) == []++ def test_a_wildcard_key_remap_that_would_rewrite_a_still_legal_value_is_refused(self, tmp_path: Path) -> None:+ """Wildcard or not, a `safe` remap must be provably unable to fire on a current file."""+ ops = """+[[migration.ops]]+kind = "remap_value"+table_path = ["levels"]+key = "*"+mapping = { premium = "standard" }+"""+ _write_ledger(migration_dir=tmp_path, current_schema_version=2, entries=_entry(ops=ops))+ _snapshot(migration_dir=tmp_path, config_model=_SchemaOneWithLevels, schema_version=1)+ _snapshot(migration_dir=tmp_path, config_model=_SchemaTwoLevelMemberGone, schema_version=2)+ issues = check_ledger(surface=_surface(config_model=_SchemaTwoLevelMemberGone), migration_dir=tmp_path)+ assert LedgerIssueKind.ILLEGAL_REMAP in _kinds(issues)+def test_a_safe_remap_of_a_value_that_is_still_legal_is_refused(self, tmp_path: Path) -> None:"""The remap legality rule, and the reason replay neutrality holds.diff --git a/tests/unit/pipelex/migration/test_narrowing.py b/tests/unit/pipelex/migration/test_narrowing.pyindex 288d7ef50..7216175f8 100644--- a/tests/unit/pipelex/migration/test_narrowing.py+++ b/tests/unit/pipelex/migration/test_narrowing.py@@ -71,6 +71,80 @@ class TestTheNarrowingRelation:reasons = describe_narrowing(before=_record(value_type="list[int | str]"), after=_record(value_type="int"))assert reasons == ["its type went from 'list[int | str]' to 'int'"]+ @pytest.mark.parametrize(+ ("before_type", "after_type"),+ [+ ("list[int]", "list[int | str]"),+ ("dict[str, int]", "dict[str, int | str]"),+ ("list[enum]", "list[str]"),+ ("dict[str, list[int]]", "dict[str, list[int | str]]"),+ ("int", "float"),+ ("list[int]", "list[float]"),+ ("enum", "literal"),+ ("literal", "enum"),+ ],+ )+ def test_a_container_or_scalar_that_only_gained_room_is_not_a_narrowing(self, before_type: str, after_type: str) -> None:+ """Four crying-wolf shapes, each a widening no file notices.++ A container whose item type widened is a widening of the container; `int` is accepted+ wherever `float` is, in strict validation as well as lax; and `enum` and `literal` are two+ renderings of the same thing — a closed set of string spellings — whose *member* movement+ is reported by the enumerated-spelling half rather than by the type half.+ """+ assert describe_narrowing(before=_record(value_type=before_type), after=_record(value_type=after_type)) == []++ @pytest.mark.parametrize(+ ("before_type", "after_type"),+ [+ ("list[int | str]", "list[int]"),+ ("dict[str, int]", "dict[str, str]"),+ ("float", "int"),+ ("list[int]", "list[int, str]"),+ ],+ )+ def test_a_container_whose_items_narrowed_is_still_a_narrowing(self, before_type: str, after_type: str) -> None:+ """The structural reading must not become a licence: same head, narrower argument, still red."""+ assert describe_narrowing(before=_record(value_type=before_type), after=_record(value_type=after_type)) == [+ f"its type went from '{before_type}' to '{after_type}'"+ ]++ @pytest.mark.parametrize(+ ("value_type", "before_constraints", "after_constraints"),+ [+ ("int", {ConstraintKind.GT: 0}, {ConstraintKind.GE: 1}),+ ("int", {ConstraintKind.GE: 1}, {ConstraintKind.GT: 0}),+ ("int", {ConstraintKind.LT: 10}, {ConstraintKind.LE: 9}),+ ("int | literal", {ConstraintKind.GT: 0}, {ConstraintKind.GE: 1}),+ ],+ )+ def test_two_spellings_of_one_integer_bound_are_the_same_bound(+ self,+ value_type: str,+ before_constraints: dict[ConstraintKind, int | float],+ after_constraints: dict[ConstraintKind, int | float],+ ) -> None:+ """Over the integers `gt=0` and `ge=1` admit exactly the same values.++ Reading the swap as a tightening is a false breaking verdict on a schema nobody's file can+ tell apart, and the remedy the gate would name — bump the version, write an unsafe entry —+ is work with no beneficiary.+ """+ assert (+ describe_narrowing(+ before=_record(value_type=value_type, constraints=before_constraints),+ after=_record(value_type=value_type, constraints=after_constraints),+ )+ == []+ )++ def test_the_integer_reading_is_not_applied_to_a_float(self) -> None:+ """`gt=0` and `ge=1` are different bounds over the reals, and `0.5` is between them."""+ assert describe_narrowing(+ before=_record(value_type="float", constraints={ConstraintKind.GT: 0}),+ after=_record(value_type="float", constraints={ConstraintKind.GE: 1}),+ ) == ["its lower bound tightened from gt=0 to ge=1"]+@pytest.mark.parametrize(("before_constraints", "after_constraints", "expected_fragment"),[diff --git a/tests/unit/pipelex/migration/test_snapshot_guard.py b/tests/unit/pipelex/migration/test_snapshot_guard.pynew file mode 100644index 000000000..b73095f0c--- /dev/null+++ b/tests/unit/pipelex/migration/test_snapshot_guard.py@@ -0,0 +1,151 @@+"""Unit tests for the head-golden regeneration guard.++The head link is the only one that tracks, which makes it the only one a regeneration can damage.+Run the regenerator after deleting a field and it rewrites `fingerprint@N` with the field gone,+erasing the removal the coverage gate exists to catch — and the gate is then green over a change+that breaks every file carrying it. These tests pin the refusal, its two-sided message, and the+one escape a fingerprint *format* change legitimately needs.+"""++import re+from enum import StrEnum+from pathlib import Path++import pytest+from pydantic import BaseModel, Field++from pipelex.migration.exceptions import MigrationSnapshotRefusedError+from pipelex.migration.goldens import read_fingerprint_golden+from pipelex.migration.ledger import ledgers_dir+from pipelex.migration.snapshot import snapshot_surface+from pipelex.migration.surfaces import DefaultsLayerKind, Surface++SURFACE_ID = "synthetic-config"+++class _Tier(StrEnum):+ BASIC = "basic"+ PREMIUM = "premium"+++class _TierWithoutBasic(StrEnum):+ PREMIUM = "premium"+++class _SchemaOne(BaseModel):+ label: str = "hello"+ tier: _Tier = _Tier.BASIC+ retries: int = Field(default=3, ge=1)+++class _LabelGone(BaseModel):+ tier: _Tier = _Tier.BASIC+ retries: int = Field(default=3, ge=1)+++class _MemberGone(BaseModel):+ label: str = "hello"+ tier: _TierWithoutBasic = _TierWithoutBasic.PREMIUM+ retries: int = Field(default=3, ge=1)+++class _BoundTightened(BaseModel):+ label: str = "hello"+ tier: _Tier = _Tier.BASIC+ retries: int = Field(default=3, ge=2)+++class _KeyAdded(BaseModel):+ label: str = "hello"+ tier: _Tier = _Tier.BASIC+ retries: int = Field(default=3, ge=1)+ extra: str = "new"+++def _surface(*, config_model: type[BaseModel]) -> Surface:+ return Surface(+ surface_id=SURFACE_ID,+ title="A synthetic configuration surface",+ base_file="synthetic.toml",+ config_model=config_model,+ defaults_layer_kind=DefaultsLayerKind.MODEL_DEFAULTS,+ )+++def _write_ledger(*, migration_dir: Path) -> None:+ ledgers = ledgers_dir(migration_dir=migration_dir)+ ledgers.mkdir(parents=True, exist_ok=True)+ (ledgers / f"{SURFACE_ID}.toml").write_text(+ f"""+[surface]+id = "{SURFACE_ID}"+title = "A synthetic configuration surface"+base_file = "synthetic.toml"+current_schema_version = 1+min_supported_schema_version = 0+""",+ encoding="utf-8",+ )+++class TestTheSnapshotGuard:+ def test_the_first_snapshot_of_a_version_is_written(self, tmp_path: Path) -> None:+ """Nothing to erase: writing a link that does not exist is what the gate is asking for."""+ _write_ledger(migration_dir=tmp_path)++ snapshot_surface(surface=_surface(config_model=_SchemaOne), migration_dir=tmp_path)++ stored = read_fingerprint_golden(migration_dir=tmp_path, surface_id=SURFACE_ID, schema_version=1)+ assert stored is not None+ assert "label" in stored.paths++ def test_an_additive_change_re_records_freely(self, tmp_path: Path) -> None:+ """A regeneration that erases nothing is the ordinary case and must stay frictionless."""+ _write_ledger(migration_dir=tmp_path)+ snapshot_surface(surface=_surface(config_model=_SchemaOne), migration_dir=tmp_path)++ snapshot_surface(surface=_surface(config_model=_KeyAdded), migration_dir=tmp_path)++ stored = read_fingerprint_golden(migration_dir=tmp_path, surface_id=SURFACE_ID, schema_version=1)+ assert stored is not None+ assert "extra" in stored.paths++ @pytest.mark.parametrize("config_model", [_LabelGone, _MemberGone, _BoundTightened])+ def test_a_head_golden_recording_lost_material_is_not_overwritten(self, tmp_path: Path, config_model: type[BaseModel]) -> None:+ """A removed path, a retired spelling and a tightened bound all break a file, and all refuse.++ Without the refusal a habitual regeneration is enough to make the coverage gate green over+ any of them — the golden it compares against would already have been rewritten.+ """+ _write_ledger(migration_dir=tmp_path)+ snapshot_surface(surface=_surface(config_model=_SchemaOne), migration_dir=tmp_path)++ with pytest.raises(MigrationSnapshotRefusedError):+ snapshot_surface(surface=_surface(config_model=config_model), migration_dir=tmp_path)++ stored = read_fingerprint_golden(migration_dir=tmp_path, surface_id=SURFACE_ID, schema_version=1)+ assert stored is not None+ assert stored.paths["label"].value_type == "str"+ assert stored.paths["tier"].enum_members == ["basic", "premium"]+ assert stored.paths["retries"].constraints is not None++ def test_the_refusal_names_both_remedies(self, tmp_path: Path) -> None:+ """The diff has two readings and the message must not pick one on the author's behalf."""+ _write_ledger(migration_dir=tmp_path)+ snapshot_surface(surface=_surface(config_model=_SchemaOne), migration_dir=tmp_path)++ with pytest.raises(MigrationSnapshotRefusedError, match=re.escape(f"'{SURFACE_ID}@2'")) as caught:+ snapshot_surface(surface=_surface(config_model=_LabelGone), migration_dir=tmp_path)++ assert "--force" in str(caught.value)++ def test_force_re_records_the_head_over_lost_material(self, tmp_path: Path) -> None:+ """The escape a fingerprint *format* change needs, over a schema version nobody has released."""+ _write_ledger(migration_dir=tmp_path)+ snapshot_surface(surface=_surface(config_model=_SchemaOne), migration_dir=tmp_path)++ snapshot_surface(surface=_surface(config_model=_LabelGone), migration_dir=tmp_path, force=True)++ stored = read_fingerprint_golden(migration_dir=tmp_path, surface_id=SURFACE_ID, schema_version=1)+ assert stored is not None+ assert "label" not in stored.pathsdiff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_migration_ops.py b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_migration_ops.pyindex 529431650..e9949e39e 100644--- a/tests/unit/pipelex/pipeline/fixes/test_fix_applier_migration_ops.py+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_applier_migration_ops.py@@ -41,6 +41,11 @@ tier = "premium"[deck.claude]provider = "anthropic"tier = "legacy"++[levels]+httpx = "loud"+openai = "quiet"+urllib3 = "info""""@@ -176,6 +181,36 @@ class TestFixApplierMigrationOps:assert outcomes == [FixOpOutcome.CONFLICT]assert text == occupied+ def test_a_wildcard_key_remaps_every_value_of_the_addressed_table(self) -> None:+ """The "each of these" reading of `*`, applied to keys rather than to tables.++ A mapping from the user's own keys to an enumerated value — `dict[str, LogLevel]` — has its+ spellings beneath keys nobody but the document can enumerate, so this is the only shape in+ which a renamed enum member under an open mapping can be repaired at all.+ """+ text, outcomes = _apply(+ text=_DOC,+ ops=[RemapValueOp(table_path=["levels"], key="*", mapping={"loud": "verbose", "quiet": "warning"})],+ )+ assert outcomes == [FixOpOutcome.APPLIED]+ assert _table_at(text=text, path=["levels"]) == {"httpx": "verbose", "openai": "warning", "urllib3": "info"}++ def test_a_wildcard_key_remap_that_matches_no_value_skips_without_touching_the_document(self) -> None:+ text, outcomes = _apply(text=_DOC, ops=[RemapValueOp(table_path=["levels"], key="*", mapping={"nope": "other"})])+ assert outcomes == [FixOpOutcome.SKIPPED]+ assert text == _DOC++ def test_a_wildcard_key_remap_skips_over_a_value_that_is_not_a_string(self) -> None:+ """Only string values are remapped, whether the key is named or matched by the wildcard."""+ text, outcomes = _apply(text=_DOC, ops=[RemapValueOp(table_path=["reporting"], key="*", mapping={"loud": "verbose"})])+ assert outcomes == [FixOpOutcome.SKIPPED]+ assert text == _DOC++ def test_a_wildcard_key_remap_over_an_absent_table_skips(self) -> None:+ text, outcomes = _apply(text=_DOC, ops=[RemapValueOp(table_path=["no_such_section"], key="*", mapping={"loud": "verbose"})])+ assert outcomes == [FixOpOutcome.SKIPPED]+ assert text == _DOC+def test_wildcard_over_an_absent_node_skips(self) -> None:"""Nothing matches, so nothing happens — and the document is untouched."""text, outcomes = _apply(text=_DOC, ops=[DeleteKeyOp(table_path=["no_such_section", "*"], key="anything")])diff --git a/tests/unit/pipelex/test_fix_op_union.py b/tests/unit/pipelex/test_fix_op_union.pyindex 02261d076..bef540bdf 100644--- a/tests/unit/pipelex/test_fix_op_union.py+++ b/tests/unit/pipelex/test_fix_op_union.py@@ -131,6 +131,33 @@ class TestFixOpUnion:assert isinstance(op, RenameTableKeyOp)assert op.table_path == ["deck", "*"]+ def test_a_wildcard_key_is_accepted_only_by_a_remap(self) -> None:+ """`key = "*"` means "each key of this table", and only a remap has a per-key answer.++ Deleting every key is `delete_table`; renaming or moving every key onto one fixed name is+ many-to-one and conflicts on the second one. Left unrefused they are dead operations: the+ applier looks up a key literally named `*`, never finds it, and reports a guarded skip+ forever.+ """+ op = _FixOpHolder.model_validate({"op": {"kind": "remap_value", "table_path": ["levels"], "key": "*", "mapping": {"a": "b"}}}).op+ assert isinstance(op, RemapValueOp)+ assert op.key == "*"++ @pytest.mark.parametrize(+ "payload",+ [+ {"kind": "delete_key", "table_path": ["s"], "key": "*"},+ {"kind": "rename_table_key", "table_path": ["s"], "key": "*", "new_key": "n"},+ {"kind": "rename_table_key", "table_path": ["s"], "key": "k", "new_key": "*"},+ {"kind": "move_key", "table_path": ["s"], "key": "*", "new_table_path": ["t"], "new_key": "k"},+ {"kind": "move_key", "table_path": ["s"], "key": "k", "new_table_path": ["t"], "new_key": "*"},+ {"kind": "set_key", "table_path": ["s"], "key": "*", "value": "v"},+ ],+ )+ def test_a_wildcard_key_is_refused_everywhere_else(self, payload: dict[str, object]) -> None:+ with pytest.raises(ValidationError, match="wildcard"):+ _FixOpHolder.model_validate({"op": payload})+def test_a_remap_needs_a_non_empty_mapping(self) -> None:"""An empty mapping is an operation that can never do anything — an authoring mistake."""with pytest.raises(ValidationError):diff --git a/wip/migrator-phase3-progress.md b/wip/migrator-phase3-progress.mdnew file mode 100644index 000000000..1b2775593--- /dev/null+++ b/wip/migrator-phase3-progress.md@@ -0,0 +1,109 @@+# S6 — Migrator Phase 3: working tracker++The charter is [`wip/migrator-3/sequencing.md` § S6](../../wip/migrator-3/sequencing.md) at the **workspace root** (from this repo: `../wip/migrator-3/sequencing.md`), with the phase content in `plan.md § Phase 3`. This file is the session-crossing record of what S6 has built, what it decided, and what is still open. Open the charter first, then this.++**Venue.** `_migrator/`, branch `feature/Migrator-3`, cut from `origin/dev` = `0aa8913f2` (the Phase 2 squash merge). Milestone 1 is committed as `077744b3d`; nothing pushed yet, no PR open yet.++## Build order chosen for this session++The charter lists a great many deliverables without an order. The order below was chosen so that everything touching the **golden format** happens first and the goldens are regenerated exactly once, before any other work can be built on top of a format that then moves:++1. **The golden-format bucket + the narrowing relation** — done, see below.+2. **R9 + the "what does `unsafe` promise" pass** — not started.+3. **The applier's dotted-key rename policy, the backup/replace semantics pass, the `UNWRITABLE` wording** — not started.+4. **The commands** — `pipelex migrate`, `pipelex-agent migrate`, the downgrade diagnosis, the rendering-rule test — not started.+5. **Boot tolerance, `report_validation_error` on the real plan, the telemetry remedies retired, the `doctor` row** — not started.+6. **The skills (`add-migration`, `/release` step 3b), the `config-docs` drift-contract review list, `command-surface-map.md` rows, publishing the contract in the nav** — not started.++## Milestone 1 — the golden-format bucket (DONE)++The charter required this to be *decided and recorded* in S6, before S7 freezes the format. All three questions are answered, the goldens were regenerated once, and the contract moved in the same change.++### (a) P — a binding bound merged with a union member's own++**Decided: the two sources do not merge the same way, and are intersected rather than pooled.**++`_collect_constraints` (`pipelex/migration/fingerprint.py`) used to flatten the field's own metadata and every union member's `Annotated` carriers into one list and take the widest of each kind. That recorded `le=100` for a field whose own `Field(le=6)` was the real ceiling — verified against pydantic, which applies the field-level bound on top of the member's. Now:++- the **binding** pool (field metadata, plus any `Annotated` wrapper met before a union) merges by **strictest**, because pydantic applies all of them;+- each **union member** gets its own pool merged by strictest, and the pools merge across each other by **widest**, because a union accepts a value if any member does;+- the two results are **intersected** (strictest), because a value must satisfy the binding bound *and* land in some member's domain.++One overclaim is kept deliberately and is now written down in the contract: a kind present on some members and not others is kept rather than dropped, so a tightening stays visible on the common `Annotated[int, Field(ge=1)] | Literal["auto"]` shape.++**No golden moved** — no live surface has the mixing shape.++### (b) `key = "*"` under a `remap_value`++**Decided: both halves of the "teach the applier" reading, not the "stop gathering" reading.**++- `RemapValueOp` now accepts `key = "*"`, meaning *each key of the addressed table*. The applier (`pipelex/pipeline/fixes/applier.py`, `_remap_every_value`) rewrites every string value the mapping names; any rewrite makes the operation `APPLIED`, none makes it `SKIPPED`, and a remap cannot collide so there is no conflict rule to invent. This is the **only** shape in which a member renamed beneath an open mapping can be repaired at all, since the keys are the user's.+- Every **other** kind refuses a `*` key when the op is parsed (`_refuse_wildcard_key` in `pipelex/suggested_fix.py`, on `set_key`, `delete_key`, `rename_table_key` both sides, `move_key` both sides). Unrefused they are *dead* operations — a literal lookup for a key spelled `*` that skips forever.+- `_gather_enum_members` now **stops at an open mapping's boundary**. The members belong to the `*` child record, whose own value is the enumerated one; recording them on the container as well made coverage demand a remap at a path whose value is a table, a demand with no legal answer. Every other container is still descended into — a `list[enum]` has no child record, so the list's own path is the only place a lost member is visible.+- Coverage now only **credits** a remap on a path a remap can reach (`is_remappable` in `narrowing.py`: the path's own value must be string-typed). For a `list[enum]` it names `unsafe` as the only remedy instead of offering a remap the author would write and never see fire.++**The one golden move of this session**, and the only one: `pipelex-config/[email protected]` lost the duplicated `enum_members` on `pipelex.log_config.package_log_levels`. `preferred_agent_targets` (a `list[enum]`) keeps its members, by design.++### (c) `list[Model]` recorded as a terminal `list[table]`++**Decided: the blind spot stays, and the reason is now in the contract.** Recording an item model's fields under a synthetic segment would make a renamed field inside an `OtlpExporterConfig` *visible* to the coverage gate — and then *demanded*, with no operation in the vocabulary able to address anything beneath an array of tables and therefore no remedy an author could write. A gate whose refusal has no legal answer is worse than a blind spot the contract names. The revisit trigger is recorded: the day an addressing syntax for arrays of tables exists, the two are one change.++### Alongside, in the same milestone++- **Q, the crying-wolf shapes in the narrowing relation** (relation only, no format move): a container whose argument widened (`list[int]` → `list[int | str]`) is now read structurally; `int` is absorbed by `float`; `enum` and `literal` absorb each other, since what moved between two member *sets* is `lost_enumerated_spellings`' to report; and over an integral type `gt=n` and `ge=n+1` are folded to the same bound, so the swap stops reading as a tightening. `_is_integral` sets the string-typed members aside first, so `int | literal` counts.+- **`umig` no longer rides in `make up`**, and refuses to overwrite a head golden recording a path, spelling or value domain the models lost (`_refuse_a_destructive_head_overwrite`, `MigrationSnapshotRefusedError`). The refusal names both readings — a real removal wants a bump and an entry, a format change over an unreleased version wants `make umigf` (new target, `--force`). This is what makes the *first* golden regeneration of this session an explicit act rather than muscle memory.+- **The head-link remedy text** in `coverage.py` now names the `make umigf` escape beside the bump, which was Session 9's finding.++### Files touched in milestone 1++```+pipelex/migration/fingerprint.py binding/member constraint split; enum gathering stops at an open mapping; INTEGER_TYPE / REAL_TYPE+pipelex/migration/narrowing.py is_remappable; structural container widening; int→float; enum↔literal; integral bound folding+pipelex/migration/coverage.py credit only reachable remaps; head-link remedy text+pipelex/migration/snapshot.py the head-overwrite refusal+pipelex/migration/exceptions.py MigrationSnapshotRefusedError+pipelex/suggested_fix.py _refuse_wildcard_key on every kind but remap_value+pipelex/pipeline/fixes/applier.py _remap_one_value / _remap_every_value (the `*` key)+pipelex/cli/dev_cli/_dev_cli.py --force on update-migration-schemas+pipelex/cli/dev_cli/commands/update_migration_schemas_cmd.py+Makefile umigf; umig out of `up`+docs/migration-ledger.md the three decisions, the wildcard-key rule, the regenerator paragraph+pipelex/migration/goldens/pipelex-config/[email protected] the one format move+tests/unit/pipelex/migration/test_fingerprint.py+tests/unit/pipelex/migration/test_narrowing.py+tests/unit/pipelex/migration/test_coverage_gate.py+tests/unit/pipelex/migration/test_ledger_check.py+tests/unit/pipelex/migration/test_snapshot_guard.py (new)+tests/unit/pipelex/test_fix_op_union.py+tests/unit/pipelex/pipeline/fixes/test_fix_applier_migration_ops.py+tests/data/errors/error_identity.txt regenerated (`make gei`) for the new error class+docs/errors/migration-snapshot-refused-error.md, docs/errors/platform-and-tooling.md regenerated (`make gep`)+```++A new `PipelexError` subclass needs both regenerators, and neither is in `agent-check`: `make gei`+(the identity snapshot, caught only by the *full* `agent-test`) and `make gep` (the per-class+reference page, caught by nothing at all). `MigrationSnapshotRefusedError` is the one this session+added.++### Verified at the pause++`make agent-check` green. `make cl` green, `make cmig` green. `make umig` is a no-op on the tree as committed. Full `make agent-test` green — every test passed, working tree clean.++## Already true before this session started (do not rebuild)++- **The directory walk's overlap refusal** — the S6 "Done when" item carried from the #1110 review — **is already built and tested**: `SurfaceRegistry.surface_for_file_name` raises `MigrationRegistryError` naming the file, and `tests/unit/pipelex/migration/test_surface_resolution.py::test_a_file_two_globs_both_claim_stops_by_name` proves it with the `pipelex_*.toml` / `*_local.toml` pair. It landed in Phase 2 ahead of schedule. **What is still owed** is the #1111 note-5 half: use the *real* specimen — `.pipelex/inference/backends/pipelex_gateway.toml`, which matches the `pipelex-config` tier glob and is claimed by nothing — rather than a synthetic name, and pin that the walk is **non-recursive** (it is: `files_by_surface_in_directory` skips anything that is not a file, so the `inference/backends/` subdirectory is never descended). That is a test, not a behaviour change.++## Still open, in the charter's own words++Everything in [§ S6](../../wip/migrator-3/sequencing.md#s6--migrator-phase-3) not listed under Milestone 1 above. The ones that must be settled *here* rather than at S7:++- **The dotted-key rename policy** — renaming a table written in dotted-key form swallows the scalars after it. Reproduced in round 3; the reshape's table renames will meet it on the first machine. Refuse with a `CONFLICT` naming the section, or preserve dotted-ness through `_replace_key_in_container`; either way a red/green fixture in `test_fix_applier_config_surface_shapes.py`.+- **The backup and replace semantics pass** — the same-second backup collision (M), a symlinked target replaced by a regular file (N), the backup kept after an uncertain-state failure being pruned by the next successful run, ownership/ACL/xattr loss, and whether a directory `fsync` is owed. One policy decision, written into the contract's "Backups" paragraph. `file_transaction.py` is shared with the `.mthds` fix loop.+- **The `UNWRITABLE` wording and the reason enum** — for a single-file commit the only reachable `FixTransactionError` is post-commit cleanup, i.e. the write *landed*; the wording describes an unreachable path.+- **R9** — the op-free `unsafe` entry declares the paths whose domain narrowed; `check-ledger` demands the declaration name at least one path the fingerprint at the entry's own version still has; the rehearsal reads it. Built together with the sibling question (an `unsafe` entry silenced by a later `safe` rename of its target) as one pass over what `unsafe` promises.++Then the phase's own body: the two commands, boot tolerance, `report_validation_error`, the downgrade diagnosis, the telemetry-remedy retirement, `doctor`, the drift-contract review list (plus the four validator sites R8 names), the `add-migration` skill, `/release` step 3b, the `command-surface-map.md` rows, and publishing the contract in the nav.++## Rulings this session took on its own authority++The charter says the format bucket is to be "decided and recorded here" — it does not route it to Louis, unlike R1–R9. The three decisions above were taken on that basis, each with its reasoning written into `docs/migration-ledger.md` rather than only here. **R9 itself is already ruled** (option 2, 2026-08-16) and is a build task, not a decision.