Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

migrator recap

Louis Choquel143571a58836
diff --git a/wip/migrator/migrator-what-we-built.html b/wip/migrator/migrator-what-we-built.html
new file mode 100644
index 000000000..e5fd9117c
--- /dev/null
+++ b/wip/migrator/migrator-what-we-built.html
@@ -0,0 +1,572 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Configuration migration: repairing a user's file instead of throwing it away</title>
+<style>
+ :root {
+ --bg: #fbfbfa;
+ --surface: #ffffff;
+ --surface-2: #f4f4f2;
+ --ink: #1a1a18;
+ --ink-soft: #55554f;
+ --ink-faint: #85857c;
+ --rule: #e2e2dc;
+ --accent: #9a3412;
+ --accent-soft: #fdf0e8;
+ --bad: #b42318;
+ --bad-soft: #fdf1f0;
+ --good: #2b6a45;
+ --good-soft: #edf6f0;
+ --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+ --sans: ui-sans-serif, -apple-system, "Segoe UI", Inter, Helvetica, Arial, sans-serif;
+ }
+ @media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #16171a;
+ --surface: #1d1f23;
+ --surface-2: #24262b;
+ --ink: #e9e9e4;
+ --ink-soft: #b3b3ab;
+ --ink-faint: #85857c;
+ --rule: #33363c;
+ --accent: #f0a072;
+ --accent-soft: #2c2018;
+ --bad: #f0837a;
+ --bad-soft: #2d1c1b;
+ --good: #7cc59b;
+ --good-soft: #172a20;
+ }
+ }
+ * { box-sizing: border-box; }
+ body {
+ margin: 0; background: var(--bg); color: var(--ink);
+ font-family: var(--sans); font-size: 16px; line-height: 1.62;
+ -webkit-text-size-adjust: 100%;
+ }
+ .wrap { max-width: 62rem; margin: 0 auto; padding: 3rem 1.25rem 6rem; }
+ header.masthead { border-bottom: 2px solid var(--ink); padding-bottom: 1.25rem; margin-bottom: 2rem; }
+ .eyebrow {
+ font-family: var(--mono); font-size: .72rem; letter-spacing: .14em; text-transform: uppercase;
+ color: var(--accent); margin: 0 0 .6rem;
+ }
+ h1 { font-size: clamp(1.7rem, 4.4vw, 2.4rem); line-height: 1.15; margin: 0 0 .7rem; letter-spacing: -.02em; }
+ .standfirst { font-size: 1.06rem; color: var(--ink-soft); margin: 0; max-width: 48rem; }
+ .meta { font-family: var(--mono); font-size: .78rem; color: var(--ink-faint); margin-top: 1.1rem; display: flex; flex-wrap: wrap; gap: .4rem 1.2rem; }
+ h2 {
+ font-size: 1.3rem; margin: 3rem 0 1rem; letter-spacing: -.01em;
+ padding-top: 1.2rem; border-top: 1px solid var(--rule);
+ }
+ h3 { font-size: 1.02rem; margin: 1.8rem 0 .6rem; }
+ p { margin: 0 0 1rem; }
+ a { color: var(--accent); text-decoration-thickness: 1px; text-underline-offset: 2px; }
+ code { font-family: var(--mono); font-size: .87em; background: var(--surface-2); padding: .12em .35em; border-radius: 3px; }
+ pre { margin: 0; overflow-x: auto; background: var(--surface-2); border: 1px solid var(--rule); border-radius: 6px; padding: .9rem 1rem; }
+ pre code { background: none; padding: 0; font-size: .8rem; line-height: 1.55; }
+ ul, ol { margin: 0 0 1rem; padding-left: 1.3rem; }
+ li { margin-bottom: .4rem; }
+
+ .tldr {
+ background: var(--accent-soft); border: 1px solid var(--accent);
+ border-radius: 8px; padding: 1.3rem 1.5rem; margin: 0 0 2rem;
+ }
+ .tldr h2 { margin: 0 0 .7rem; border: none; padding: 0; font-size: 1.05rem; font-family: var(--mono);
+ letter-spacing: .1em; text-transform: uppercase; color: var(--accent); }
+ .tldr p:last-child, .tldr ul:last-child { margin-bottom: 0; }
+
+ .note { background: var(--surface); border-left: 3px solid var(--rule); padding: .8rem 1rem; margin: 0 0 1rem; font-size: .93rem; color: var(--ink-soft); }
+ .note.warn { border-left-color: var(--bad); background: var(--bad-soft); color: var(--ink); }
+ .note.ok { border-left-color: var(--good); background: var(--good-soft); color: var(--ink); }
+
+ table { border-collapse: collapse; width: 100%; font-size: .89rem; margin: 0 0 1rem; }
+ th, td { text-align: left; padding: .5rem .6rem; border-bottom: 1px solid var(--rule); vertical-align: top; }
+ th { font-family: var(--mono); font-size: .74rem; letter-spacing: .07em; text-transform: uppercase; color: var(--ink-faint); }
+ .tblwrap { overflow-x: auto; }
+
+ details { border: 1px solid var(--rule); border-radius: 6px; margin: 0 0 .8rem; background: var(--surface); }
+ summary { cursor: pointer; padding: .65rem .9rem; font-weight: 600; font-size: .93rem; list-style: none; }
+ summary::-webkit-details-marker { display: none; }
+ summary::before { content: "▸ "; color: var(--accent); font-weight: 400; }
+ details[open] summary::before { content: "▾ "; }
+ details > div, details > pre { margin: 0 .9rem .9rem; }
+ details > pre { margin-top: 0; }
+
+ .cols { display: grid; grid-template-columns: 1fr 1fr; gap: .8rem; margin: 0 0 1rem; }
+ @media (max-width: 42rem) { .cols { grid-template-columns: 1fr; } }
+ .col-label { font-family: var(--mono); font-size: .72rem; text-transform: uppercase; letter-spacing: .08em; color: var(--ink-faint); margin: 0 0 .3rem; }
+
+ figure { margin: 1.4rem 0; }
+ figure svg { display: block; width: 100%; height: auto; background: var(--surface); border: 1px solid var(--rule); border-radius: 8px; }
+ figcaption { font-size: .82rem; color: var(--ink-faint); margin-top: .5rem; }
+ .svg-box { fill: var(--surface-2); stroke: var(--rule); }
+ .svg-box-a { fill: var(--accent-soft); stroke: var(--accent); }
+ .svg-box-g { fill: var(--good-soft); stroke: var(--good); }
+ .svg-box-b { fill: var(--bad-soft); stroke: var(--bad); }
+ .svg-t { fill: var(--ink); font-family: var(--sans); font-size: 12px; }
+ .svg-t-s { fill: var(--ink-soft); font-family: var(--sans); font-size: 10.5px; }
+ .svg-m { fill: var(--ink); font-family: var(--mono); font-size: 11px; }
+ .svg-line { stroke: var(--ink-faint); fill: none; stroke-width: 1.3; }
+ .svg-arrow { fill: var(--ink-faint); }
+
+ .diff-add { color: var(--good); }
+ .diff-del { color: var(--bad); }
+ .pillrow { display: flex; flex-wrap: wrap; gap: .4rem; margin: 0 0 1rem; }
+ .pill { font-family: var(--mono); font-size: .74rem; border: 1px solid var(--rule); border-radius: 999px; padding: .15rem .6rem; color: var(--ink-soft); background: var(--surface); }
+ footer { margin-top: 3rem; padding-top: 1.2rem; border-top: 1px solid var(--rule); font-size: .84rem; color: var(--ink-faint); }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<header class="masthead">
+ <p class="eyebrow">pipelex · v0.46.0</p>
+ <h1>Configuration migration: repairing a user's file instead of throwing it away</h1>
+ <p class="standfirst">
+ We changed the shape of every configuration file pipelex reads — and built the machinery that
+ makes that survivable on a machine that already has one. Migration is now recorded as data,
+ replayed over real files, and enforced by gates that refuse a schema change nobody accounted for.
+ </p>
+ <div class="meta">
+ <span>Release <strong>v0.46.0</strong></span>
+ <span>9 merged PRs · <a href="https://github.com/Pipelex/pipelex/pull/1117">#1117 cuts the release</a></span>
+ <span>Author-facing doc — for co-developers</span>
+ </div>
+</header>
+
+<div class="tldr">
+ <h2>TL;DR</h2>
+ <p>
+ <strong>The problem:</strong> a schema change used to be a landmine. <code>pipelex init</code> never
+ overwrites, so every machine in the field kept its old file, and the next boot died on
+ <code>extra="forbid"</code> naming a key the user never chose to have. The only remedy we could offer
+ was <code>pipelex init</code> — which resets the file and discards their API keys, buckets and log levels.
+ </p>
+ <p>
+ <strong>What we built:</strong> every configuration surface now carries a checked-in <em>ledger</em>
+ recording each shape change as data. <code>pipelex migrate</code> replays it over a user's real files,
+ in place, keeping their values and taking a timestamped backup. A stale-but-explainable config no
+ longer stops the boot — it warns. Three gates make it impossible to land a schema change without the
+ entry that repairs it.
+ </p>
+ <p>
+ <strong>What you need to do:</strong> after pulling, run <code>pipelex migrate</code> once. If you touch
+ a config model and <code>make cmig</code> refuses, invoke the <code>add-migration</code> skill — never
+ regenerate the goldens to silence it.
+ </p>
+</div>
+
+<h2>Why a "just edit the model" change was never just that</h2>
+
+<p>
+ Three of the four surfaces below changed shape in this release, and each change was, by itself,
+ reasonable. The reshape gave <code>pipelex.toml</code> a scheme. Retiring <code>prompting_target</code>
+ made templating an authoring decision. Neither is controversial. What made them dangerous is that
+ configuration files are <em>the user's</em>: we ship defaults, they edit and keep them, and we never
+ overwrite. So a field we delete lives on in their file forever, and the strict loader that protects
+ them from typos is exactly what turns our cleanup into their broken boot.
+</p>
+
+<p>
+ The failure had a particularly bad shape. The error named a key — but not which file put it there,
+ and certainly not whether that key was correct last month. A user reading
+ <code>Extra inputs are not permitted: prompting_target</code> has no way to tell a typo from a field
+ that we removed.
+</p>
+
+<h2>The ledger: a migration is data, not code</h2>
+
+<p>
+ The core move is that a shape change is recorded, in a checked-in TOML file, as a list of structural
+ operations. Not a Python function — data. That is what lets the same record be replayed by the
+ command, rehearsed by the boot, verified by a gate, and read by a human.
+</p>
+
+<figure>
+<svg viewBox="0 0 720 250" role="img" aria-label="A ledger is a surface plus ordered entries, each entry a list of structural operations">
+ <rect class="svg-box-a" x="8" y="12" width="180" height="60" rx="6"/>
+ <text class="svg-t" x="22" y="34" font-weight="600">[surface]</text>
+ <text class="svg-m" x="22" y="52">id, base_file,</text>
+ <text class="svg-m" x="22" y="66">current_schema_version</text>
+
+ <rect class="svg-box" x="8" y="90" width="180" height="66" rx="6"/>
+ <text class="svg-t" x="22" y="112" font-weight="600">[[migration]] @2</text>
+ <text class="svg-t-s" x="22" y="130">breaking, safety,</text>
+ <text class="svg-t-s" x="22" y="146">pre_history, guidance</text>
+
+ <rect class="svg-box" x="8" y="174" width="180" height="66" rx="6"/>
+ <text class="svg-t" x="22" y="196" font-weight="600">[[migration]] @3</text>
+ <text class="svg-t-s" x="22" y="214">ordered — @2 addresses</text>
+ <text class="svg-t-s" x="22" y="230">the pre-rename spelling</text>
+
+ <path class="svg-line" d="M188 123 H236"/>
+ <polygon class="svg-arrow" points="236,119 246,123 236,127"/>
+ <path class="svg-line" d="M188 207 H236"/>
+ <polygon class="svg-arrow" points="236,203 246,207 236,211"/>
+
+ <rect class="svg-box" x="250" y="86" width="200" height="74" rx="6"/>
+ <text class="svg-t" x="264" y="108" font-weight="600">[[migration.ops]]</text>
+ <text class="svg-m" x="264" y="126">move_key</text>
+ <text class="svg-m" x="264" y="142">rename_key · delete_table</text>
+ <text class="svg-m" x="264" y="156">remap_value · ensure_table</text>
+
+ <rect class="svg-box" x="250" y="174" width="200" height="66" rx="6"/>
+ <text class="svg-t-s" x="264" y="196">structural kinds only —</text>
+ <text class="svg-t-s" x="264" y="212">an op that would WRITE a</text>
+ <text class="svg-t-s" x="264" y="228">value is refused at parse</text>
+
+ <path class="svg-line" d="M450 123 H498"/>
+ <polygon class="svg-arrow" points="498,119 508,123 498,127"/>
+
+ <rect class="svg-box-g" x="512" y="86" width="196" height="74" rx="6"/>
+ <text class="svg-t" x="526" y="108" font-weight="600">replay over a real file</text>
+ <text class="svg-t-s" x="526" y="128">text in → text out, plus a</text>
+ <text class="svg-t-s" x="526" y="144">plan: applied / blocked /</text>
+ <text class="svg-t-s" x="526" y="158">unexplained</text>
+
+ <text class="svg-t-s" x="512" y="196">One record, four readers:</text>
+ <text class="svg-t-s" x="512" y="212">the command, the boot,</text>
+ <text class="svg-t-s" x="512" y="228">the gates, and a human.</text>
+</svg>
+<figcaption>A ledger is a surface header plus ordered entries. Order matters: the entry that carries <code>[pipelex.prompting_config]</code> forward sits <em>below</em> the reshape, because it addresses a spelling that only exists while the root table is still called <code>[pipelex]</code>.</figcaption>
+</figure>
+
+<details>
+<summary>The reshape entry, as it actually ships</summary>
+<pre><code>[[migration]]
+id = "pipelex-config@3"
+to_schema_version = 3
+introduced_in = "0.46.0"
+breaking = true
+safety = "safe"
+title = "The configuration reshape: one scheme for the root"
+
+# Children move out of [pipelex] BEFORE [pipelex] itself is renamed, so the
+# rename that follows carries only what belongs to the interpreter.
+[[migration.ops]]
+kind = "move_key"
+table_path = ["pipelex"]
+key = "storage_config"
+new_table_path = ["runtime"]
+new_key = "storage"</code></pre>
+</details>
+
+<h3>The four surfaces</h3>
+
+<div class="tblwrap">
+<table>
+<thead><tr><th>Surface</th><th>Files it claims</th><th>Schema</th><th>Ships in 0.46.0</th></tr></thead>
+<tbody>
+<tr><td><code>pipelex-config</code></td><td><code>pipelex.toml</code> + <code>pipelex_*.toml</code></td><td>v3</td><td><code>@2</code> templating, <code>@3</code> reshape</td></tr>
+<tr><td><code>telemetry-config</code></td><td><code>telemetry.toml</code> + tiers</td><td>v2</td><td><code>@2</code> flat → <code>[custom_posthog]</code></td></tr>
+<tr><td><code>inference-backend</code></td><td><code>inference/backends/*.toml</code></td><td>v2</td><td><code>@2</code> drop <code>prompting_target</code></td></tr>
+<tr><td><code>pipelex-service-config</code></td><td><code>pipelex_service.toml</code></td><td>v1</td><td>baseline, no entries</td></tr>
+</tbody>
+</table>
+</div>
+
+<p>
+ The walk is deliberately narrow: the global <code>~/.pipelex/</code> and the project
+ <code>.pipelex/</code>, <strong>those two only</strong>, one level deep, and into a subdirectory only
+ when a configuration family owns it. <code>inference/backends/</code> is such a directory;
+ <code>inference/deck/</code> is not and is never entered. A file is claimed by the <em>pair</em>
+ (directory, name) — which is what stops <code>inference/backends/pipelex_gateway.toml</code>, a
+ <code>pipelex_*.toml</code> match by name, from being rewritten under the main config's ledger.
+</p>
+
+<h2>Boot tolerance: a stale file warns, it does not stop the world</h2>
+
+<p>
+ The command alone would not have been enough. A user upgrades, boots, and dies before they ever see
+ a message telling them to run it. So when a surface fails to validate, its ledger is replayed over
+ the same files <strong>in memory</strong> and the result re-validated.
+</p>
+
+<figure>
+<svg viewBox="0 0 720 300" role="img" aria-label="Boot tolerance decision flow">
+ <rect class="svg-box" x="250" y="8" width="200" height="38" rx="6"/>
+ <text class="svg-t" x="350" y="32" text-anchor="middle">load + validate config</text>
+
+ <path class="svg-line" d="M350 46 V74"/>
+ <polygon class="svg-arrow" points="346,74 350,84 354,74"/>
+
+ <rect class="svg-box-g" x="486" y="56" width="222" height="38" rx="6"/>
+ <text class="svg-t" x="597" y="80" text-anchor="middle">valid → boot. Zero cost:</text>
+ <path class="svg-line" d="M450 75 H486"/>
+ <polygon class="svg-arrow" points="486,71 496,75 486,79"/>
+ <text class="svg-t-s" x="597" y="110" text-anchor="middle">the engine is never even imported</text>
+
+ <rect class="svg-box-b" x="250" y="84" width="200" height="38" rx="6"/>
+ <text class="svg-t" x="350" y="108" text-anchor="middle">invalid</text>
+
+ <path class="svg-line" d="M350 122 V150"/>
+ <polygon class="svg-arrow" points="346,150 350,160 354,150"/>
+
+ <rect class="svg-box-a" x="228" y="160" width="244" height="42" rx="6"/>
+ <text class="svg-t" x="350" y="178" text-anchor="middle" font-weight="600">replay the ledger IN MEMORY</text>
+ <text class="svg-t-s" x="350" y="194" text-anchor="middle">nothing is written, ever</text>
+
+ <path class="svg-line" d="M228 181 H120 V226"/>
+ <polygon class="svg-arrow" points="116,226 120,236 124,226"/>
+ <path class="svg-line" d="M472 181 H600 V226"/>
+ <polygon class="svg-arrow" points="596,226 600,236 604,226"/>
+
+ <rect class="svg-box-g" x="14" y="236" width="212" height="54" rx="6"/>
+ <text class="svg-t" x="120" y="256" text-anchor="middle" font-weight="600">re-validates → BOOT</text>
+ <text class="svg-t-s" x="120" y="273" text-anchor="middle">warn, naming the files and</text>
+ <text class="svg-t-s" x="120" y="287" text-anchor="middle">`pipelex migrate`</text>
+
+ <rect class="svg-box-b" x="494" y="236" width="212" height="54" rx="6"/>
+ <text class="svg-t" x="600" y="256" text-anchor="middle" font-weight="600">still invalid → FAIL</text>
+ <text class="svg-t-s" x="600" y="273" text-anchor="middle">the user's own error stands —</text>
+ <text class="svg-t-s" x="600" y="287" text-anchor="middle">it names the key to fix</text>
+</svg>
+<figcaption>Tolerance widens what <em>starts</em>, never what is <em>accepted</em>: the re-validation is what decides, so material an <code>unsafe</code> entry is about still fails the boot because the model still refuses it.</figcaption>
+</figure>
+
+<details>
+<summary>Critical diff — the retry seam (<code>config_surface.py</code>)</summary>
+<div>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:.8rem 0">
+Two things in here are load-bearing and easy to break. The import is deferred for an
+<em>architectural</em> reason, not for speed; and a file that cannot be read abandons the whole retry
+rather than being skipped.
+</p>
+</div>
+<pre><code><span class="diff-add">+ # Imported here rather than at module level, and the reason is architectural: the
++ # engine's applier lives under an interpreter package, while this module sits in
++ # runtime_hub's import closure — the kernel layer, which loads zero interpreter modules.
++ from pipelex.migration.engine import replay_ledger_over_text # noqa: PLC0415
++
++ for path in paths:
++ try:
++ text = path.read_text(encoding="utf-8")
++ except FileNotFoundError:
++ continue
++ except (OSError, UnicodeDecodeError):
++ return None # <- abandon, do NOT skip: dropping a layer from the merge
++ # could re-validate green and boot a config the user
++ # does not actually have
++ replay = replay_ledger_over_text(ledger=ledger, text=text)
++ deep_update(merged, updates=tomlkit.loads(replay.text).unwrap())
++
++ if all(plan.is_clean for plan in plans):
++ return None # <- the ledger has nothing to say; not staleness.
++ # The caller's own error stands.</span></code></pre>
+</details>
+
+<div class="note">
+ <strong>A healthy configuration pays nothing.</strong> It reads no ledger, re-parses no document, and
+ does not even import the migration engine. That deferral is doubly required: the applier lives in the
+ interpreter layer and the config loaders sit in the kernel layer, which must not load it.
+</div>
+
+<h2>The gates: you cannot land a schema change without accounting for it</h2>
+
+<p>
+ A ledger nobody is forced to write is a ledger that will be forgotten on the one change that mattered.
+ Three checks close that.
+</p>
+
+<div class="tblwrap">
+<table>
+<thead><tr><th>Gate</th><th>Question it asks</th><th>Runs in</th></tr></thead>
+<tbody>
+<tr>
+ <td><code>make check-ledger</code><br><span class="pill">cl</span></td>
+ <td>Is what this entry <em>says</em> legal, and is replaying it harmless? An op may only act on material some version removed; replaying the whole ledger over the reference documents must return the very bytes it was given.</td>
+ <td><code>agent-check</code> + <code>check</code></td>
+</tr>
+<tr>
+ <td><code>make check-migration-schemas</code><br><span class="pill">cmig</span></td>
+ <td>Did a schema change go unaccounted for? Recomputes each surface's fingerprint and refuses a removed path, a lost enum spelling, or a narrowed value domain that no entry repairs. Also <em>performs</em> every migration against frozen before/after documents.</td>
+ <td><code>check</code> only</td>
+</tr>
+<tr>
+ <td><code>make up-migration-schemas</code><br><span class="pill">umig</span> <span class="pill">umigf</span></td>
+ <td>Regenerates the goldens. Deliberately <strong>left <code>make up</code></strong> — rewriting a head golden after deleting a field erases the very removal the gate exists to catch.</td>
+ <td>on purpose, by hand</td>
+</tr>
+</tbody>
+</table>
+</div>
+
+<div class="note warn">
+ <strong>Because <code>cmig</code> is not in <code>agent-check</code>,</strong> an unaccounted schema change
+ reaches a release unseen. That is why <code>/release</code> gained step 3b, which blocks on it and
+ confirms a <code>**Migration:**</code> changelog bullet for every new breaking entry.
+</div>
+
+<h3>Catching a narrowing — the class of change that looks additive</h3>
+
+<p>
+ A change can keep every path and every enumerated spelling and still break a user's file:
+ <code>int</code> becomes <code>str</code>, a free string becomes an enum, a bound moves from
+ <code>ge=1</code> to <code>ge=5</code>. Read as a path diff those look like <em>additions</em>, so the
+ gate used to ask for a golden regeneration, demand nothing, and let the next boot reject a valid file
+ with a green gate behind it. The verdict is now split by <strong>direction</strong>.
+</p>
+
+<p>
+ To see a bound at all, the fingerprint has to record one — which is why
+ <code>annotated-types</code> became a declared runtime dependency. It is a closed whitelist, and
+ <code>pattern</code> is excluded permanently: regex containment is not decidable, so every pattern edit
+ would read as a tightening and teach everyone to wave the gate through.
+</p>
+
+<details>
+<summary>Critical diff — the constraint whitelist (<code>fingerprint.py</code>)</summary>
+<pre><code><span class="diff-add">+ from annotated_types import Ge, Gt, Le, Lt, MaxLen, MinLen, MultipleOf
++
++ CONSTRAINT_ATTRIBUTE_BY_CARRIER: dict[type[Any], ConstraintKind] = {
++ Gt: ConstraintKind.GT, Ge: ConstraintKind.GE,
++ Lt: ConstraintKind.LT, Le: ConstraintKind.LE,
++ MinLen: ConstraintKind.MIN_LENGTH,
++ MaxLen: ConstraintKind.MAX_LENGTH,
++ MultipleOf: ConstraintKind.MULTIPLE_OF,
++ }
++ # pattern is excluded ON PURPOSE and permanently.</span></code></pre>
+<div>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:0 0 .8rem">
+The fingerprint is <em>not</em> raw <code>model_json_schema()</code> — that moves for reasons having
+nothing to do with our schema (ref layout, titles, ordering, pydantic's own version). A gate that cries
+wolf gets regenerated reflexively, and that is how a gate dies.
+</p>
+</div>
+</details>
+
+<h3>Replay neutrality, checked rather than asserted</h3>
+
+<p>
+ The guarantee every machine depends on: replaying a ledger over a file <em>already valid</em> changes
+ not one byte. The reference documents cannot prove it — they carry exactly one value per key, so they
+ never reach the other legal spelling of an enumerated field. <code>hypothesis</code> (dev-only) generates
+ documents that do, and checks neutrality, idempotence and prefix coherence.
+</p>
+
+<div class="note ok">
+ Each generator carries its own <strong>vacuity check</strong> —
+ <code>test_the_generator_does_not_merely_re_emit_the_reference_document</code>,
+ <code>test_the_generator_reaches_every_mutation_kind</code>. Every one of these properties is trivially
+ true over documents nothing acts on, so without those guards a green suite would prove nothing.
+</div>
+
+<h2>The breaking changes that rode along</h2>
+
+<details>
+<summary>The configuration root reshaped — <code>pipelex-config@3</code></summary>
+<div class="cols">
+ <div>
+ <p class="col-label">before</p>
+ <pre><code>[pipelex.log_config.rich_log_config]
+[pipelex.storage_config]
+[cogt.llm_config.instructor_config]
+[plugins]
+[migration.migration_maps]
+session_id = "..."</code></pre>
+ </div>
+ <div>
+ <p class="col-label">after</p>
+ <pre><code>[runtime.log.rich_log]
+[runtime.storage]
+[inference.llm.instructor]
+[runtime] / [inference]
+[interpreter] / [kit]
+# dropped</code></pre>
+ </div>
+</div>
+<div>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:0 0 .8rem">
+Four roots mirroring the layers the code already had. The redundant <code>_config</code> suffix goes at
+every depth — <em>class</em> names keep theirs, because the redundancy was in the key, not the type.
+Three things are dropped rather than moved: <code>[migration.migration_maps]</code>,
+<code>session_id</code>, and <code>plugins.boot_orchestrator</code> (now strictly a boot argument).
+</p>
+</div>
+</details>
+
+<details>
+<summary>Templating style is now an authoring decision — <code>pipelex-config@2</code> + <code>inference-backend@2</code></summary>
+<div>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:.8rem 0">
+How a pipe's inputs are tagged into a prompt is declared <em>on the pipe</em>, not inferred from the
+model — so the same method renders the same prompt shape everywhere. The global default is now XML tags
+instead of back-ticks, which means <strong>every prompt rendered for an OpenAI-family model changes
+shape</strong>. Compose, image-gen, search and structuring prompts follow the same default.
+</p>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:.8rem 0">
+This is the change that created the <code>inference-backend</code> surface. <code>#1104</code> deleted
+<code>prompting_target</code> from every backend file we ship — but those files were reachable by no
+surface, no walk and no gate, so the key survived on every installation that predates it, where it is
+fatal twice over: in <code>[defaults]</code> it is copied wholesale into every model of the file, and on
+a single model it is rejected by name.
+</p>
+</div>
+</details>
+
+<details>
+<summary>Unknown per-model backend keys must be header-shaped</summary>
+<div>
+<p style="font-size:.9rem;color:var(--ink-soft);margin:.8rem 0">
+An unrecognised key in a per-model table is sent to the provider as an HTTP header. That mechanism is
+now documented and gated on shape: it must contain a hyphen. A typo like <code>max_tokns</code> used to
+go out on the wire silently while the real setting stayed unset; it now fails the boot naming the key,
+the model and the file. The key must also be <em>usable</em> as a header — RFC 7230 token characters,
+printable single-line string value.
+</p>
+</div>
+</details>
+
+<h2>Working with this from now on</h2>
+
+<ol>
+ <li><strong>You change a config model.</strong> <code>make cmig</code> refuses, printing a fingerprint diff.</li>
+ <li><strong>Invoke the <code>add-migration</code> skill.</strong> It is the only thing that writes a ledger — it derives the entry from what the gate refused, bumps the schema version, regenerates the goldens and adds the changelog bullet.</li>
+ <li><strong>Never regenerate goldens to silence the gate.</strong> A green gate over an unaccounted removal is precisely the failure it exists to prevent.</li>
+ <li><strong>At release, step 3b blocks</strong> until every new breaking entry has a <code>**Migration:**</code> bullet naming its id, and a correct <code>introduced_in</code>.</li>
+</ol>
+
+<div class="note warn">
+ <strong>Dogfood finding from cutting this release.</strong> A stale untracked
+ <code>.pipelex/pipelex_override.toml</code> on a dev machine reddened three tests with
+ <code>Extra forbidden fields: 'pipelex'</code>. It is not a code defect — it is exactly the situation
+ this work exists for. Note that <code>pipelex migrate</code> has <em>no scoping flag</em>: it walks both
+ directories, so it will also rewrite your global <code>~/.pipelex/inference/backends/*.toml</code>.
+ Backups are automatic, but be aware if you share a global config across worktrees.
+</div>
+
+<h2>PR map</h2>
+
+<div class="tblwrap">
+<table>
+<thead><tr><th>PR</th><th>What landed</th></tr></thead>
+<tbody>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1104">#1104</a></td><td>Templating style as an authoring decision — retire <code>prompting_target</code></td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1106">#1106</a></td><td>Strict templating tables, keyless <code>pipelex run --dry-run</code></td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1109">#1109</a></td><td>Rogue outbound headers guard</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1110">#1110</a></td><td>Migrator Phases 0–1 — the contract, the operation vocabulary, the schema-1 cut</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1111">#1111</a></td><td>Configuration reshape: one scheme for the root</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1112">#1112</a></td><td>Migrator Phase 2 — the engine, the gates, the first real migration</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1113">#1113</a></td><td>Phase 3.1 — what an <code>unsafe</code> entry promises, catching a narrowing, the write path</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1114">#1114</a></td><td>Phase 3.2 — the migrate commands, boot tolerance</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1115">#1115</a></td><td>Phase 3.3 — the review obligation, the two skills</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1116">#1116</a></td><td>The <code>inference-backend</code> surface + the two pre-history entries</td></tr>
+<tr><td><a href="https://github.com/Pipelex/pipelex/pull/1117">#1117</a></td><td><strong>Release v0.46.0</strong> (open)</td></tr>
+</tbody>
+</table>
+</div>
+
+<div class="note">
+ <strong>Downstream, still pending.</strong> The MTHDS JSON Schema gained
+ <code>additionalProperties: false</code> on <code>TemplatingStyle</code> and <code>TemplateBlueprint</code>.
+ The committed copies in <code>mthds</code>, <code>vscode-pipelex</code> and <code>mthds-ui</code> are
+ release-gated and not yet synced — no PRs to link there yet.
+</div>
+
+<footer>
+ pipelex · <code>wip/migrator/what-we-built.html</code> · work-in-progress note for co-developers, not release documentation.
+</footer>
+
+</div>
+</body>
+</html>