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.
Make the TypeScript emission gates mandatory in CI (#1184)
Louis Choquel753737d459dd
diff --git a/.github/workflows/tests-check.yml b/.github/workflows/tests-check.ymlindex a4a35ecf2..22a282406 100644--- a/.github/workflows/tests-check.yml+++ b/.github/workflows/tests-check.yml@@ -68,19 +68,58 @@ jobs:fi# ---------------------------------------------------------------------------# 2. Aggregator job — the *single* required status check+# 2. TypeScript emission gates — the two codegen tests that need node.+# The shards above run them too, and there they skip: `prettier --check`+# is the only test that PARSES the emitted TypeScript, and the zod round+# trip is the only one that EXECUTES it, so with no node toolchain the+# emitter's whole content contract was unguarded — three defects reached+# review that way, each caught afterwards by a hand-written assertion.+# This job provisions a pinned toolchain and sets PIPELEX_REQUIRE_TS_GATES,+# under which those tests fail instead of skipping. One job, not a node+# step on all 8 shards: the codegen suite is seconds and lands in one shard.+# --------------------------------------------------------------------------+ ts-emission-gates:+ name: Tests (ts emission gates)+ runs-on: ubuntu-latest+ env:+ VIRTUAL_ENV: ${{ github.workspace }}/.venv+ ENV: dev+ steps:+ - uses: actions/checkout@v4++ - name: Install uv (with cache)+ uses: astral-sh/setup-uv@v7+ with:+ enable-cache: true+ cache-dependency-glob: "uv.lock"++ # >= 22.6 for `--experimental-strip-types`, which is what lets node run the emitted `.ts`.+ - name: Install node+ uses: actions/setup-node@v4+ with:+ node-version: "24"++ - name: Install dependencies+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install++ - name: Run the TypeScript emission gates+ run: make test-ts-gates++# --------------------------------------------------------------------------+# 3. Aggregator job — the *single* required status check# Guards against a silently-dropped shard: fails unless ALL 8 succeed.# --------------------------------------------------------------------------tests-all:name: Tests (all)runs-on: ubuntu-latest- needs: [matrix-test]+ needs: [matrix-test, ts-emission-gates]if: always()steps:- name: Fail if any test job failedrun: |- if [ "${{ needs.matrix-test.result }}" != "success" ]; then+ if [ "${{ needs.matrix-test.result }}" != "success" ] || \+ [ "${{ needs.ts-emission-gates.result }}" != "success" ]; thenecho "::error::At least one test job failed."exit 1fidiff --git a/.gitignore b/.gitignoreindex 999d3ddd6..b345b78e2 100644--- a/.gitignore+++ b/.gitignore@@ -82,9 +82,11 @@ mthds-wip# Derived artifacts (auto-generated, not tracked)derived/-# Node.js (used only for syncing mthds-ui graph viewer assets)+# Node.js (syncing mthds-ui graph viewer assets, and the pinned toolchain `make ts-toolchain`+# installs for the TypeScript emission gates — provisioned on demand, never committed)node_modules/package-lock.json+.ts-toolchain/# Claude plans.claude/plans/diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2fe60fa42..643d8ba47 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@### Added+- **`make test-ts-gates`** (alias `make ttg`): the TypeScript emission gates, provisioned and made mandatory. The `ts-zod` target promises its bytes are already what prettier would write — a codegen stamp is a hash over those bytes, so anything less has a consumer's first `prettier --write` report an untouched artifact as hand-edited. Two tests actually read the emission rather than measuring its lines: `prettier --check` over it, which is also the only thing that parses it, and running the emitted schema under a real zod against the runtime's own payload. Both were written to skip when node was absent, which in a Python repo meant they skipped in CI and on every developer machine, so the emitter's whole content contract was guarded by nothing. This target installs a pinned prettier and zod into the gitignored `.ts-toolchain/` and runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which a missing binary is a failure instead of a skip; the new `Tests (ts emission gates)` CI job runs the same target behind a node step and blocks through the `Tests (all)` aggregate. An ordinary run on a machine with no node still skips, and now says which command would provision the toolchain. Moving the pinned prettier version is an emitter change rather than a dependency bump: the emitter models that formatter's exact break, quote and object-literal behaviour, so the gate is expected to red and the emitter to be taught what moved. See [TypeScript Emission Gates](contribute/typescript-emission-gates.md).+- **`.worktreeinclude`**: the gitignored files a fresh worktree of this repo needs — `.env`, the three `.pipelex/*.toml` overrides and `.pipelex-dev/test_profiles_override.toml` — are now declared in a tracked file at the repo root instead of living in one contributor's shell script. Claude Code reads it when it creates a worktree with git, and the workspace's `wt` tool reads it for the durable ones, so a fresh worktree of `pipelex` arrives configured either way. The file holds only the names of untracked files this repo's `.gitignore` already discloses, never their contents; it was previously gitignored here, which made the mechanism personal and untracked before anyone had used it.- **`pipelex-dev generate-projection-corpus`**: The generator of the shared fixture corpus that pins the two client-side inputs-template projections — the TypeScript one in `mthds` and its Python twin — against each other. Each client SDK now renders a pipe's fill-in template from the input-form descriptor it already has instead of asking a server for one, so the two renderings have to agree exactly, TOML `# concept:` comment lines included. The command pairs each pipe's descriptor with the expected template in both shapes (compact and explicit) and both formats (JSON and TOML), and records where that expectation deliberately differs from this engine's own inputs-template renderer: the expectation is authored from a reference projection that walks the descriptor, where the engine reflects the runtime content classes. Each class of difference is declared rather than discovered — an undeclared one fails the run, and so does a declared one that no longer occurs, so an engine fix retires its entry deliberately. A new corpus bundle covers what the existing probe bundles did not: a text field merely named `url` beside a real file position, optional file fields nested inside a structure, and both a fixed `[N]` and a variable `[]` slot over a structured concept. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **The projection corpus round-trips every template it pins through the input shaper**: `pipelex-dev generate-projection-corpus` now hands each projected template straight back to the runtime — both shapes, assembled exactly as an entry-pipe run assembles a caller's inputs — because a fill-in template exists to be filled in and run, and nothing checked that before. Twice the corpus pinned slots the runtime rejects outright and a human review round caught it rather than the capture; the second time the divergence gate absorbed the broken sites into a declared class and exited zero, since "differs from the engine" and "the engine refuses this value" are different questions. The verdict follows the same declared-never-discovered discipline as the divergence record, through an `EXPECTED_UNSHAPEABLE` registry mapping a pipe and shape to the item tracking the gap: an undeclared refusal fails the command naming the pipe, shape and error, a declared entry whose template has started shaping fails it too so a fix retires its declaration deliberately, and a declared one is stated in the manifest as an `unshapeable` entry carrying the contract-stable error class and its ledger item — so a known-open gap is recorded rather than blocking the capture. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).@@ -20,6 +22,8 @@### Fixed+- **A dict-default key carrying a double quote made the generated `types.ts` unstable under prettier**: an object-literal key that is not a plain identifier was quoted with `json.dumps`, so a key like `marked "urgent"` — reachable from `default_value = { 'marked "urgent"' = 3 }`, ordinary TOML on a `type = "dict"` field — came out double-quoted with escapes and prettier rewrote it to the escape-free `'marked "urgent"'` on the consumer's first format run, breaking the stamp. Keys now go through the same fewer-escapes quote rule as every other emitted literal, which the value side already used. This was found and deliberately deferred during the ts-zod optionality work, on the grounds that a real gate over the emission would catch its whole family at once rather than one more hand-written assertion; the newly mandatory prettier gate reddened on it immediately.+- **The ts-zod projection could not parse the engine's own wire payload** (breaking for generated TypeScript — regenerate): a non-required concept field was projected as `.optional()`, which means `T | undefined` in Zod and rejects an explicit `null`. The runtime serializes an unset optional field as exactly that — the generated runtime class annotates every non-required field `X | None` and the transport dump keeps nulls on purpose (no `exclude_none`, spelled out at the composer's dump sites) — so `Schema.parse` failed on a successful run's output with one issue per nulled field. The wire genuinely carries both spellings of "unset", a key a partial payload omitted and a key the runtime nulled, and the projection now describes both: `.nullish()` for a non-required field, and `.nullable().default(…)` where it carries a default, since a producer may null a defaulted field explicitly. There is no `.transform()` folding `null` into `undefined` — the binder uses one schema for both `parse` and `serialize`, so a transform would desynchronize the pair. Parsed optional fields therefore type as `T | null | undefined` instead of `T | undefined` (`??` covers both), and a recursive concept's explicit `export type` carries the same widening, because it is checked against the schema's inferred output. The two Python targets already accepted both spellings; this is a parity fix. Because `.nullable()` costs width on every defaulted field, the emitter's line-breaking now models prettier's real rule — a member chain of two or more calls breaks entirely, whatever the expression — rather than treating `z.enum([…])` as the only shape that can overflow; a defaulted `z.string()` overflows on nothing but a long field name and default literal. Prettier then re-measures each call on its new line and leaves flat any that now fits, so an ordinary three-choice enum carrying a default — which reaches the break on its `.nullable()` width alone — keeps its members on one line rather than being exploded into a shape the formatter folds straight back. See [Codegen Projections](under-the-hood/codegen-projections.md).- **A string carrying a double quote made every generated artifact unstable under its formatter**: choices and string defaults were always emitted double-quoted with escapes (`"marked \"urgent\""`), but ruff and prettier apply the same normalization — double quotes by default, single where that strictly reduces the escape count — so both rewrote the literal to `'marked "urgent"'` on a consumer's first format run, at any line width, and `pipelex codegen check` then reported an untouched file as hand-edited. All three targets now emit the quote style their formatter keeps, verified shape by shape against ruff and prettier including the tied and backslash-adjacent cases.- **A choice containing a comma or a bracket emitted generated code that does not parse**: an exploded choice list was split on every comma, so an ordinary authored choice like `"blocked, awaiting the owner"` became two unterminated string literals — in the TypeScript target and in both Python targets alike, since each split its own exploded form the same naive way. Every split that computes an emitted line break now walks the string literals, in both emitters and in both quote styles, the single-quoted spelling included: a choice carrying a `"` is spelled `'…'` because that is the style prettier keeps, so a walker watching only `"` cut it at its own comma. The same applies to the TypeScript member-chain split, which located a break by counting brackets and counted the ones *inside* a literal too — a choice is prose whose brackets need not balance (`a) strongly agree` is an ordinary answer option), and an unmatched closer walked the depth to zero mid-string and cut the chain through the middle of it. The TypeScript half is the one nothing was catching: every broken form is a run of *short* lines, so the print-width guard is blind to them and the only test that parses the emitted TypeScript skips wherever there is no node toolchain. An always-on invariant now asserts that no emitted line ends inside an unterminated string literal, which needs no toolchain and covers the whole class.diff --git a/CLAUDE.md b/CLAUDE.mdindex 9adab9c88..668981253 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -60,6 +60,18 @@For the full debugging methodology — clean-state protocol, when to bail to the user, how to grep failures by error class name, when xdist failures are flakes vs real bugs — see [`docs/agents/debugging-hanging-pytest-runs.md`](docs/agents/debugging-hanging-pytest-runs.md).+#### Changing a codegen emitter: `make test-ts-gates`++ ⚠ **`make agent-test` does not cover the TypeScript emission.** The two tests that read the emitted TypeScript *as TypeScript* — `prettier --check` over it, and running the emitted schema under a real zod — need a node toolchain, so in an ordinary run they skip and the suite still reports green. Everything else about the ts-zod target is measured structurally (line width, trailing whitespace, blank-line runs, unterminated literals), which is blind to a wrong quote style or a member chain broken where prettier would not break it.++ So after touching anything under `pipelex/codegen/emitters/`, run:++ ```bash+ make test-ts-gates # alias: make ttg+ ```++ It provisions a pinned prettier and zod into the gitignored `.ts-toolchain/` (needs npm and node >= 22.6), then runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which those two gates **fail** instead of skipping. CI runs the same target as the `Tests (ts emission gates)` job, so skipping it locally means finding out on the pull request. Moving the pinned prettier version is an emitter change rather than a dependency bump — the emitter models that formatter's exact behaviour. Full rationale in [`docs/contribute/typescript-emission-gates.md`](docs/contribute/typescript-emission-gates.md).+### Running Tests with Prints> **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.diff --git a/Makefile b/Makefileindex 303008fab..4a9d42b13 100644--- a/Makefile+++ b/Makefile@@ -26,6 +26,15 @@ VENV_PIPELEX_DEV := "$(VIRTUAL_ENV)/bin/pipelex-dev"SKELETON_DIR := "$(HOME)/.pipelex-skeleton/"HEARTBEAT_INTERVAL ?= 20+# The node toolchain the TypeScript emission gates run against. Both packages are pinned exactly and+# both have zero dependencies, so `npm install` here is reproducible without a lockfile. The prettier+# pin is the contract: `pipelex/codegen/emitters/ts_zod.py` emits the bytes *this* prettier leaves+# alone, so moving it is an emitter change, not a dependency bump — expect the gate to red and the+# emitter to need teaching. The directory is gitignored and provisioned on demand.+TS_TOOLCHAIN_DIR := $(CURDIR)/.ts-toolchain+TS_TOOLCHAIN_PRETTIER_VERSION ?= 3.9.6+TS_TOOLCHAIN_ZOD_VERSION ?= 4.5.4+UV_MIN_VERSION = $(shell grep -m1 'required-version' pyproject.toml | sed -E 's/.*= *"([^<>=, ]+).*/\1/')USUAL_PYTEST_MARKERS := "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api"@@ -146,6 +155,9 @@ make test-xdist - Run unit tests with xdist (no inference)make agent-test - Run unit tests, silent on success, output on failure (for AI agents)make agent-test-debug - Debug variant: cleanup + outer timeout + live log; use when agent-test hangs or fails opaquelymake atd - Shorthand -> agent-test-debug+make ts-toolchain - Install the pinned prettier + zod the TypeScript emission gates need+make test-ts-gates - Run the codegen tests with that toolchain, where the node gates may not skip+make ttg - Shorthand -> test-ts-gatesmake t - Shorthand -> test-xdistmake test-quiet - Run unit tests without prints (no inference)make tq - Shorthand -> test-quiet@@ -230,6 +242,7 @@ export HELPgenerate-error-identity generate-error-identity-quiet gei \update-gateway-models update-gateway-models-quiet ugm check-gateway-models cgm up \test-count check-test-badge \+ ts-toolchain test-ts-gates ttg \serve-graph serve-graph-bg stop-graph-server view-graph sg vg \docs-deploy-root@@ -557,6 +570,7 @@ cleanderived:rm -f tests/integration/pipelex/fixtures/_generated_model_sets.py && \rm -f .pipelex-dev/model_availability.json && \rm -rf derived/ && \+ rm -rf .ts-toolchain/ && \echo "Cleaned up derived files and directories";cleanenv:@@ -624,6 +638,37 @@ gha-tests: env@echo "• Running unit tests for github actions (excluding inference and gha_disabled)"$(VENV_PYTEST) -n auto --dist=worksteal $(if $(SPLITS),--splits $(SPLITS) --group $(GROUP)) --max-worker-restart=2 --timeout=180 --timeout-method=thread --tb=line -p no:cacheprovider --no-header -m $(GHA_PYTEST_MARKERS) || [ $$? = 5 ]+# --------------------------------------------------------------------------------------+# The TypeScript emission gates. These are the two tests that need node, and they are the+# only ones that read the emitted TypeScript as TypeScript rather than as lines of text:+# `prettier --check` parses it and holds the byte-for-byte formatting the codegen stamp+# depends on, and the wire round-trip executes the emitted schema under a real zod. Both+# were written to skip when the toolchain is absent, which on a Python repo meant always+# — so three content defects reached review with the suite green. This target provisions+# the toolchain and sets PIPELEX_REQUIRE_TS_GATES, under which a missing binary is a+# failure instead of a skip. CI runs this same target, so the gates cannot silently lapse.+# --------------------------------------------------------------------------------------+ts-toolchain:+ $(call PRINT_TITLE,"Provisioning the pinned node toolchain for the TypeScript emission gates")+ @command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 || { \+ echo "The TypeScript emission gates need node >= 22.6 and npm on PATH — install them and retry."; \+ exit 1; \+ }+ @mkdir -p "$(TS_TOOLCHAIN_DIR)"+ @npm install --silent --no-audit --no-fund --prefix "$(TS_TOOLCHAIN_DIR)" \+ prettier@$(TS_TOOLCHAIN_PRETTIER_VERSION) zod@$(TS_TOOLCHAIN_ZOD_VERSION)+ @echo "• prettier $$("$(TS_TOOLCHAIN_DIR)/node_modules/.bin/prettier" --version), zod $(TS_TOOLCHAIN_ZOD_VERSION), node $$(node --version)"++test-ts-gates: env ts-toolchain+ $(call PRINT_TITLE,"Running the TypeScript emission gates against the pinned node toolchain")+ @PATH="$(TS_TOOLCHAIN_DIR)/node_modules/.bin:$$PATH" \+ PIPELEX_REQUIRE_TS_GATES=1 \+ PIPELEX_ZOD_PACKAGE="$(TS_TOOLCHAIN_DIR)/node_modules/zod" \+ $(VENV_PYTEST) tests/unit/pipelex/codegen --no-header -p no:cacheprovider -q --timeout=180 --timeout-method=thread++ttg: test-ts-gates+ @echo "> done: ttg = test-ts-gates"+run-all-tests: env$(call PRINT_TITLE,"Running all unit tests")@echo "• Regenerating test model fixtures"diff --git a/docs/contribute/typescript-emission-gates.md b/docs/contribute/typescript-emission-gates.mdnew file mode 100644index 000000000..a46e26e86--- /dev/null+++ b/docs/contribute/typescript-emission-gates.md@@ -0,0 +1,44 @@+# TypeScript Emission Gates++The `ts-zod` target promises something stronger than "the generated code compiles": it promises the bytes are already what Prettier would write. A codegen stamp is a raw SHA-256 over the body, so a consumer's first `prettier --write` over a generated tree that is *nearly* right rewrites it, and `pipelex codegen check` then reports an untouched file as **hand-edited** — accusing the user of the one thing they did not do. That contract is stated for consumers in [Codegen Projections](../under-the-hood/codegen-projections.md#typescript-assumes-prettiers-defaults); this page is how we hold ourselves to it.++## Why the always-on tests are not enough++`tests/unit/pipelex/codegen/test_emitted_artifacts_are_lint_clean.py` carries a set of TypeScript invariants that need no toolchain at all: no collapsible blank-line run, no line past the print width, no trailing whitespace, and no line ending inside an unterminated string literal. They are cheap, they run everywhere, and they are all **structural** — they measure the shape of the emitted lines without ever reading them as TypeScript.++That leaves a whole family of defect invisible. A member chain broken where Prettier would have kept it flat, a string literal in the quote style Prettier rewrites, an object literal spelled as JSON — each of those is a run of short, well-formed, whitespace-clean lines. Three such defects reached pull-request review, and each was caught afterwards only because somebody read the emission by hand and then wrote a byte assertion for that one shape. Hand-written assertions do not generalize to the next shape.++## The two gates that read the emission++Two tests do more than measure lines, and both need node:++| Test | What it proves |+|---|---|+| `test_emitted_ts_is_prettier_clean` | `prettier --check` over the emitted `types.ts` and `binder.ts`. It parses the emission, so it is also the syntax gate, and it holds the byte-for-byte formatting the stamp depends on. |+| `test_the_emitted_schema_parses_the_runtime_payload` | The emitted schema, under a real zod, against the JSON the runtime actually puts on the wire. It is the only layer that *executes* the projection. |++Both were written to `pytest.skip` when the toolchain was absent — which, in a Python repo whose CI installs no node, meant they skipped in CI and on every developer machine. The gates existed and guarded nothing.++## `make test-ts-gates`++The fix is not another assertion, it is making the skip impossible where it matters:++```bash+make test-ts-gates # alias: make ttg+```++It provisions a pinned toolchain into the gitignored `.ts-toolchain/` (`make ts-toolchain` on its own does just that step), puts `prettier` on `PATH`, points `PIPELEX_ZOD_PACKAGE` at the installed `zod`, and runs the whole `tests/unit/pipelex/codegen` suite with **`PIPELEX_REQUIRE_TS_GATES=1`**. Under that flag `tests/helpers/ts_toolchain.py` turns a missing binary into a test *failure* instead of a skip, so the gates cannot lapse back into silence. The `Tests (ts emission gates)` job in `.github/workflows/tests-check.yml` runs this exact target behind `actions/setup-node`, and the `Tests (all)` aggregate requires it.++Without the flag — an ordinary `make agent-test` on a machine with no node — the two gates still skip, and say which command would provision them. The structural invariants hold the line there.++## The pins, and why moving one is an emitter change++`TS_TOOLCHAIN_PRETTIER_VERSION` and `TS_TOOLCHAIN_ZOD_VERSION` in the `Makefile` are exact. Both packages have zero dependencies, so `npm install` is reproducible without a lockfile.++The Prettier pin is not a routine dependency bump. `pipelex/codegen/emitters/ts_zod.py` models that formatter's behaviour directly — its member-chain break rule, its re-measurement of each call at the new indent, its quote-style rule, its object-literal brace padding and key unquoting. Moving the pin is a statement that the emitter now targets a different formatter, so expect the gate to red and expect to teach the emitter what changed. That is the gate working, not the gate misfiring.++Node itself needs **>= 22.6**, for `--experimental-strip-types`: it is what lets the round-trip driver run the emitted `.ts` with no build step.++## What is still not gated++`tsc --strict` over the emission is not run. It would catch a class the two gates above miss — a declared type that disagrees with the schema's inferred output on the recursive-concept path, where `z.ZodType<Name>` stops typechecking. Adding it is worthwhile and is deliberately not done here, because the recursive declared-type path has a known open defect of its own (its line overflows the print width, which the current width guard cannot be pointed at without reddening shapes Prettier already tolerates). A `tsc` gate belongs with the fix for that path, not before it.diff --git a/mkdocs.yml b/mkdocs.ymlindex e0652d087..865411eef 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -350,6 +350,7 @@ plugins:- contribute/mthds-test-corpus.md: "MTHDS Test Corpus"- contribute/trace-input-semantics.md: "Tracing Input Semantics"- contribute/generate-projection-corpus.md: "Projection Fixture Corpus"+ - contribute/typescript-emission-gates.md: "TypeScript Emission Gates"- migration-ledger.md: "Migration Ledger"- changelog.md: "Changelog"@@ -603,6 +604,7 @@ nav:- MTHDS Test Corpus: contribute/mthds-test-corpus.md- Tracing Input Semantics: contribute/trace-input-semantics.md- Projection Fixture Corpus: contribute/generate-projection-corpus.md+ - TypeScript Emission Gates: contribute/typescript-emission-gates.md- Migration Ledger: migration-ledger.md- Code of Conduct: CODE_OF_CONDUCT.md- License: license.mddiff --git a/pipelex/codegen/emitters/ts_zod.py b/pipelex/codegen/emitters/ts_zod.pyindex 0aeb8d600..86eb348df 100644--- a/pipelex/codegen/emitters/ts_zod.py+++ b/pipelex/codegen/emitters/ts_zod.py@@ -331,12 +331,17 @@ def _ts_literal(value: Any) -> str:def _ts_object_key(key: Any) -> str:"""An object-literal key, quoted only where prettier keeps the quotes (a non-identifier key).+ A quoted key goes through `_ts_string` like any other literal, not through `json.dumps`: prettier+ applies the same fewer-escapes quote rule to a key as to a value, so a key carrying a `"` — legal TOML+ on a `type = "dict"` field, `default_value = { 'marked "urgent"' = 3 }` — came out double-quoted with+ escapes and was rewritten to `'marked "urgent"'` on the consumer's first format run.+A non-string key is stringified first, exactly as `json.dumps` used to coerce one — `default_value` istyped `Any`, so nothing but authoring convention keeps a non-string out, and a crash here would be aworse answer than the spelling the emitter has always produced."""text = key if isinstance(key, str) else json.dumps(key)- return text if _TS_IDENTIFIER.match(text) else json.dumps(text)+ return text if _TS_IDENTIFIER.match(text) else _ts_string(text)def _concept_type_expr(diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.mdindex 938844dba..3408512af 100644--- a/pipelex/kit/agent_rules/commands.md+++ b/pipelex/kit/agent_rules/commands.md@@ -58,6 +58,18 @@For the full debugging methodology — clean-state protocol, when to bail to the user, how to grep failures by error class name, when xdist failures are flakes vs real bugs — see [`docs/agents/debugging-hanging-pytest-runs.md`](docs/agents/debugging-hanging-pytest-runs.md).+### Changing a codegen emitter: `make test-ts-gates`++ ⚠ **`make agent-test` does not cover the TypeScript emission.** The two tests that read the emitted TypeScript *as TypeScript* — `prettier --check` over it, and running the emitted schema under a real zod — need a node toolchain, so in an ordinary run they skip and the suite still reports green. Everything else about the ts-zod target is measured structurally (line width, trailing whitespace, blank-line runs, unterminated literals), which is blind to a wrong quote style or a member chain broken where prettier would not break it.++ So after touching anything under `pipelex/codegen/emitters/`, run:++ ```bash+ make test-ts-gates # alias: make ttg+ ```++ It provisions a pinned prettier and zod into the gitignored `.ts-toolchain/` (needs npm and node >= 22.6), then runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which those two gates **fail** instead of skipping. CI runs the same target as the `Tests (ts emission gates)` job, so skipping it locally means finding out on the pull request. Moving the pinned prettier version is an emitter change rather than a dependency bump — the emitter models that formatter's exact behaviour. Full rationale in [`docs/contribute/typescript-emission-gates.md`](docs/contribute/typescript-emission-gates.md).+## Running Tests with Prints> **LOCAL ONLY**: The commands below are meant for a human developer running on their local machine. If you are an AI agent (Claude Code, Cursor, Codex, or any other agent running in the cloud or in a sandboxed environment), **do NOT use these commands**. Use `make agent-test` instead.diff --git a/tests/helpers/test_ts_toolchain.py b/tests/helpers/test_ts_toolchain.pynew file mode 100644index 000000000..bffe10ee5--- /dev/null+++ b/tests/helpers/test_ts_toolchain.py@@ -0,0 +1,60 @@+"""Every `ts_toolchain` resolver must hand back an absolute path.++The callers use what they are given from somewhere else: the wire round-trip launches node with+`cwd=tmp_path`, and it symlinks the zod package into a `node_modules` under that same tmp directory. A+relative path survives the resolver's own checks — which run from the repository root — and then means+something different at the point of use. Both failure modes were reproduced before these tests existed:+`shutil.which("node")` under a relative `PATH` entry returns `bin/node` and `subprocess.run(cwd=…)` raises+`FileNotFoundError`, while a relative `PIPELEX_ZOD_PACKAGE` passes its `package.json` check and then+produces a symlink read relative to the *link's* parent, i.e. a dangling one, which surfaces as node+reporting that it cannot find the `zod` module.++Nothing here needs a real node toolchain — the executables are stubs — so these run in the ordinary CI+shards rather than only under `make test-ts-gates`.+"""++import stat+from pathlib import Path++import pytest++from tests.helpers.ts_toolchain import resolve_node, resolve_prettier, resolve_zod_package+++def _stub_executable(*, directory: Path, name: str, prints: str) -> Path:+ """A stand-in binary on PATH, so the contract can be tested without a node toolchain."""+ directory.mkdir(parents=True, exist_ok=True)+ executable = directory / name+ executable.write_text(f"#!/bin/sh\necho '{prints}'\n", encoding="utf-8")+ executable.chmod(executable.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)+ return executable+++class TestTsToolchainResolversReturnAbsolutePaths:+ def test_resolve_prettier_absolutizes_a_relative_path_entry(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):+ _stub_executable(directory=tmp_path / "bin", name="prettier", prints="3.9.6")+ monkeypatch.chdir(tmp_path)+ monkeypatch.setenv("PATH", "bin")++ assert Path(resolve_prettier()).is_absolute()++ def test_resolve_node_absolutizes_a_relative_path_entry(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):+ _stub_executable(directory=tmp_path / "bin", name="node", prints="v24.17.0")+ monkeypatch.chdir(tmp_path)+ monkeypatch.setenv("PATH", "bin")++ # The version gate has to clear on the stub's answer before the path contract can be read at all.+ assert Path(resolve_node()).is_absolute()++ def test_resolve_zod_package_absolutizes_a_relative_env_value(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):+ package = tmp_path / "vendor" / "zod"+ package.mkdir(parents=True)+ (package / "package.json").write_text("{}", encoding="utf-8")+ monkeypatch.chdir(tmp_path)+ monkeypatch.setenv("PIPELEX_ZOD_PACKAGE", "vendor/zod")++ resolved = resolve_zod_package()++ assert resolved.is_absolute()+ # The point of absolutizing: the path still names the package once it is read from elsewhere.+ assert (resolved / "package.json").is_file()diff --git a/tests/helpers/ts_toolchain.py b/tests/helpers/ts_toolchain.pynew file mode 100644index 000000000..d7de6f251--- /dev/null+++ b/tests/helpers/ts_toolchain.py@@ -0,0 +1,111 @@+"""Resolving the node toolchain the TypeScript emission gates need — and refusing to skip when a run demands it.++The ts-zod emitter is calibrated against a *specific* formatter: it emits the bytes prettier would leave+alone, so that a consumer's own format run cannot change them and make `pipelex codegen check` report an+untouched artifact as hand-edited. The gate on that calibration is `prettier --check` over the emission,+and the gate on the schema's meaning is running it under a real zod. Both need node, which a Python repo's+CI does not have by default — so both were written to `pytest.skip`, and both skipped everywhere. Three+content defects reached review through that gap, each caught afterwards by a hand-written byte assertion.++The fix is not another assertion, it is making the skip impossible where it matters. `make test-ts-gates`+provisions a pinned prettier and zod, puts them where these resolvers look, and sets+`PIPELEX_REQUIRE_TS_GATES=1`; under that flag an absent toolchain is a **failure**, not a skip. CI runs+that same target, so the gates are mandatory there and stay opportunistic on a developer's machine.++**Every resolver returns an absolute path.** Its callers use the result from somewhere else — the wire+round-trip launches node with `cwd=tmp_path` and symlinks the zod package into a `node_modules` under that+same directory — so a relative path clears the checks here, which run from the repository root, and then+names something different at the point of use. `shutil.which` returns whatever the `PATH` entry was, and an+environment variable holds whatever a human typed, so neither source can be trusted to be absolute.+"""++import os+import shutil+import subprocess # ruff: ignore[suspicious-subprocess-import]+from pathlib import Path+from typing import NoReturn++import pytest++REQUIRE_TS_GATES_ENV = "PIPELEX_REQUIRE_TS_GATES"+"""Set by `make test-ts-gates` (and therefore by CI): a missing toolchain fails instead of skipping."""++ZOD_PACKAGE_ENV = "PIPELEX_ZOD_PACKAGE"+"""Path to the `zod` package directory to link against, when it is not a global npm install."""++NODE_TYPE_STRIPPING_MINIMUM = (22, 6)+"""`--experimental-strip-types` landed in node 22.6, which is what lets node run the emitted `.ts` directly."""++_FALSE_SPELLINGS = {"", "0", "false", "no"}+++def ts_gates_are_required() -> bool:+ """Whether this run declared the node toolchain mandatory rather than opportunistic."""+ return os.environ.get(REQUIRE_TS_GATES_ENV, "").strip().lower() not in _FALSE_SPELLINGS+++def _unavailable(what: str) -> NoReturn:+ """Skip — unless the run declared the toolchain mandatory, in which case its absence is the failure."""+ if ts_gates_are_required():+ pytest.fail(f"{what}, and {REQUIRE_TS_GATES_ENV} is set, so this gate may not skip. Provision it with `make test-ts-gates`.")+ pytest.skip(f"{what} (run `make test-ts-gates` to provision it)")+++def _absolute_executable(found: str) -> str:+ """An executable path an absolute one, with its symlinks left alone.++ `Path.resolve()` is wrong here: a version manager (volta, asdf, nvm) puts a *shim* on PATH, and some+ shims dispatch on the path they were invoked by, so resolving one to its target can change what runs.+ Only the relative-`PATH`-entry case needs fixing, and `absolute()` is exactly that much.+ """+ return str(Path(found).absolute())+++def resolve_prettier() -> str:+ """The `prettier` binary the formatting gate runs, from PATH, absolute."""+ prettier = shutil.which("prettier")+ if prettier is None:+ _unavailable("prettier is not on PATH")+ return _absolute_executable(prettier)+++def resolve_node() -> str:+ """The `node` binary, when it is present and new enough to strip types off the emitted `.ts`."""+ node = shutil.which("node")+ if node is None:+ _unavailable("node is not on PATH")+ reported = subprocess.run([node, "--version"], capture_output=True, text=True, check=False) # ruff: ignore[subprocess-without-shell-equals-true]+ if reported.returncode != 0:+ _unavailable(f"`node --version` failed: {reported.stderr.strip()}")+ parts = reported.stdout.strip().lstrip("v").split(".")+ version = tuple(int(part) for part in parts[:2] if part.isdigit())+ if len(version) != 2 or version < NODE_TYPE_STRIPPING_MINIMUM:+ minimum = ".".join(str(part) for part in NODE_TYPE_STRIPPING_MINIMUM)+ _unavailable(f"node {reported.stdout.strip()} cannot strip types (needs >= {minimum})")+ return _absolute_executable(node)+++def resolve_zod_package() -> Path:+ """The `zod` package directory to symlink into a driver's `node_modules`.++ Two sources, in order: the path `make test-ts-gates` provisions and names in the environment, then a+ global npm install — which is what a developer who ran `npm install -g zod` already has.+ """+ provisioned = os.environ.get(ZOD_PACKAGE_ENV, "").strip()+ if provisioned:+ # Fully resolved rather than merely absolute: this becomes a symlink *target*, and a relative one+ # would be read from the link's own parent — a dangling link reported as a missing `zod` module.+ package = Path(provisioned).resolve()+ if not (package / "package.json").is_file():+ _unavailable(f"{ZOD_PACKAGE_ENV} points at {package}, which holds no package.json")+ return package+ npm = shutil.which("npm")+ if npm is None:+ _unavailable("npm is not on PATH, so there is no global zod to find")+ reported = subprocess.run([npm, "root", "-g"], capture_output=True, text=True, check=False) # ruff: ignore[subprocess-without-shell-equals-true]+ if reported.returncode != 0:+ _unavailable(f"`npm root -g` failed: {reported.stderr.strip()}")+ package = (Path(reported.stdout.strip()) / "zod").resolve()+ if not (package / "package.json").is_file():+ _unavailable("no globally installed zod to link against")+ return packagediff --git a/tests/unit/pipelex/codegen/conftest.py b/tests/unit/pipelex/codegen/conftest.pyindex bb9bbd66c..1b482443f 100644--- a/tests/unit/pipelex/codegen/conftest.py+++ b/tests/unit/pipelex/codegen/conftest.py@@ -237,15 +237,16 @@ def every_type_kind_crate() -> LibraryCrate:"counts": ConceptStructureBlueprint(description="Counts", type=ConceptStructureBlueprintFieldType.DICT, key_type="text", value_type="integer", required=True),- # A dict-valued default, carrying both key spellings: prettier unquotes a plain- # identifier key and keeps the quotes on one that is not, so the emitted literal has to- # make that distinction per key or a consumer's formatter rewrites the artifact.+ # A dict-valued default, carrying all three key spellings: prettier unquotes a plain+ # identifier key, keeps the quotes on one that is not, and picks the quote style that+ # needs fewer escapes on a key carrying a `"` — so the emitted literal has to make+ # both distinctions per key or a consumer's formatter rewrites the artifact."quotas": ConceptStructureBlueprint(description="Quotas",type=ConceptStructureBlueprintFieldType.DICT,key_type="text",value_type="integer",- default_value={"per-reviewer": 3, "total": 12},+ default_value={"per-reviewer": 3, "total": 12, 'marked "urgent"': 1},),# ANY — only reachable nested, from genuine source imprecision. An untyped list also# emits the trailing `# imprecise:` comment, so that shape gets linted too.diff --git a/tests/unit/pipelex/codegen/test_emitted_artifacts_are_lint_clean.py b/tests/unit/pipelex/codegen/test_emitted_artifacts_are_lint_clean.pyindex 0f5679278..d4c58c771 100644--- a/tests/unit/pipelex/codegen/test_emitted_artifacts_are_lint_clean.py+++ b/tests/unit/pipelex/codegen/test_emitted_artifacts_are_lint_clean.py@@ -27,7 +27,6 @@ See `render_import_block` in `pipelex/codegen/emitters/python_common.py`."""import re-import shutilimport subprocess # ruff: ignore[suspicious-subprocess-import]import sysfrom collections.abc import Callable@@ -44,6 +43,7 @@ from pipelex.codegen.emitters.ts_zod import TS_PRINT_WIDTH, emit_ts_zodfrom pipelex.codegen.resolved_concepts import ResolvedLibrary, resolve_concepts_from_cratefrom pipelex.core.concepts.resolved_fields import ResolvedType, ResolvedTypeKindfrom pipelex.libraries.library_crate import LibraryCrate+from tests.helpers.ts_toolchain import resolve_prettier_REPO_ROOT = Path(__file__).parents[4]_PYPROJECT = _REPO_ROOT / "pyproject.toml"@@ -265,7 +265,8 @@ class TestEmittedArtifactsAreLintClean:"""Prettier collapses a run of blank lines to one under *every* config — so emitting two (thePython idiom) guarantees a reformat, and a broken stamp, for any TypeScript consumer.- This invariant needs no prettier binary, so unlike `test_emitted_ts_is_prettier_clean` it always runs.+ This invariant needs no prettier binary, so unlike `test_emitted_ts_is_prettier_clean` it runs on any+ machine, not only where the node toolchain is provisioned."""for emitted_file in emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate)):offenders = re.findall(r"\n[ \t]*\n[ \t]*\n", emitted_file.content)@@ -274,9 +275,9 @@ class TestEmittedArtifactsAreLintClean:def test_emitted_ts_lines_fit_the_print_width(self, every_type_kind_crate: LibraryCrate):"""No emitted code line may exceed prettier's print width — it would be wrapped, breaking the stamp.- This is the guard that actually holds the TypeScript line in CI, where there is no node toolchain- for `test_emitted_ts_is_prettier_clean` to use. It needs no prettier binary, and it is what turns- an unmodelled overflow (a long concept name, a long choice list) into a failing test.+ It needs no prettier binary, so it turns an unmodelled overflow (a long concept name, a long choice+ list) into a failing test on any machine — including a developer's, before the mandatory+ `test_emitted_ts_is_prettier_clean` sees it in CI.Comment lines are exempt on purpose: prettier reflows code, never the contents of a `//` line or a`/** … */` block, so a long JSDoc line is stable at any width.@@ -295,8 +296,8 @@ class TestEmittedArtifactsAreLintClean:generated `types.ts` changed the bytes and got the artifact reported as `[hand-edited]` — the exactfalse report these emitters exist to prevent.- Like the two invariants above, this needs no prettier binary, so it is what holds the line in CI- where `test_emitted_ts_is_prettier_clean` skips for want of a node toolchain.+ Like the two invariants above, this needs no prettier binary, so it reddens locally on a machine with+ no node toolchain rather than waiting for the mandatory `test_emitted_ts_is_prettier_clean` in CI."""for emitted_file in emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate)):offenders = [line for line in emitted_file.content.splitlines() if line != line.rstrip()]@@ -310,11 +311,11 @@ class TestEmittedArtifactsAreLintClean:member-chain dots — and each of those splits has to walk the string literals to avoid cutting*through* one. Cut through one and the artifact stops being TypeScript.- Nothing else catches it. The broken form is a run of *short* lines, so the print-width guard- cannot see it, and `test_emitted_ts_is_prettier_clean` — the only test that actually parses the- emission — skips wherever there is no node toolchain, which is CI and every machine here. Three- separate defects of exactly this shape reached review before this guard existed; the durable fix- is a real parse, tracked as L-260901-26da36.+ No *always-on* guard catches it: the broken form is a run of *short* lines, so the print-width guard+ cannot see it. Three separate defects of exactly this shape reached review while the only test that+ parses the emission — `test_emitted_ts_is_prettier_clean` — skipped everywhere for want of a node+ toolchain. That gate is mandatory in CI now, which is the durable fix; this one is what keeps the+ class visible on a machine that has no node at all."""for emitted_file in emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate)):for line_number, line in enumerate(emitted_file.content.splitlines(), start=1):@@ -338,12 +339,17 @@ class TestEmittedArtifactsAreLintClean:def test_emitted_ts_is_prettier_clean(self, every_type_kind_crate: LibraryCrate, tmp_path: Path):"""`prettier --check` must find nothing to change in the emitted TypeScript.- Skipped when prettier is not on PATH — this is a Python repo, so CI has no node toolchain. The- always-on structural guard above is what holds the line there.+ This is the only gate that actually *parses* the emission, so it is the one that sees a content+ defect the structural invariants above are blind to by construction — a wrong quote style, an+ object literal spelled as JSON, a member chain broken where prettier would not break it. Each of+ those reached review at least once while this test skipped everywhere.++ It is therefore **mandatory** rather than opportunistic: `make test-ts-gates` provisions a pinned+ prettier and sets `PIPELEX_REQUIRE_TS_GATES`, under which an absent binary fails here instead of+ skipping, and CI runs that target. Without the flag — an ordinary local run on a machine with no+ node toolchain — it still skips, and the structural invariants hold the line."""- prettier = shutil.which("prettier")- if prettier is None:- pytest.skip("prettier not on PATH")+ prettier = resolve_prettier()for emitted_file in emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate)):(tmp_path / emitted_file.filename).write_text(emitted_file.content, encoding="utf-8")diff --git a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py b/tests/unit/pipelex/codegen/test_ts_zod_emitter.pyindex b8cd9091d..738ed1803 100644--- a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py+++ b/tests/unit/pipelex/codegen/test_ts_zod_emitter.py@@ -124,12 +124,15 @@ class TestTsZodEmitter:"""Prettier normalizes a string literal to whichever quote needs fewer escapes, at any width.So the naive always-double spelling — double-quoted with both inner quotes escaped — is rewritten on- the consumer's first format run and the artifact is reported as hand-edited. The Python targets have- the same rule and the ruff guards catch them; nothing always-on watches the TypeScript spelling.+ the consumer's first format run and the artifact is reported as hand-edited. The rule reaches an+ object-literal *key* as well as a value: prettier quotes a non-identifier key in whichever style+ needs fewer escapes, so a dict default keyed `marked "urgent"` — legal TOML on a `type = "dict"`+ field — has to be emitted single-quoted too, next to the two spellings it is emitted beside."""content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].contentassert ' reviewer_verdict: z.enum([\'marked "urgent"\', "left unmarked"]),' in content+ assert '.default({ \'marked "urgent"\': 1, "per-reviewer": 3, total: 12 })' in contentdef test_temporal_defaults_emit_iso_wire_strings(self, temporal_defaults_crate: LibraryCrate):content = emit_ts_zod(resolve_concepts_from_crate(temporal_defaults_crate))[0].contentdiff --git a/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py b/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.pyindex dd615001b..d43cc91d2 100644--- a/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py+++ b/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py@@ -15,12 +15,12 @@ Three layers, on one shared crate:`exclude_none`, this reddens and forces the projection decision to be revisited alongside it.2. **Projection pin** — emit ts-zod for the same crate and require every non-required field to benull-tolerant. Paired with (1), the cross-language contract is encoded here even where CI has no node.-3. **Executable round-trip** — feed (1)'s JSON through the emitted schema under a real zod. Skipped unless- node and a global `zod` are both present; the always-on pins hold the line in CI.+3. **Executable round-trip** — feed (1)'s JSON through the emitted schema under a real zod. Mandatory+ wherever the node toolchain is provisioned (`make test-ts-gates`, which is what CI runs); opportunistic+ on a machine without it, where the two always-on pins hold the line."""import json-import shutilimport subprocess # ruff: ignore[suspicious-subprocess-import]from pathlib import Pathfrom typing import Any@@ -37,6 +37,7 @@ from pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.libraries.crate_normalization import normalize_cratefrom pipelex.libraries.library_crate import LibraryCratefrom pipelex.system.registries.class_registry_access import get_class_registry+from tests.helpers.ts_toolchain import resolve_node, resolve_zod_packagefrom tests.unit.pipelex.codegen.conftest import CRATE_TEST_VERSION_DOMAIN = "wire"@@ -77,9 +78,6 @@ _AUTHORED: dict[str, ConceptBlueprint] = {# Every non-required field of `Payload`, i.e. every key the runtime can put on the wire as an explicit null._NON_REQUIRED_FIELDS = ("note", "detail", "tags", "counts", "status")-_NODE_TYPE_STRIPPING_MINIMUM = (22, 6)-"""`--experimental-strip-types` landed in 22.6, which is what lets node run the emitted `.ts` directly."""-def _authored_crate() -> LibraryCrate:return LibraryCrate(@@ -88,31 +86,6 @@ def _authored_crate() -> LibraryCrate:)-def _node_executable() -> str | None:- """The node binary, when it is present and new enough to strip types off the emitted `.ts`."""- node = shutil.which("node")- if node is None:- return None- reported = subprocess.run([node, "--version"], capture_output=True, text=True, check=False) # ruff: ignore[subprocess-without-shell-equals-true]- if reported.returncode != 0:- return None- parts = reported.stdout.strip().lstrip("v").split(".")- version = tuple(int(part) for part in parts[:2] if part.isdigit())- return node if len(version) == 2 and version >= _NODE_TYPE_STRIPPING_MINIMUM else None---def _global_zod_package() -> Path | None:- """The globally installed `zod` package directory, if there is one to link against."""- npm = shutil.which("npm")- if npm is None:- return None- reported = subprocess.run([npm, "root", "-g"], capture_output=True, text=True, check=False) # ruff: ignore[subprocess-without-shell-equals-true]- if reported.returncode != 0:- return None- package = Path(reported.stdout.strip()) / "zod"- return package if (package / "package.json").is_file() else None--class TestTsZodWireAgreement:@pytest.fixturedef wire_payloads(self, load_empty_library: Any) -> list[dict[str, Any]]:@@ -170,15 +143,13 @@ class TestTsZodWireAgreement:def test_the_emitted_schema_parses_the_runtime_payload(self, wire_payloads: list[dict[str, Any]], tmp_path: Path):"""The round trip itself: a real zod, the emitted schema, the runtime's own JSON.- Skipped when the node toolchain is absent — this is a Python repo, so CI has none. The two pins- above encode the same contract without it.+ This is the only layer that executes the projection, so it is the one that would catch a schema+ that is well-formed and still wrong. `make test-ts-gates` provisions node's companions and sets+ `PIPELEX_REQUIRE_TS_GATES`, under which an absent toolchain fails here instead of skipping, and CI+ runs that target. Without the flag it still skips, and the two pins above encode the same contract."""- node = _node_executable()- if node is None:- pytest.skip("node >= 22.6 not available")- zod_package = _global_zod_package()- if zod_package is None:- pytest.skip("no globally installed zod to link against")+ node = resolve_node()+ zod_package = resolve_zod_package()content = emit_ts_zod(resolve_concepts_from_crate(normalize_crate(_authored_crate(), mthds_version=CRATE_TEST_VERSION)))[0].content(tmp_path / "types.ts").write_text(content, encoding="utf-8")diff --git a/wip/github-actions-sha-pinning.md b/wip/github-actions-sha-pinning.mdindex cc02b211e..484493596 100644--- a/wip/github-actions-sha-pinning.md+++ b/wip/github-actions-sha-pinning.md@@ -16,3 +16,9 @@ This is not a defect in the PR — it is the repo's standing convention. Existin## RecommendationDecide once, for the whole repo: either keep the current tags-for-standard-actions / SHAs-for-privileged-actions split as deliberate policy, or pin every third-party action to a reviewed SHA across all workflows in one sweep (with Dependabot or pin tooling such as `pinact` to keep the pins moving). If pinning wins, the sweep should cover all workflows in `.github/workflows/`, not just the new one.++## Raised again on PR #1184 (2026-09-02)++Greptile reported the identical finding on the new `Tests (ts emission gates)` job in `.github/workflows/tests-check.yml` — thread `PRRT_kwDOOwmMFc6eS72b`, flagging `actions/checkout@v4`, `astral-sh/setup-uv@v7` and `actions/setup-node@v4`. Deferred here unchanged, for the same reason and with one addition specific to that PR: the new job sits in the same file as the eight `matrix-test` shards, which already run `actions/checkout@v4` and `astral-sh/setup-uv@v7` unpinned on every pull request. Pinning only the new job would change nothing about what third-party code executes per PR, while making one job in the file disagree with the rest of it.++The recurrence is itself an argument for the recommendation above: the bots will raise this on every new workflow or job until the repo decides once and sweeps.diff --git a/wip/ts-emission-gate-coverage-deferrals.md b/wip/ts-emission-gate-coverage-deferrals.mdnew file mode 100644index 000000000..ad8bc7b73--- /dev/null+++ b/wip/ts-emission-gate-coverage-deferrals.md@@ -0,0 +1,17 @@+# Deferred: two coverage gaps in the TypeScript emission gates++Deferred from the pre-landing review of PR [#1184](https://github.com/Pipelex/pipelex/pull/1184) (2026-09-02). Both are defense-in-depth rather than defects: the gate that decides whether a branch merges runs, and runs correctly.++## The release gate to `main` does not run the emission gates++`.github/workflows/tests-check.yml` grew the `Tests (ts emission gates)` job, and `Tests (all)` requires it. `.github/workflows/tests-full-check.yml` — the gate on PRs targeting `main`, i.e. the release PRs — has only `matrix-test-full` and its aggregator, so the emission gates do not run there.++Left alone because a `dev -> main` release PR carries only commits that already passed the gate on their own PR into `dev`, so the second run would re-prove what the first proved. It becomes worth adding the moment anything can reach `main` without having passed through `tests-check.yml`.++## `AGENTS.md` does not carry the `make test-ts-gates` warning++The warning was added to `pipelex/kit/agent_rules/commands.md`, which `index.toml` merges into `CLAUDE.md`. `AGENTS.md` is built from a different set, headed by `codex_commands.md`, which the change did not touch — `pipelex-dev check-rules` passes, so this is the sets working as declared, not drift.++The gap that leaves: an agent working from `AGENTS.md` and editing `pipelex/codegen/emitters/` is told to verify with `make agent-test`, and is not told that `make agent-test` does not read the emitted TypeScript at all. That is the environment class the three original defects came from.++Left alone because `codex_commands.md` is deliberately the slimmer variant — it already omits the hang-debugging section and the with-prints section — and because a cloud sandbox may have no npm reach, which makes the provisioning half of the instruction useless there. The right shape is probably the warning without the provisioning command: *"`make agent-test` does not cover the TypeScript emission; a change under `pipelex/codegen/emitters/` is verified by the `Tests (ts emission gates)` CI job, not by the suite you can run here."* Worth writing the next time that file is edited for another reason.diff --git a/wip/ts-emission-gate-pin-enforcement.md b/wip/ts-emission-gate-pin-enforcement.mdnew file mode 100644index 000000000..a62269786--- /dev/null+++ b/wip/ts-emission-gate-pin-enforcement.md@@ -0,0 +1,34 @@+# Deferred: should the TypeScript emission gate enforce its own prettier pin?++Deferred from PR [#1184](https://github.com/Pipelex/pipelex/pull/1184) review round 1 (2026-09-02). Raised by cubic, running locally against `origin/dev` — it left no PR thread, so this note is its only record.++## The issue as reported++`Makefile:35` declares the toolchain pins with `?=`:++```make+TS_TOOLCHAIN_PRETTIER_VERSION ?= 3.9.6+TS_TOOLCHAIN_ZOD_VERSION ?= 4.5.4+```++Make treats an environment variable as already-defined, so `TS_TOOLCHAIN_PRETTIER_VERSION=3.0.0 make test-ts-gates` installs and gates against a formatter other than the one the emitter is calibrated to, while the mandatory gate still reports green.++## The sharper version, found while verifying it++The `?=` is not the widest door. `resolve_prettier()` in `tests/helpers/ts_toolchain.py` takes whatever `prettier` is first on `PATH` and never compares it to the pin. `make test-ts-gates` prepends the provisioned binary, so the target is safe — but running the codegen suite directly with `PIPELEX_REQUIRE_TS_GATES=1` and an ambient prettier gates the emission against an arbitrary version. The dangerous direction is a false pass: a prettier that accepts bytes the pinned one would rewrite.++## Why it deferred++- `?=` is this repo's own idiom for an overridable default (`PYTHON_VERSION ?= 3.13`, `HEARTBEAT_INTERVAL ?= 20`, `LINT_PYTHON_VERSION ?=`), and here it is the deliberate hook for probing a newer prettier before moving the pin — which is exactly the workflow the pin's documentation asks for.+- CI sets neither variable and always goes through `make test-ts-gates`, so the gate that decides whether a branch merges always runs the pin. The exposure is a developer's local run, where a false pass is caught by CI on push.+- Closing it means a third environment variable carrying the pin from the Makefile into Python plus a version-comparison branch, to guard a case the layering already handles. That is a guard on a state that cannot occur where it would matter.++## The shape of the fix, if it is ever wanted++Keep the Makefile as the single source of the pin and pass it down — `PIPELEX_PRETTIER_VERSION_PIN=$(TS_TOOLCHAIN_PRETTIER_VERSION)` beside the two variables the target already exports — then have `resolve_prettier()` compare `prettier --version` against it and refuse **only in required mode**. Duplicating the version into Python instead would create a second source of truth and is the wrong trade.++Worth revisiting if the gate ever produces a confusing result that turns out to be a version mismatch, or if a second consumer starts running these gates outside the make target.++## The same hole on the zod side++Raised in the pre-landing review of the same PR (2026-09-02). Everything above reasons about prettier, but `resolve_zod_package()` has the identical shape: with `PIPELEX_ZOD_PACKAGE` unset it falls back to `npm root -g` plus `zod` and never compares what it finds against `TS_TOOLCHAIN_ZOD_VERSION`. The deferral reasoning carries over unchanged — CI always goes through `make test-ts-gates`, which names the provisioned package explicitly — and the exposure is milder still: the round trip *executes* the schema, so a zod far enough from the pin to matter fails loudly rather than passing on bytes the pinned one would reject. If the fix above is ever taken, it should carry both pins down, not just prettier's.