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.

docs(codegen): say what a crate fingerprint actually covers (#1193)

Louis Choquelb7b6c563a564
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 14b8f5a2c..b703fc093 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@
### Fixed
+- **The codegen stamp reference no longer understates what moves a fingerprint:** [Codegen Projections](under-the-hood/codegen-projections.md) said a stamp moves only when a method's effective type surface changes, which would have a reader mistake an ordinary restamp for drift and expect a prompt edit to leave the generated tree alone. The crate fingerprint is computed over the whole normalized crate — concepts, pipes and domains — so an edited `system_prompt` or a swapped model restamps every generated file exactly as a renamed concept field does, with the body below the fence byte-identical. `content_hash`, in the stamp header and in the lock's `artifacts[]` entries, is what distinguishes that harmless restamp from a real change to the generated code. The `pipelex/codegen/stamp.py` module docstring carried the same understatement and was corrected with it.
- **Compound version constraints written the documented way now parse:** `parse_constraint` stripped no whitespace around the comma that ANDs a compound constraint's clauses, so `>=1.0.0, <2.0.0` — the exact spelling of the MTHDS standard's own example — was rejected while the identical `>=1.0.0,<2.0.0` parsed. A manifest's `mthds_version` written that way therefore got no compatibility check at all, since the load path degrades an unparseable constraint to a log line. A malformed compound such as `>=1.0.0,,<2.0.0` still fails, because normalizing whitespace must not repair a broken constraint.
## [v0.56.0] - 2026-09-03
diff --git a/docs/under-the-hood/codegen-projections.md b/docs/under-the-hood/codegen-projections.md
index 6d220f291..b962a0c9c 100644
--- a/docs/under-the-hood/codegen-projections.md
+++ b/docs/under-the-hood/codegen-projections.md
@@ -77,7 +77,7 @@ Drift — generated code that no longer matches the method it was generated from
# <<< pipelex-codegen-stamp <<<
```
-The `crate_fingerprint` is the crate's semantic hash, so reformatting or commenting a `.mthds` file never changes a stamp — only a change to the method's effective type surface does. The `content_hash` is a SHA-256 over the body **below** the stamp, so a lone file can testify that it has not been hand-edited, without the engine, the network, or the lock.
+The `crate_fingerprint` is the crate's *semantic* hash, so reformatting or commenting a `.mthds` file never changes a stamp. What it covers is the whole normalized crate — concepts, pipes and domains — and not only the slice a given projection emits, so an edited `system_prompt` or a swapped model moves it exactly as a renamed concept field does. The consequence reads as drift at first sight and is not: a prompt-only edit brings every generated file back restamped with a one-line diff, the `crate_fingerprint` line, while the body below the fence stays byte-identical. The `content_hash` is a SHA-256 over that body, so a lone file can testify that it has not been hand-edited, without the engine, the network, or the lock — and it is what tells a harmless restamp apart from a real change to the generated code, both in the stamp header and in the lock's `artifacts[]` entries.
The header itself is read strictly, because the content hash covers only what is *below* it. Every line between the fences must carry the file's comment prefix, so a line injected into the block — an uncommented statement sitting inside a header that says `DO NOT EDIT`, or a blank line — makes the stamp unparseable, which the offline check reports as **hand-edited**. What counts as a line there is deliberately wider than `\n`: the reader breaks wherever Python's `str.splitlines()` breaks, U+2028 and U+2029 included, because those two terminate a `//` comment in JavaScript. A TypeScript artifact whose header carried one raw would be a single commented line to a narrower reader and two lines to the engine running it — executable text inside the header, on a file the check would still call current, since the hash covers only the body. The second implementation of the check splits on the same set, so both readers reach the same verdict. The `options` value must be conformant JSON: Python's non-standard `NaN` / `Infinity` / `-Infinity` literals are refused, since the stamp header is a cross-language interchange format and a stamp only one language can read is not a valid stamp. None of this is a signature — there is no MAC anywhere, and the real defence against a malicious edit is diff review; the rule exists so a file that claims to be pristine cannot quietly carry code that was edited in.
diff --git a/pipelex/codegen/stamp.py b/pipelex/codegen/stamp.py
index 4deab14cd..3bc1fa86a 100644
--- a/pipelex/codegen/stamp.py
+++ b/pipelex/codegen/stamp.py
@@ -7,8 +7,12 @@ artifacts), any output-affecting options, and a **content hash of the body below
hand edit anywhere under the stamp is detectable without the engine, the network, or the lock.
The stamp hashes the crate fingerprint (the semantic hash), not raw authored bytes: reformatting or
-commenting a `.mthds` file never changes a stamp; changing a method's effective type surface always
-does. The block is emitted in the target language's comment syntax (`#` for Python, `//` for
+commenting a `.mthds` file never changes a stamp. The fingerprint covers the whole normalized crate
+— concepts, pipes and domains — not only the slice a projection emits, so any semantic edit moves it:
+an edited prompt or a swapped model exactly as much as a renamed concept field. `content_hash`, not
+`crate_fingerprint`, is what tells such a restamp apart from a real change to the generated body.
+
+The block is emitted in the target language's comment syntax (`#` for Python, `//` for
TypeScript), delimited by `>>> … >>>` / `<<< … <<<` fences so the offline check can split stamp from
body byte-exactly and recompute the hash.
"""