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.

Pin LF line endings in the index, and pin the stamp header's line-boundary rule (#1128)

Louis Choqueladc952902df3
diff --git a/.badges/tests.json b/.badges/tests.json
index bce3ad50b..d3bfebd01 100644
--- a/.badges/tests.json
+++ b/.badges/tests.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"label": "tests",
- "message": "10565",
+ "message": "10569",
"color": "blue",
"cacheSeconds": 300
}
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000..35fe964cd
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,14 @@
+# Line endings are normalised to LF in the index and on checkout, on every platform.
+#
+# The repo carries a lot of *generated but committed* text — CLAUDE.md and AGENTS.md, subject_grants.toml,
+# .drift/acks/*.toml, .test_durations, tests/data/errors/error_identity.txt, docs/errors/*.md, the migration
+# goldens, the gateway model references — and each is produced by a writer that does not pass an explicit
+# `newline` argument, so on Windows Python translates every "\n" to CRLF and the whole set churns in version
+# control with no change of content. The gates would not notice: they all compare with universal-newline
+# reads, which fold CRLF back to LF before the comparison. This file closes that class for tracked files
+# regardless of which writer produced them; see wip/line-endings-writer-sweep.md for the writer-by-writer
+# half, which is the structural fix and is tracked separately.
+#
+# `text=auto` leaves git to detect text from binary, so images and other binaries are untouched. No tracked
+# file contained CRLF when this landed, so it introduces no renormalisation diff — it pins the invariant.
+* text=auto eol=lf
diff --git a/docs/under-the-hood/codegen-projections.md b/docs/under-the-hood/codegen-projections.md
index fdcf28101..1fec34da0 100644
--- a/docs/under-the-hood/codegen-projections.md
+++ b/docs/under-the-hood/codegen-projections.md
@@ -68,7 +68,7 @@ Drift — generated code that no longer matches the method it was generated from
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 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**. 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.
+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.
In the other direction the header is deliberately tolerant: a *commented* `key: value` line the reader does not recognise is ignored rather than rejected, so the stamp can gain a field without breaking readers built against an earlier shape.
@@ -93,7 +93,7 @@ The verdict rides the exit code (mirroring `resolve` / `validate`): `0` current,
### Idempotent emission
-`pipelex/codegen/emission.py` ties it together in two layers. `build_stamped_projection` is the **pure** core: it stamps each emitted body and assembles the matching `codegen.lock` content — no filesystem access — so it is the single source of truth for what a projection *is* on disk. `write_stamped_projection` rides it to materialize locally: it writes each file only when its content changed (write-if-changed — no mtime churn, clean diffs, watch-mode friendly), removes any previously-tracked stamped file that dropped out of the set, and rewrites the lock. Only files the tool itself stamped are ever removed, so a hand-authored file sharing the output directory is never touched. `codegen inputs` applies the same write-if-changed rule to its single (unstamped) template file, so a full regeneration pass over a committed consumer is a true no-op when everything is current. Every artifact is written with LF line endings whatever the platform, because Python would otherwise translate each newline to the host's convention: the same projection emitted on Windows and on Linux would land as different bytes while both recorded the same content hash, and a team mixing the two would watch the generated tree churn in version control with no change of content. Byte-identical regeneration is a promise across machines, not only within one. The ownership test that governs removal governs overwriting too, and it runs before the first byte is written, so a refused run leaves the tree exactly as it found it: the writer declines any destination already holding a file it cannot prove it owns — one neither tracked by the lock nor parseable as stamped. That is where the strict header gate has a visible edge. A stamped file **the lock does not track** still scans as stamped, so the check calls it an **orphan** and advises "remove or regenerate" — but a tampered header no longer *parses*, so regeneration cannot prove it owns the file and declines to reclaim it; removing it is the half of that advice that always applies. A **lock-tracked** file whose header was tampered with is the other case entirely: the lock is the ownership proof, so the check reports it as **hand-edited** and regeneration overwrites it. The writer is deliberately unwilling to clobber a file that may hold real work.
+`pipelex/codegen/emission.py` ties it together in two layers. `build_stamped_projection` is the **pure** core: it stamps each emitted body and assembles the matching `codegen.lock` content — no filesystem access — so it is the single source of truth for what a projection *is* on disk. `write_stamped_projection` rides it to materialize locally: it writes each file only when its content changed (write-if-changed — no mtime churn, clean diffs, watch-mode friendly), removes any previously-tracked stamped file that dropped out of the set, and rewrites the lock. Only files the tool itself stamped are ever removed, so a hand-authored file sharing the output directory is never touched. `codegen inputs` applies the same write-if-changed rule to its single (unstamped) template file, so a full regeneration pass over a committed consumer is a true no-op when everything is current. Every artifact is written with LF line endings whatever the platform, because Python would otherwise translate each newline to the host's convention: the same projection emitted on Windows and on Linux would land as different bytes while both recorded the same content hash, and a team mixing the two would watch the generated tree churn in version control with no change of content. Byte-identical regeneration is a promise across machines, not only within one. Ownership governs overwriting as well as removal, but the two tests are not the same one, and the overwrite test is the stricter: pruning asks only whether a file still carries our stamp markers, while overwriting demands a header that actually parses. The overwrite test runs before the first byte is written, so a refused run leaves the tree exactly as it found it: the writer declines any destination already holding a file it cannot prove it owns — one neither tracked by the lock nor parseable as stamped. That is where the strict header gate has a visible edge. A stamped file **the lock does not track** still scans as stamped, so the check calls it an **orphan** and advises "remove or regenerate" — but a tampered header no longer *parses*, so regeneration cannot prove it owns the file and declines to reclaim it; removing it is the half of that advice that always applies. A **lock-tracked** file whose header was tampered with is the other case entirely: the lock is the ownership proof, so the check reports it as **hand-edited** and regeneration overwrites it. The writer is deliberately unwilling to clobber a file that may hold real work.
### Lint-clean by construction
diff --git a/pipelex/codegen/stamp.py b/pipelex/codegen/stamp.py
index f14f6fec7..4deab14cd 100644
--- a/pipelex/codegen/stamp.py
+++ b/pipelex/codegen/stamp.py
@@ -139,6 +139,18 @@ def parse_stamped(text: str, *, comment_prefix: str) -> ParsedStamp | None:
# Every line we ever write inside the fence carries the comment prefix, so anything else in there
# was injected by hand — and it would otherwise verify as pristine, since the hash covers only the
# body below the fence. An executable line hiding inside a "DO NOT EDIT" block is not a valid stamp.
+ #
+ # `splitlines` is the deliberate choice over splitting on `"\n"` alone: it also breaks on U+2028,
+ # U+2029 and U+0085, and the first two terminate a `//` comment in ECMAScript. Split narrowly, a `.ts`
+ # header carrying a raw U+2028 followed by a statement is one prefixed line to this gate and two lines
+ # to the JavaScript engine — so `codegen check` would report the file current while it executes the
+ # injected code, since the header itself is not hashed. The SDK's mirror of this parser splits on the
+ # same set for the same reason (`PYTHON_LINE_BOUNDARY` in `@pipelex/sdk`'s `codegen-check.ts`).
+ #
+ # Nothing legitimate is rejected, because the emitter cannot write such a header: no caller supplies
+ # `pipe_ref` or `options`, and the four fields that are written are two hex digests, a package version
+ # and two enum members. If either field ever carries real data, escape the line terminators *at the
+ # emitter* then — this gate stays correct, because the emitter will never write a raw one.
if any(not line.startswith(comment_prefix) for line in header_region.splitlines()):
return None
@@ -174,6 +186,9 @@ def has_stamp(text: str, *, comment_prefix: str) -> bool:
def _parse_fields(header_region: str, *, comment_prefix: str) -> dict[str, str]:
fields: dict[str, str] = {}
+ # Same split rule as the gate in `parse_stamped`, and it has to stay the same one: a narrower split
+ # here would rejoin a line the gate had already split, so a field value would swallow the injected
+ # text the gate exists to catch.
for raw_line in header_region.splitlines():
# `parse_stamped` has already rejected any line without the prefix, so stripping it is unconditional.
stripped = raw_line[len(comment_prefix) :].strip()
diff --git a/tests/unit/pipelex/codegen/test_stamp.py b/tests/unit/pipelex/codegen/test_stamp.py
index 041e75026..14f08101b 100644
--- a/tests/unit/pipelex/codegen/test_stamp.py
+++ b/tests/unit/pipelex/codegen/test_stamp.py
@@ -86,6 +86,25 @@ class TestStamp:
injected = stamped.replace("# options: {}", "\n# options: {}")
assert parse_stamped(injected, comment_prefix="#") is None
+ @pytest.mark.parametrize("line_boundary", ["\u2028", "\u2029", "\u0085"])
+ def test_a_header_value_carrying_a_unicode_line_boundary_is_rejected(self, line_boundary: str) -> None:
+ r"""A raw line boundary inside a header value makes the stamp unparseable — why both header splits use `splitlines`.
+
+ U+2028 and U+2029 terminate a `//` comment in ECMAScript. Under a `"\n"`-only split, a `.ts` header
+ carrying one is a single prefixed line to this gate and two lines to the JavaScript engine: the
+ injected statement executes while `codegen check` still calls the file current, because the header
+ is not covered by the content hash. U+0085 is inert to a JS engine but breaks a line to `splitlines`
+ just the same, and one gate covers all three.
+
+ Nothing legitimate is rejected — no caller supplies `pipe_ref` or `options`, so the emitter cannot
+ write a header this refuses.
+ """
+ # The payload must not itself open with `//`, or it would be a comment on the JS side too.
+ options = {"note": f"before{line_boundary}globalThis.pwned = 1;//"}
+ stamped = self._stamp("export const x = 1;\n", comment_prefix="//", options=options)
+
+ assert parse_stamped(stamped, comment_prefix="//") is None
+
def test_commented_unknown_field_still_parses(self) -> None:
# Additive tolerance, pinned: a stamp gaining a field stays readable by today's parser, which
# is why the stamp header carries no version of its own. Over-tightening the gate would break it.
@@ -95,7 +114,10 @@ class TestStamp:
assert parsed is not None
assert parsed.stamp.crate_fingerprint == "fp-123"
- @pytest.mark.parametrize("options_value", ['{"x": NaN}', '{"x": Infinity}', '{"x": -Infinity}', "Infinity"])
+ # A bare top-level constant is deliberately not in this list: `_parse_options` already rejects any
+ # non-object payload, so that case stays green with the `parse_constant` guard removed and would
+ # pin nothing. Every case here must be one the guard alone catches.
+ @pytest.mark.parametrize("options_value", ['{"x": NaN}', '{"x": Infinity}', '{"x": -Infinity}', '{"a": 1, "b": NaN}'])
def test_non_standard_json_constants_in_options_are_rejected(self, options_value: str) -> None:
# Python's `json` accepts these; no conformant JSON parser does. The stamp header is a
# cross-language interchange format, so a stamp only Python can read is not a valid stamp.
diff --git a/tests/unit/pipelex/tools/misc/test_save_text_to_path.py b/tests/unit/pipelex/tools/misc/test_save_text_to_path.py
index 0564b0862..048eab134 100644
--- a/tests/unit/pipelex/tools/misc/test_save_text_to_path.py
+++ b/tests/unit/pipelex/tools/misc/test_save_text_to_path.py
@@ -1,17 +1,37 @@
"""`save_text_to_path` writes LF on every platform, so generated artifacts are byte-identical everywhere."""
+from __future__ import annotations
+
from pathlib import Path
+from typing import TYPE_CHECKING
from pipelex.tools.misc.file_utils import load_text_from_path, save_text_to_path
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
class TestSaveTextToPath:
+ def test_the_lf_guarantee_is_handed_to_the_writer(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ r"""The discriminating test of the pair: it pins the argument, not `os.linesep`'s opinion.
+
+ The byte-level tests below cannot fail on a POSIX runner, and CI is Linux-only — so dropping
+ `newline="\n"` would leave every gate green. Asserting the call reaches `write_text` with it is
+ platform-independent, so this one goes red the moment the guarantee is removed.
+ """
+ write_text = mocker.patch.object(Path, "write_text")
+
+ save_text_to_path("line one\n", path=tmp_path / "artifact.py")
+
+ assert write_text.call_args.kwargs.get("newline") == "\n"
+ assert write_text.call_args.kwargs.get("encoding") == "utf-8"
+
def test_newlines_are_written_as_lf(self, tmp_path: Path) -> None:
r"""No `\r` reaches the disk, whatever `os.linesep` says.
- This is a tripwire, not a discriminating test: on POSIX `os.linesep` is already `\n`, so it
- passes with or without the fix. It goes red the day a Windows runner appears, or the day the
- explicit `newline` argument is dropped — which is exactly when the guarantee would break.
+ A tripwire rather than a discriminating test: on POSIX `os.linesep` is already `\n`, so it passes
+ with or without the fix, and it is the test above that actually pins the guarantee. This one
+ documents the observable outcome, and goes red on its own the day a Windows runner appears.
"""
target = tmp_path / "artifact.py"
save_text_to_path("line one\nline two\n", path=target)
@@ -23,7 +43,7 @@ class TestSaveTextToPath:
With the default translating write, a `\r\n` in the string becomes `\r\r\n` on Windows because
only the `\n` is translated. Pinning `newline="\n"` disables translation entirely, so the text is
- the file.
+ the file. Also a POSIX tripwire — the call-args test is what pins this on a Linux runner.
"""
target = tmp_path / "crlf.txt"
save_text_to_path("first\r\nsecond\r\n", path=target)
diff --git a/wip/codegen/sdk-followups.md b/wip/codegen/sdk-followups.md
index 14c26db66..07f3597ec 100644
--- a/wip/codegen/sdk-followups.md
+++ b/wip/codegen/sdk-followups.md
@@ -23,9 +23,9 @@ Cross-repo sequencing constraint, stated once: `src/codegen-check.ts` in `pipele
## Cold start — read this first
-**Status: Phases 1–5 done and committed (Checkpoint 4 reached). All five upstream items are implemented, tested, documented and swept. What is left is not code: the SDK follow-up must be triaged into `pipelex-sdk-js` and released before this branch's release, and two PR #31 threads want a reply. See the end of Phase 5.**
+**Status: Phases 1–5 done and committed (Checkpoint 4 reached). All five upstream items are implemented, tested, documented and swept. What is left is not code and it is one thing: the SDK follow-up has been delivered into `pipelex-sdk-js`, but an `@pipelex/sdk` that tolerates `lock_version` must be *published* before this branch's release. Every PR #31 thread is resolved; nothing there is waiting on a reply. See the end of Phase 5.**
-**Where the work is.** Branch `feature/Codegen-followups` in `pipelex/`, cut from `d28e703e3` (v0.46.4). Phase 1 is one commit, Phases 2–3 a second, Phase 4 a third, Phase 5 a fourth. Nothing is pushed. When this eventually becomes a PR it targets `dev`, never `main`.
+**Where the work is.** Branch `feature/Codegen-followups` in `pipelex/`, cut from `d28e703e3` (v0.46.4). Phase 1 is one commit, Phases 2–3 a second, Phase 4 a third, Phase 5 a fourth. The branch is pushed and open as PR #1127 against `dev` (never `main`), with every CI check green.
**Verify the tree is green before touching anything** (about a minute):
@@ -210,12 +210,12 @@ Everything else was confirmed already in place: § Stamps carries the header-str
`make agent-check` clean, `.badges/tests.json` refreshed to the count the added test produced, and the full `make agent-test` green.
-**Checkpoint 4 — REACHED (2026-08-19), committed on `feature/Codegen-followups`.** The code work for U1–U5 is complete. Two items remain, neither of them code, and the first one gates the release:
+**Checkpoint 4 — REACHED (2026-08-19), committed on `feature/Codegen-followups`.** The code work for U1–U5 is complete. One item remains, and it is not code — it gates the release. The second is kept below as a closed record rather than as work:
1. ⚠ **The SDK follow-up is delivered; the release gate is now an SDK *release*, not a filing.** Triaged out of the workspace inbox on 2026-08-19 and delivered into `pipelex-sdk-js` as `wip/upstream-codegen-followups-mirror.md`, committed on `feature/Codegen-follow-ups` (the PR #31 branch) as "docs: record what the upstream codegen landing requires of this SDK". It carries the four rules to mirror, the read-the-version-before-the-key-set ordering trap, the fixture refresh, and a direction table for all five items — the SDK's own `pr-31-review-notes.md` gained per-item status lines in the same commit, since its claim that nothing had been filed upstream was no longer true. **What still blocks a pipelex release is unchanged in substance:** until an `@pipelex/sdk` that tolerates `lock_version` is *published*, the very release that fixes U3 causes the failure U3 describes in every consumer's CI, because their `rejectUnknownKeys` hard-throws on the new key. Record the published `@pipelex/sdk` version here before cutting a pipelex release.
-2. **The open PR #31 threads want a reply** (`chatgpt-codex-connector` and `cubic-dev-ai`, both on item 1 of `../pipelex-sdk-js/wip/pr-31-review-notes.md`, which says explicitly that they stay open until U1 lands upstream). U1 has landed *on this branch* — but the branch is unpushed and unreleased, so a reply can only say "fixed upstream, pending release", not "shipped". Drafts for both were written on 2026-08-19 and are with Louis; nothing has been posted, since posting to a public PR is his call.
+2. **The PR #31 threads are now all resolved — this item is closed.** It read, until 2026-08-19, that two threads (`chatgpt-codex-connector` and `cubic-dev-ai`, both on item 1 of `../pipelex-sdk-js/wip/pr-31-review-notes.md`) were waiting on a reply, and a later correction raised the count to five. Every review thread on PR #31 now reports resolved, so nothing there is blocking. Kept as a record of what the replies had to say, not as work: U1 has landed on this branch and is unreleased, so any reply could only claim "fixed upstream, pending release", never "shipped".
- A count correction worth carrying: PR #31 has **five** unresolved threads, not two. Besides the two U1 ones, a third (`cubic-dev-ai`, `src/codegen-check.ts:552`, the drift-ordering deferral) is materially changed by Phase 2 — upstream converged on the SDK's own full-string comparator, closing the reachable ASCII half of that finding — so it got a draft too. The remaining two are SDK-only and untouched by this work: the `WINDOWS_DRIVE = /^.:/u` regex missing U+2028 / U+2029 (verified real from this side — `validate_artifact_path` rejects `\u2028:models.py` as a drive prefix, and U+2028 is `Zl` so the control-character gate does not catch it first, leaving the SDK the permissive side), and a duplicated CRLF test row. Both are recorded at the end of the delivered SDK doc.
+ A count correction worth carrying, from when these were open: PR #31 had **five** unresolved threads, not two. Besides the two U1 ones, a third (`cubic-dev-ai`, `src/codegen-check.ts:552`, the drift-ordering deferral) is materially changed by Phase 2 — upstream converged on the SDK's own full-string comparator, closing the reachable ASCII half of that finding — so it got a draft too. The remaining two are SDK-only and untouched by this work: the `WINDOWS_DRIVE = /^.:/u` regex missing U+2028 / U+2029 (verified real from this side — `validate_artifact_path` rejects `\u2028:models.py` as a drive prefix, and U+2028 is `Zl` so the control-character gate does not catch it first, leaving the SDK the permissive side), and a duplicated CRLF test row. Both are recorded at the end of the delivered SDK doc.
## Cross-repo follow-ups (recorded here, **not** work in this repo)
diff --git a/wip/line-endings-writer-sweep.md b/wip/line-endings-writer-sweep.md
new file mode 100644
index 000000000..3428b79d0
--- /dev/null
+++ b/wip/line-endings-writer-sweep.md
@@ -0,0 +1,43 @@
+# Line endings: the writer-by-writer half
+
+Surfaced by the U4 fix on `feature/Codegen-followups` (PR #1127), during the `/review` pass on 2026-08-19. **Not a codegen item** — U4 is closed and every codegen write path is covered. This is the pre-existing repo-wide residue that U4 made visible, and it is deliberately not part of that PR.
+
+## What is already done
+
+`.gitattributes` now carries `* text=auto eol=lf`, so every **tracked** file is normalised to LF in the index and on checkout whatever the platform. That closes the user-visible half of the problem — no churning diffs, no CRLF landing in a commit — and it cost one line. No tracked file contained CRLF when it landed, so it introduced no renormalisation diff.
+
+## What is left, and why it still matters
+
+`.gitattributes` fixes the files git owns. It does not fix the writers, and two things still follow from that:
+
+- A file written **outside** a git checkout (a consumer's output directory, a temp tree, a container) still lands with the host's line endings.
+- A content hash taken over an in-memory LF string still stops describing the bytes on disk, which is the property `save_text_to_path` was fixed to restore.
+
+Each site below writes a **tracked** artifact today and passes no `newline` argument, so Python translates every `\n` to `os.linesep`. The fix in each case is the same one U4 applied: route the write through `pipelex.tools.misc.file_utils.save_text_to_path`, which passes `newline="\n"`.
+
+| Site | Writes | Gated by |
+|---|---|---|
+| `pipelex/kit/single_file_agent_rules.py:139` | repo-root `CLAUDE.md`, `AGENTS.md` | `make check-rules` |
+| `pipelex/tools/misc/toml_utils.py:75` (`save_toml_to_path`) | `subject_grants.toml`, `.drift/acks/*.toml` | `make check-keyword-only`, `make drift-check` |
+| `pipelex/migration/goldens.py:105,112` | `pipelex/migration/goldens/**` | `make check-migration-schemas`, `make check-ledger` |
+| `pipelex/errors/error_pages_generator.py:367` | `docs/errors/*.md` | `make docs-check` |
+| `pipelex/cli/dev_cli/commands/generate_error_identity_cmd.py:44` | `tests/data/errors/error_identity.txt` | `test_error_identity_snapshot.py` |
+| `pipelex/cli/dev_cli/commands/duration_map.py:66` | `.test_durations` | `test_test_durations_paths.py` |
+| `pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py:142-143` | the gateway model reference pairs | `make check-gateway-models` |
+| `pipelex/cli/dev_cli/commands/keyword_only_guard.py:923` | any `pipelex/**/*.py` the fixer rewrites | `make check-keyword-only` |
+| `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:198` | `pipelex/graph/reactflow/standalone_assets.py` | manual |
+| `pipelex/graph/graph_factory.py:159-177` | graphspec JSON, Mermaid, ReactFlow HTML | not tracked; user output |
+| `pipelex/cogt/models/deck_manifest.py:160` | `.pipelex/inference/deck/.kit_manifest.json` | not diff-gated |
+
+`save_toml_to_path` is the one that is not a one-liner: it hands an open file to `tomlkit.dump` rather than writing a string, so it needs `open(path, "w", encoding="utf-8", newline="\n")` instead of a call swap.
+
+## The trap that hid this
+
+The sweep behind U4 grepped for `os.linesep` and found nothing, which read as a clean bill. That is the wrong probe: the bug is the **absence** of an explicit `newline="\n"`, never the presence of `os.linesep`. Grep for `write_text(` and `open(..., "w")` instead.
+
+The second trap is why none of the gates above would have caught it. Every one of them compares a freshly rendered string against `path.read_text(...)`, and that read uses universal newlines — so it folds CRLF back to LF *before* the comparison. A CRLF-corrupted committed file passes its own freshness check while being byte-different from what the tool writes. The check is blind to exactly the corruption it looks like it would catch.
+
+## Known, and deliberately left alone
+
+- **`keyword_only_guard.py` reads with translation too**, so its CRLF-preservation branch in `fix_source` — the one `test_crlf_line_endings_preserved_and_fixed` pins byte-for-byte — is unreachable through the only caller that touches the filesystem. Fixing the write without deciding the read leaves it half-done. The open question is whether the fixer should genuinely preserve CRLF (read and write with `newline=""`) or declare itself LF-only and delete the branch. Decide that on its own terms.
+- **`load_text_from_path` still reads with universal newlines** while `save_text_to_path` now writes verbatim. One consequence is worth knowing rather than fixing: a generated file already on disk as CRLF reads back as LF, compares equal to the canonical content, and is therefore never rewritten by `_write_if_changed` — so the LF fix does not heal a tree that was already corrupted, it only stops new corruption. The tree is stable either way (nothing rewrites it, so nothing churns), which is why this is a note and not a bug.
diff --git a/wip/pr-1128-review-notes.md b/wip/pr-1128-review-notes.md
new file mode 100644
index 000000000..3f0138c6e
--- /dev/null
+++ b/wip/pr-1128-review-notes.md
@@ -0,0 +1,20 @@
+# PR #1128 — deferred review finding
+
+Surfaced while triaging the review-agent comments on PR #1128 (`feature/Line-endings-sweep`) on 2026-08-19. Everything else the bots raised was either fixed on the branch or resolved as a false positive; this is the one item deliberately left for later, because it is well outside the PR and wants its own test pass.
+
+## `is_snake_case` accepts a trailing newline
+
+`pipelex/tools/misc/string_utils.py:282` anchors its pattern with `$`:
+
+```python
+def is_snake_case(word: str) -> bool:
+ return re.match(r"^[a-z][a-z0-9_]*$", word) is not None
+```
+
+In Python `$` matches at the end of the string **or immediately before a trailing newline**, so `is_snake_case("abc\n")` returns `True` while `is_snake_case("abc\ndef")` correctly returns `False`. Verified by execution.
+
+That admits a pipe code or domain code ending in a newline through the two validators built on it: `pipelex/pipe_machinery/validation.py:126` (`is_pipe_code_valid`) and `pipelex/core/domains/validation.py:26`, both wired into the bundle parser at `pipelex/mthds_parsing/pipelex_bundle_blueprint.py:113-121` and `:149,181`.
+
+**Why it was not fixed here.** It reached this review only as a side question — whether a `pipe_ref` could carry a line terminator into a codegen stamp header. Through the stamp it cannot do harm either way: a raw `\n` breaks the header line under any split rule, so the stamp gate rejects it, and no codegen caller populates `pipe_ref` in the first place. The gap is real but it belongs to identifier validation generally, not to codegen.
+
+**The fix and what it costs.** Swap `$` for `\Z`, which matches only at the true end of the string. The change is one character, but it tightens every code that flows through those two validators, so it wants a deliberate pass: a test for the trailing-newline case on both validators, and a check that no fixture or example bundle in the tree currently relies on the loose behaviour.