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.

fix: make the ts-zod projection accept the explicit nulls the wire carries (#1177)

Louis Choquelfc9bc8891ce9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b9efa783..2fe60fa42 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,10 @@
### Fixed
+- **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.
+- **A dict-valued default made the generated `types.ts` unstable under prettier**: the default was rendered as a JSON object (`{"alpha": "first"}`), and prettier rewrites a TypeScript object literal at any line width — it pads the braces and drops the quotes from every key that is a plain identifier. One such default was therefore enough for a consumer's formatter run to change the artifact's bytes and have `pipelex codegen check` report an untouched file as hand-edited, which is precisely the drift the emitted formatting exists to prevent. Defaults now render as TypeScript literals, quoting only the keys prettier itself keeps quoted.
- **An unknown or ambiguous entry `pipe_code` is reported as the caller's mistake, not a server fault**: the two entry-shaped lookups — the ones a CLI argument and an API request field land in — raised the bare `PipeNotFoundError` / `PipeLibraryError`, which declare no `error_domain`, so `ErrorReport.http_status` fell through to 500. A caller typo in the `pipe_code` of a run request therefore came back as an internal error, logged with a traceback and looking retryable to every SDK, for a mistake only the caller could fix — and the same typo already answered 422 on the build routes, which catch those classes explicitly, so one input produced two verdicts depending on the route. Two dedicated classes now carry `ErrorDomain.INPUT` and a `CHANGE_INPUT` action: `EntryPipeNotFoundError` when the entry lookup resolves nothing, `EntryPipeAmbiguousError` when a bare code is declared in several domains. Both subclass the errors they replace, so every existing catcher still matches, and every presentation derives from the domain at once — 422 on the API, the classification the agent CLI reports, the hosted status. Both are caller-facing copy that survives STRICT disclosure, since the message names only the caller's own `pipe_code` and the qualified `pipe_ref`s of bundles they loaded themselves — which is the only thing that makes an ambiguity actionable. In-body resolution is deliberately untouched: `get_optional_pipe` / `get_required_pipe` keep raising the undomained classes, because a ref written inside a bundle is not a caller's input mistake. The one crossing case is translated rather than left to leak: an ambiguous `alias->bare_code` is detected one frame down, inside the alias-scoped search, and the entry lookup re-raises it as `EntryPipeAmbiguousError` keeping the original as its cause. The agent CLI's `validate` arms stopped hardcoding `PipeNotFoundError` as the reported `error_type` and now name the class that actually failed, which is where the domain and hint on that envelope come from.
- **A typo'd `--pipe` / `pipe_ref` slice selector is reported as the caller's mistake too**: bundle validation narrowed to one pipe (`pipelex-agent validate bundle --pipe`, its `validate method --pipe` twin, and the `pipe_ref` field the build routes forward) raised the undomained `PipeNotFoundError` when the selector named nothing in the bundle, so the same caller typo that answers 422 through the entry lookups came back as a 500 through this one — the divergence the entry-pipe classification above was meant to remove, left in place one module over. The selector is entry-shaped input by the same definition (a code a human typed at an entry point), so the miss now raises `EntryPipeNotFoundError` with its `INPUT` domain and `CHANGE_INPUT` action, keeping the raise site's own bundle-scoped wording, which names only the codes the caller supplied. It is a subclass of the class it replaces, so every existing catcher still matches; the hand-written 422 mapping the public runner API keeps for this case becomes redundant once a release carries the change.
- **A `native.JSON` input produced a fill-in template the runtime refused**: the input-form deriver grouped `native.JSON` with the three natives the standard calls structureless — `Dynamic`, `Anything` and `Composite` — so its descriptor node was `unknown`, which every inputs-template projection renders as the empty object. But `JSON` is not structureless: its pinned blueprint carries a required `json_obj`, and `JSONContent` refuses a payload without it, so the template a caller was handed for a `JSON` input could never be filled in and submitted. It now expands through the same pinned-structure arm as `Date`, `Html`, `Page`, `TextAndImages` and `SearchResult`, rendering `{"json_obj": {}}`, which the input shaper takes back. The engine's own `_pinned_structure` already drew the line in exactly this place — it returns a structure for `JSON` and `None` for the other three — so the deriver is now consistent with it, and the empty object stays the honest rendering for the natives that genuinely withhold their shape. The shared projection corpus gained a pipe covering all three of the natives it can reach at a slot position, which is where the defect had been sitting unmeasured. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).
diff --git a/docs/under-the-hood/codegen-projections.md b/docs/under-the-hood/codegen-projections.md
index 10686d03c..6d220f291 100644
--- a/docs/under-the-hood/codegen-projections.md
+++ b/docs/under-the-hood/codegen-projections.md
@@ -29,6 +29,17 @@ Wire-native keys (D10) are a deliberate correctness choice: a camelCase-keyed sc
For **`python-pydantic`**, no key mapping is ever needed either: wire names are already snake_case Python names, so parse/serialize are the native `Model.model_validate(data)` / `model.model_dump(mode="json")`.
+### Optionality: the wire carries explicit nulls
+
+A projection describes the payload the engine actually produces, and that payload spells an unset optional field as an explicit `null` — not as an absent key. The runtime class generated for a concept annotates every non-required field `X | None`, and the transport dump keeps nulls deliberately (`dump_for_transport()` is a `model_dump(serialize_as_any=True)` with no `exclude_none`, and the composer spells `exclude_none=False` at its dump sites), because the shape also feeds the Temporal data converter and the hydrator. A partial payload arriving from a caller, meanwhile, may simply omit the key. **The wire genuinely carries both spellings of "unset", so every projection must accept both.**
+
+Per target that means:
+
+- **`python-pydantic` / `python-structures`** — `X | None = Field(default=None)`. Pydantic accepts an omitted key and an explicit `null` alike, so nothing further is needed.
+- **`ts-zod`** — `.nullish()` for a non-required field (`T | null | undefined`), and `.nullable().default(…)` for a non-required field carrying a default, since a producer may null it explicitly. A bare `.optional()` would mean `T | undefined` in Zod and would **reject the engine's own output**; a bare `.default(…)` rejects the explicit null the same way. There is deliberately no `.transform()` folding `null` into `undefined`: the binder uses one schema for both `parse` and `serialize`, so a transform would make the pair asymmetric.
+
+On the TypeScript side the consequence is that a parsed optional field types as `T | null | undefined` rather than `T | undefined` — `??` covers both. For a recursive concept, where the emitter writes an explicit `export type` beside a `z.ZodType<Name>`-annotated schema, the declared type carries the same widening (`next?: Node | null`), because that annotation is checked against the schema's inferred output and stops typechecking otherwise.
+
### Refinement and native bases
A concept that refines another keeps its `refines` link when the base is **native-backed** (the refinement chain bottoms out at a native such as `Text` or `Number`), because the native is materialized into the crate and the base carries real runtime behavior; the emitter then renders inheritance (`class Summary(TextContent)` / `class Summary(Text)` / `z.lazy(() => TextSchema)`), which round-trips to the correct base class. A concept that refines an **in-crate structured** base has that base's effective structure flattened in during normalization.
@@ -131,7 +142,7 @@ Exact bytes survive wherever they are consumed programmatically rather than read
#### TypeScript assumes Prettier's defaults
-The `ts-zod` target is emitted to match Prettier's **default** configuration: 80-column print width, double quotes, semicolons. A long concept name or choice list is pre-wrapped the way Prettier would wrap it, for the same reason the Python side pre-explodes long calls.
+The `ts-zod` target is emitted to match Prettier's **default** configuration: 80-column print width, double quotes, semicolons. Anything that would overflow is pre-wrapped the way Prettier would wrap it, for the same reason the Python side pre-explodes long calls — and what overflows is not only a long concept name or choice list. The field name and the default literal are authored too, so an ordinary `z.string()` carrying a default can pass the width on its name alone; the emitter therefore breaks by Prettier's own rule, which keys on the **member chain's call count** rather than on the expression. A chain of two or more calls breaks entirely (`z` alone on the property line, one call per line), and each call is then re-measured at its new indent and left flat if it now fits; a single call has no chain to break, so its arguments explode in place. Default values are likewise emitted as TypeScript literals rather than JSON ones, because Prettier pads an object literal's braces and unquotes every key that is a plain identifier, at any width.
If your Prettier config changes `printWidth`, `singleQuote`, or `semi`, the generated files will not match it, and `prettier --write` will rewrite them. Either run codegen output through your own Prettier before stamping, or keep an exclusion for the generated path.
diff --git a/pipelex/codegen/emitters/python_common.py b/pipelex/codegen/emitters/python_common.py
index aef7506df..971fd5f71 100644
--- a/pipelex/codegen/emitters/python_common.py
+++ b/pipelex/codegen/emitters/python_common.py
@@ -51,14 +51,27 @@ def python_header(*, target: str) -> str:
def escape_py_string(value: str) -> str:
- """Escape a string for a double-quoted Python literal (handles quotes, backslashes, newlines)."""
- # repr() escapes everything correctly and returns a quoted literal; prefer double quotes when repr
- # chose single quotes (for consistency with the rest of the generated code).
+ """Escape a string as the Python literal `ruff format` would leave alone.
+
+ Double quotes by default, and single quotes only where that **strictly reduces** the escape count —
+ which is ruff's (and black's) own normalization rule, verified across the mixed and tied cases. Always
+ double-quoting was the tempting simplification and it broke the stamp: a description or choice
+ carrying a `"` came out double-quoted with both quotes escaped, which ruff rewrites to the
+ escape-free `'say "hi"'` on a consumer's very first format run — at any line width, reporting an
+ untouched artifact as hand-edited.
+
+ `repr` does the escaping of everything else — backslashes, newlines, control characters — and picks its
+ own quote by a different rule, so its choice is converted when it disagrees.
+ """
+ quote = "'" if value.count("'") < value.count('"') else '"'
escaped = repr(value)
- if escaped.startswith("'") and escaped.endswith("'") and not escaped.startswith("'''"):
- inner = escaped[1:-1].replace("\\'", "'").replace('"', '\\"')
- return f'"{inner}"'
- return escaped
+ if escaped[0] == quote:
+ return escaped
+ # Only repr-single -> double is reachable: repr picks `"` solely for a value carrying `'` and no `"`,
+ # which is exactly the shape this rule also wants double-quoted.
+ other = escaped[0]
+ inner = escaped[1:-1].replace(f"\\{other}", other).replace(quote, f"\\{quote}")
+ return f"{quote}{inner}{quote}"
def format_default_value(value: Any) -> str:
@@ -191,16 +204,34 @@ def field_line(field: ResolvedField, *, annotation: str, imports: set[str]) -> s
def _split_top_level(inner: str) -> list[str]:
- """Split `a, b[c, d], e` on its top-level commas only."""
+ """Split `a, b[c, d], e` on its top-level commas only — outside a bracket *and* outside a literal.
+
+ The literal half is not decoration: a `Literal[...]` member is authored text, and an ordinary choice
+ like `"yes, absolutely"` carries a comma. Split on it and the exploded annotation is two unterminated
+ strings — generated Python that does not parse. Both quote styles have to be walked, because
+ `escape_py_string` falls back to a single-quoted `repr` for a choice that itself contains a `"`.
+ """
members: list[str] = []
depth = 0
current = ""
+ quote: str | None = None
+ escaped = False
for char in inner:
- if char == "," and depth == 0:
+ if escaped:
+ escaped = False
+ elif quote is not None:
+ if char == "\\":
+ escaped = True
+ elif char == quote:
+ quote = None
+ elif char in {'"', "'"}:
+ quote = char
+ elif char == "," and depth == 0:
members.append(current.strip())
current = ""
continue
- depth += {"[": 1, "]": -1}.get(char, 0)
+ else:
+ depth += {"[": 1, "]": -1}.get(char, 0)
current += char
members.append(current.strip())
return members
diff --git a/pipelex/codegen/emitters/ts_zod.py b/pipelex/codegen/emitters/ts_zod.py
index a6bcbc058..0aeb8d600 100644
--- a/pipelex/codegen/emitters/ts_zod.py
+++ b/pipelex/codegen/emitters/ts_zod.py
@@ -20,7 +20,8 @@ sibling file), the TS analog of the Python subclassing story; the generated file
"""
import json
-from typing import Any
+import re
+from typing import Any, cast
from pipelex.codegen.emitters.naming import allocate_ts_type_names
from pipelex.codegen.emitters.target import EmittedFile
@@ -127,44 +128,215 @@ def _render_field(
reasons = list(dict.fromkeys(iter_imprecision_reasons(concept_field.resolved_type)))
doc = _jsdoc(concept_field.description, imprecise="; ".join(reasons) if reasons else None, indent=" ")
expr = _zod_type(concept_field.resolved_type, by_ref=by_ref, type_name_by_ref=type_name_by_ref)
- modifier = ""
- if concept_field.default_value is not None:
- modifier = f".default({_format_default_value(concept_field.default_value)})"
- elif not concept_field.required:
- modifier = ".optional()"
+ modifiers = _presence_modifiers(concept_field)
- flat = f" {key}: {expr}{modifier},"
+ flat = f" {key}: {expr}{''.join(modifiers)},"
if len(flat) <= TS_PRINT_WIDTH or "\n" in expr:
return f"{doc}{flat}"
- return f"{doc} {key}: {_break_zod_expr(expr, modifier=modifier)},"
+ return f"{doc} {key}: {_break_zod_expr(expr, modifiers=modifiers)},"
+
+
+def _presence_modifiers(concept_field: ResolvedField) -> list[str]:
+ """The zod member calls that encode a field's presence, in chain order.
+
+ Both non-required spellings are **null-tolerant**, because the runtime serializes an unset optional
+ field as an explicit `null`: the generated runtime class annotates every non-required field `X | None`
+ and `dump_for_transport()` keeps nulls on purpose (no `exclude_none`). `.optional()` means
+ `T | undefined` in zod and rejects that payload, so a schema that spelled it would fail to parse the
+ very wire the engine produces. The wire genuinely carries both spellings of "unset" — a key a partial
+ payload omitted, and a key the runtime nulled — and `.nullish()` is the honest description of that.
+
+ A defaulted field is non-required by construction (the blueprint validator refuses `required = true`
+ beside a `default_value`, E3), and a producer may set it to `None` explicitly, so `.default(...)` needs
+ `.nullable()` in front of it for the same reason.
+ """
+ if concept_field.default_value is not None:
+ return [".nullable()", f".default({_format_default_value(concept_field.default_value)})"]
+ if not concept_field.required:
+ return [".nullish()"]
+ return []
-def _break_zod_expr(expr: str, *, modifier: str) -> str:
+def _break_zod_expr(expr: str, *, modifiers: list[str]) -> str:
"""Prettier's rendering of a field expression too long to sit on one line.
- Only `z.enum([...])` can genuinely overflow — its members are authored choices with no length bound,
- while every other emitted expression is a short fixed form or a `z.lazy(() => XSchema)` whose width is
- the concept name's. Two shapes, and prettier picks between them: bare, it breaks the array in place;
- with a modifier attached it breaks the whole member chain, pulling `.enum(` onto its own line.
+ Prettier picks between two shapes by how many calls the chain carries, and the count is what decides —
+ not which expression it is. **Two or more** calls (every field carrying a presence modifier, and
+ `z.number().int()` on its own) and it breaks the whole member chain: `z` stays on the property line and
+ every call goes onto a line of its own. A **single** call has no chain to break, so prettier explodes
+ that call's arguments in place instead.
- Anything we do not model stays flat — `test_emitted_ts_lines_fit_the_print_width` is the guard that
- turns an unmodelled overflow into a failing test rather than a silently broken stamp.
+ Both unbounded widths reach this. A `z.enum([...])`'s members are authored choices with no length bound,
+ and the *field name* and *default literal* are authored too — so an ordinary `z.string()` carrying a
+ default overflows on nothing but a long name, which is why the break cannot key on the expression.
+
+ The one shape still unmodelled is a single call whose arguments must explode for a reason other than
+ enum members — a `z.lazy(() => AVeryLongConceptNameSchema)` on a required field. It stays flat, and
+ `test_emitted_ts_lines_fit_the_print_width` is the guard that turns that into a failing test rather
+ than a silently broken stamp.
+ """
+ head, *calls = _split_member_chain(expr)
+ chain = calls + modifiers
+ if len(chain) < 2:
+ # No chain to break: prettier explodes the single call's arguments, and only `z.enum` is modelled.
+ if chain and _is_enum_call(chain[0]):
+ return f"{head}{_explode_enum_call(chain[0], indent=2)}"
+ return f"{expr}{''.join(modifiers)}"
+ rendered = "".join(f"\n {_render_broken_call(call, indent=4)}" for call in chain)
+ return f"{head}{rendered}"
+
+
+def _render_broken_call(call: str, *, indent: int) -> str:
+ """One member call on its own line after the chain break, exploded only if it still overflows there.
+
+ Prettier re-measures every call once the chain is broken, and one that now fits is left flat — the
+ threshold is exact, `indent + len(call) <= TS_PRINT_WIDTH` stays on the line. Exploding unconditionally
+ is what a `z.enum` special case looks like from the other side: an ordinary three-choice enum carrying a
+ default reaches this branch on its `.nullable()` width alone, sits far inside the width at indent 4, and
+ was being exploded into a shape prettier immediately folds back — a consumer's first format run changes
+ the bytes and `pipelex codegen check` reports an untouched artifact as hand-edited. Only the enum's
+ arguments are modelled here, for the same reason as in the single-call branch.
+ """
+ if _is_enum_call(call) and indent + len(call) > TS_PRINT_WIDTH:
+ return _explode_enum_call(call, indent=indent)
+ return call
+
+
+def _split_member_chain(expr: str) -> list[str]:
+ """Split `z.record(z.string(), z.number()).int()` into its head and calls: `["z", ".record(…)", ".int()"]`.
+
+ Splits on the dots sitting at bracket depth zero **outside a string literal**, and the literal half is
+ what makes the count trustworthy. A choice is authored prose whose brackets need not balance — `a)` is
+ an ordinary answer option — so counting the brackets *inside* one walks the depth to zero mid-literal
+ and cuts the chain through the middle of a string. Both quote styles have to be walked, because
+ `_ts_string` spells a choice carrying a `"` single-quoted.
+ """
+ parts: list[str] = []
+ depth = 0
+ current = ""
+ quote: str | None = None
+ escaped = False
+ for char in expr:
+ if escaped:
+ escaped = False
+ elif quote is not None:
+ if char == "\\":
+ escaped = True
+ elif char == quote:
+ quote = None
+ elif char in {'"', "'"}:
+ quote = char
+ else:
+ if char == "." and depth == 0 and current:
+ parts.append(current)
+ current = ""
+ depth += {"(": 1, "[": 1, "{": 1, ")": -1, "]": -1, "}": -1}.get(char, 0)
+ current += char
+ parts.append(current)
+ return parts
+
+
+def _is_enum_call(call: str) -> bool:
+ """Whether a member call is the one shape whose arguments can overflow on their own contents."""
+ return call.startswith(".enum([") and call.endswith("])")
+
+
+def _explode_enum_call(call: str, *, indent: int) -> str:
+ """Render `.enum([...])` with one choice per line, for a call sitting at column `indent`.
+
+ The split has to walk the string literals rather than `str.split(",")`: a choice is authored text, and
+ an ordinary one like `"yes, absolutely"` carries a comma. Split naively it became two unterminated
+ literals — generated TypeScript that does not parse, on any crate whose choice list overflows. It walks
+ both quote styles, since `_ts_string` spells a choice carrying a `"` single-quoted.
"""
- prefix, _, members_text = expr.partition("([")
- if prefix != "z.enum" or not members_text.endswith("])"):
- return f"{expr}{modifier}"
- members = [member.strip() for member in members_text[:-2].split(",")]
+ rendered = "".join(f"{' ' * (indent + 2)}{member},\n" for member in _split_enum_members(call[len(".enum([") : -2]))
+ return f".enum([\n{rendered}{' ' * indent}])"
- if not modifier:
- rendered = "".join(f" {member},\n" for member in members)
- return f"z.enum([\n{rendered} ])"
- rendered = "".join(f" {member},\n" for member in members)
- return f"z\n .enum([\n{rendered} ])\n {modifier}"
+
+def _split_enum_members(members_text: str) -> list[str]:
+ """Split `"a", 'b, c'` on its separating commas only — the ones outside a string literal.
+
+ Both quote styles have to be walked, not just the double one: `_ts_string` spells a choice carrying a
+ `"` single-quoted, since that is the style prettier keeps. Track only `"` and an ordinary authored
+ choice like `'say "hi", then continue'` is cut at its own comma into two unterminated literals.
+ """
+ members: list[str] = []
+ current = ""
+ quote: str | None = None
+ escaped = False
+ for char in members_text:
+ if escaped:
+ escaped = False
+ elif quote is not None:
+ if char == "\\":
+ escaped = True
+ elif char == quote:
+ quote = None
+ elif char in {'"', "'"}:
+ quote = char
+ elif char == ",":
+ members.append(current.strip())
+ current = ""
+ continue
+ current += char
+ members.append(current.strip())
+ return members
def _format_default_value(value: Any) -> str:
- """Render a JSON-safe default canonically so mapping insertion order cannot affect output."""
- return json.dumps(clean_json_content(value), sort_keys=True)
+ """Render a JSON-safe default as a canonical *TypeScript* literal, not a JSON one.
+
+ Keys are sorted so mapping insertion order cannot affect the output. Beyond that the two spellings
+ diverge on objects, and JSON's is the one prettier rewrites: it pads the braces (`{ a: 1 }`) and drops
+ the quotes from every key that is a valid identifier, at any line width. Emitting JSON therefore made a
+ single dict-valued default enough to have a consumer's formatter change the bytes and `pipelex codegen
+ check` report an untouched artifact as hand-edited. Scalars and arrays are spelled the same in both.
+ """
+ return _ts_literal(clean_json_content(value))
+
+
+# A key prettier is willing to leave unquoted in an object literal: a plain JS identifier.
+_TS_IDENTIFIER = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$]*$")
+
+
+def _ts_string(text: str) -> str:
+ """A string literal in the quote style prettier would leave alone — the same rule ruff applies to Python.
+
+ Double quotes by default, single only where that **strictly reduces** the escape count. `json.dumps`
+ always double-quotes, so a choice or default carrying a `"` came out double-quoted with both quotes
+ escaped, which prettier rewrites to the escape-free `'say "hi"'` on a consumer's first format run,
+ reporting the artifact as hand-edited.
+ """
+ quote = "'" if text.count("'") < text.count('"') else '"'
+ body = json.dumps(text)[1:-1].replace('\\"', '"').replace(quote, f"\\{quote}")
+ return f"{quote}{body}{quote}"
+
+
+def _ts_literal(value: Any) -> str:
+ """One JSON-safe value as the TypeScript literal prettier would leave alone."""
+ if isinstance(value, str):
+ return _ts_string(value)
+ if isinstance(value, dict):
+ pairs = cast("dict[str, Any]", value)
+ if not pairs:
+ return "{}"
+ rendered = ", ".join(f"{_ts_object_key(key)}: {_ts_literal(pairs[key])}" for key in sorted(pairs))
+ return f"{{ {rendered} }}"
+ if isinstance(value, list):
+ items = cast("list[Any]", value)
+ return f"[{', '.join(_ts_literal(item) for item in items)}]"
+ return json.dumps(value)
+
+
+def _ts_object_key(key: Any) -> str:
+ """An object-literal key, quoted only where prettier keeps the quotes (a non-identifier key).
+
+ A non-string key is stringified first, exactly as `json.dumps` used to coerce one — `default_value` is
+ typed `Any`, so nothing but authoring convention keeps a non-string out, and a crash here would be a
+ worse 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)
def _concept_type_expr(
@@ -189,9 +361,15 @@ def _render_type_field(
by_ref: dict[str, ResolvedConcept],
type_name_by_ref: dict[str, str],
) -> str:
- optional_marker = "?" if not concept_field.required and concept_field.default_value is None else ""
type_expr = _ts_type(concept_field.resolved_type, by_ref=by_ref, type_name_by_ref=type_name_by_ref)
- return f" {concept_field.name}{optional_marker}: {type_expr};"
+ # Mirror `_presence_modifiers` branch for branch: this declared type is what the annotated
+ # `z.ZodType<Name>` is checked against, so it has to be exactly the schema's inferred output —
+ # `.nullable().default(…)` infers `T | null`, `.nullish()` infers `T | null | undefined`.
+ if concept_field.default_value is not None:
+ return f" {concept_field.name}: {type_expr} | null;"
+ if not concept_field.required:
+ return f" {concept_field.name}?: {type_expr} | null;"
+ return f" {concept_field.name}: {type_expr};"
def _ts_type(
@@ -209,7 +387,7 @@ def _ts_type(
case ResolvedTypeKind.BOOLEAN:
return "boolean"
case ResolvedTypeKind.LITERAL:
- return " | ".join(json.dumps(choice) for choice in resolved_type.choices or [])
+ return " | ".join(_ts_string(choice) for choice in resolved_type.choices or [])
case ResolvedTypeKind.CONCEPT:
return _concept_type(resolved_type, by_ref=by_ref, type_name_by_ref=type_name_by_ref)
case ResolvedTypeKind.LIST:
@@ -288,7 +466,7 @@ def _zod_type(
# ISO date / datetime / time string on the wire (the `@wire` field keeps the shape documented).
return "z.string()"
case ResolvedTypeKind.LITERAL:
- choices = ", ".join(json.dumps(choice) for choice in resolved_type.choices or [])
+ choices = ", ".join(_ts_string(choice) for choice in resolved_type.choices or [])
return f"z.enum([{choices}])"
case ResolvedTypeKind.CONCEPT:
return _concept_schema(resolved_type, by_ref=by_ref, type_name_by_ref=type_name_by_ref)
diff --git a/subject_grants.toml b/subject_grants.toml
index 8c50afbaf..2a7493224 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -1068,6 +1068,10 @@ rationale = "Noun-named derivation: the type expr for the concept; context stays
param = "concepts"
rationale = "Verb-object: emits the binder for the concepts; mapping stays keyword."
+["pipelex/codegen/emitters/ts_zod.py::_explode_enum_call"]
+param = "call"
+rationale = "Verb-object: explodes the enum call it is handed; the column stays keyword."
+
["pipelex/codegen/emitters/ts_zod.py::_find_recursive_concept_refs"]
param = "concepts"
rationale = "Single-operand analysis over the concepts collection."
@@ -1076,10 +1080,22 @@ rationale = "Single-operand analysis over the concepts collection."
param = "value"
rationale = "Single-operand formatting of the value."
+["pipelex/codegen/emitters/ts_zod.py::_is_enum_call"]
+param = "call"
+rationale = "Verb-object predicate over the one member call it classifies."
+
["pipelex/codegen/emitters/ts_zod.py::_jsdoc"]
param = "description"
rationale = "Noun-named derivation: builds the JSDoc from the description; extras stay keyword."
+["pipelex/codegen/emitters/ts_zod.py::_presence_modifiers"]
+param = "concept_field"
+rationale = "Reads as a verb-object sentence over the one field it describes, matching every other renderer in this emitter."
+
+["pipelex/codegen/emitters/ts_zod.py::_render_broken_call"]
+param = "call"
+rationale = "Verb-object: renders the one member call it is handed; the column stays keyword."
+
["pipelex/codegen/emitters/ts_zod.py::_render_field"]
param = "concept_field"
rationale = "Verb-object: renders the field; context stays keyword."
@@ -1104,10 +1120,30 @@ rationale = "Single-operand sanitization of the text."
param = "concept"
rationale = "Noun-named derivation: the schema expr for the concept; context stays keyword."
+["pipelex/codegen/emitters/ts_zod.py::_split_enum_members"]
+param = "members_text"
+rationale = "Verb-object: splits the enum member text it is handed, its one operand."
+
+["pipelex/codegen/emitters/ts_zod.py::_split_member_chain"]
+param = "expr"
+rationale = "Verb-object: splits the zod expression into its member chain, its one operand."
+
+["pipelex/codegen/emitters/ts_zod.py::_ts_literal"]
+param = "value"
+rationale = "Single-operand formatting of the value, matching the sibling default-value renderers."
+
+["pipelex/codegen/emitters/ts_zod.py::_ts_object_key"]
+param = "key"
+rationale = "Single-operand formatting of the key it quotes."
+
["pipelex/codegen/emitters/ts_zod.py::_ts_signature"]
param = "name"
rationale = "Verb-object: renders the signature for the named function; param and return type are context."
+["pipelex/codegen/emitters/ts_zod.py::_ts_string"]
+param = "text"
+rationale = "Single-operand formatting of the text it quotes."
+
["pipelex/codegen/emitters/ts_zod.py::_ts_type"]
param = "resolved_type"
rationale = "Noun-named derivation: the TS type for the resolved type; context stays keyword."
diff --git a/tests/unit/pipelex/codegen/conftest.py b/tests/unit/pipelex/codegen/conftest.py
index 05a740587..bb9bbd66c 100644
--- a/tests/unit/pipelex/codegen/conftest.py
+++ b/tests/unit/pipelex/codegen/conftest.py
@@ -237,6 +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.
+ "quotas": ConceptStructureBlueprint(
+ description="Quotas",
+ type=ConceptStructureBlueprintFieldType.DICT,
+ key_type="text",
+ value_type="integer",
+ default_value={"per-reviewer": 3, "total": 12},
+ ),
# ANY — only reachable nested, from genuine source imprecision. An untyped list also
# emits the trailing `# imprecise:` comment, so that shape gets linted too.
"items": ConceptStructureBlueprint(description="Untyped items", type=ConceptStructureBlueprintFieldType.LIST, required=True),
@@ -264,6 +274,74 @@ def every_type_kind_crate() -> LibraryCrate:
choices=["awaiting_triage", "in_progress_with_owner", "blocked_on_dependency", "ready_for_review"],
required=False,
),
+ # A choice carrying a comma, on a list long enough to force the explode. Split naively
+ # this became two unterminated string literals in every target — generated code that
+ # does not parse, which the lint-clean guards catch only if a fixture carries the shape.
+ "escalation_reason": ConceptStructureBlueprint(
+ description="Why it escalated",
+ choices=["blocked, awaiting the owner", "stale, no movement for a week", "ready for review"],
+ required=True,
+ ),
+ # A choice carrying a double quote. Both formatters normalize a string literal to the
+ # quote style needing fewer escapes, so the naive always-double spelling
+ # (`"marked \"urgent\""`) is rewritten to a single-quoted one on the consumer's first
+ # format run — at any line width, in both languages.
+ "reviewer_verdict": ConceptStructureBlueprint(
+ description='Whether the reviewer marked it "urgent"',
+ choices=['marked "urgent"', "left unmarked"],
+ required=True,
+ ),
+ # The intersection the two shapes above never combined: a choice carrying a comma AND a
+ # double quote, on a list long enough to explode. The quote makes `_ts_string` spell it
+ # single-quoted, and a member split that walks only `"` then cuts at the inner comma —
+ # two unterminated literals again, on the one spelling the comma fix did not cover.
+ "escalation_note": ConceptStructureBlueprint(
+ description="A note explaining the escalation",
+ choices=['say "hi", then continue', "left unmarked", "needs another look"],
+ required=True,
+ ),
+ # Enumerated answer options: ordinary prose whose `)` closers are unmatched. They are
+ # inside string literals, so a chain split that counts brackets without tracking quotes
+ # reaches depth zero mid-literal and cuts the member chain there.
+ "survey_answer": ConceptStructureBlueprint(
+ description="The reviewer's answer",
+ choices=["a) strongly agree with the proposal", "b) agree. with some reservations", "c unsure"],
+ required=True,
+ ),
+ # The same unbounded choice list carrying a default — the widest presence spelling
+ # ts-zod emits (`.nullable().default(…)` on top of a broken `z.enum([…])`), so the
+ # print-width and prettier guards actually exercise the multi-member chain break.
+ "fallback_state": ConceptStructureBlueprint(
+ description="Fallback workflow state",
+ choices=["awaiting_triage", "in_progress_with_owner", "blocked_on_dependency", "ready_for_review"],
+ default_value="awaiting_triage",
+ ),
+ # A short choice list that only overflows once `.nullable().default(…)` is attached.
+ # Prettier re-measures each call after breaking the chain, so the enum goes back onto
+ # one line at indent 4 — exploding its members regardless is a shape prettier folds
+ # straight back, which is exactly the stamp break the breaking exists to prevent.
+ "escalation_severity": ConceptStructureBlueprint(
+ description="How severe the escalation is",
+ choices=["low", "medium", "high"],
+ default_value="medium",
+ ),
+ # The overflow that has nothing to do with the *expression*: `z.string()` is as short as
+ # they come, and this line still passes prettier's print width on the authored field name
+ # and default literal alone. It is the shape that makes the member-chain break general
+ # rather than a `z.enum` special case, so the width and prettier guards must carry it.
+ "default_summary_style": ConceptStructureBlueprint(
+ description="How the summary should be written",
+ type=ConceptStructureBlueprintFieldType.TEXT,
+ default_value="a concise executive summary",
+ ),
+ # The same overflow reached through a nested type rather than a long default.
+ "per_reviewer_summary_style_overrides": ConceptStructureBlueprint(
+ description="Summary style per reviewer",
+ type=ConceptStructureBlueprintFieldType.DICT,
+ key_type="text",
+ value_type="text",
+ required=False,
+ ),
},
),
# A multi-line description, and one padded with edge whitespace. Rendered naively the first
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.py
index db257650f..0f5679278 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
@@ -302,6 +302,39 @@ class TestEmittedArtifactsAreLintClean:
offenders = [line for line in emitted_file.content.splitlines() if line != line.rstrip()]
assert not offenders, f"{emitted_file.filename} has lines with trailing whitespace:\n" + "\n".join(repr(line) for line in offenders)
+ def test_emitted_ts_never_breaks_a_line_inside_a_string_literal(self, every_type_kind_crate: LibraryCrate):
+ """No emitted line may end inside an unterminated string literal.
+
+ This is the always-on guard for a whole class of defect the other three are blind to. Every
+ emitted break is computed by splitting a rendered expression — on its member commas, or on its
+ 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.
+ """
+ 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):
+ # Comment lines are prose, not code: an authored description may hold an apostrophe, and
+ # the emitted grammar keeps every comment on a line of its own (`//`, `/** … */`, ` * `).
+ if line.lstrip().startswith(("//", "/*", "*")):
+ continue
+ quote: str | None = None
+ escaped = False
+ for char in line:
+ if escaped:
+ escaped = False
+ elif quote is not None and char == "\\":
+ escaped = True
+ elif quote is not None:
+ quote = None if char == quote else quote
+ elif char in {'"', "'"}:
+ quote = char
+ assert quote is None, f"{emitted_file.filename}:{line_number} ends inside a {quote} literal: {line!r}"
+
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.
diff --git a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py b/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
index 24e8fffec..b8cd9091d 100644
--- a/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
+++ b/tests/unit/pipelex/codegen/test_ts_zod_emitter.py
@@ -41,14 +41,101 @@ class TestTsZodEmitter:
def test_concept_refs_use_lazy_and_literals_keep_defaults(self, pipeline_crate: LibraryCrate):
content = emit_ts_zod(resolve_concepts_from_crate(pipeline_crate))[0].content
# A concept reference is a forward-safe lazy schema; the literal-with-default is a defaulted enum.
- assert "score: z.lazy(() => ScoreSchema).optional()" in content
- assert 'status: z.enum(["draft", "final"]).default("draft")' in content
+ assert "score: z.lazy(() => ScoreSchema).nullish()" in content
+ assert 'status: z.enum(["draft", "final"]).nullable().default("draft")' in content
+
+ def test_non_required_fields_are_null_tolerant(self, pipeline_crate: LibraryCrate):
+ """Both non-required spellings must accept the explicit `null` the runtime puts on the wire.
+
+ An unset optional field is dumped as `"key": null` (the generated runtime class annotates it
+ `X | None` and `dump_for_transport()` carries no `exclude_none`), so a `.optional()` schema —
+ `T | undefined` in zod — rejects the engine's own payload. `.nullish()` and `.nullable()` are
+ the two null-tolerant spellings; `.optional()` alone must appear nowhere.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(pipeline_crate))[0].content
+ assert ".optional()" not in content
+ # No default: the wire may omit the key *or* null it, and `.nullish()` describes exactly that.
+ assert "rationale: z.string().nullish()" in content
+ # With a default: absent applies the default, explicit null stays null.
+ assert 'status: z.enum(["draft", "final"]).nullable().default("draft")' in content
+
+ def test_an_overlong_field_breaks_its_whole_member_chain(self, every_type_kind_crate: LibraryCrate):
+ """Prettier breaks by call count, not by expression, so the break cannot be a `z.enum` special case.
+
+ `z.string()` is the shortest expression the emitter produces, and a defaulted one still overflows on
+ the authored field name and default literal alone. Left flat, a consumer's prettier run rewrites the
+ bytes and `pipelex codegen check` reports an untouched artifact as hand-edited. Both shapes below are
+ prettier 3.9.6's own output for the emitted crate.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' default_summary_style: z\n .string()\n .nullable()\n .default("a concise executive summary"),' in content
+ assert " per_reviewer_summary_style_overrides: z\n .record(z.string(), z.string())\n .nullish()," in content
+ # A single call has no chain to break: prettier explodes the enum members in place instead.
+ assert ' workflow_state: z.enum([\n "awaiting_triage",' in content
+
+ def test_a_broken_chain_keeps_a_call_that_fits_on_its_own_line(self, every_type_kind_crate: LibraryCrate):
+ """Prettier re-measures every call once the chain is broken, and one that now fits stays flat.
+
+ The counterpart to the test above: `.nullable()` costs width on every defaulted field, so an
+ ordinary three-choice enum reaches the break on nothing but that — and then sits far inside the
+ print width at indent 4. Exploding its members anyway produces a shape prettier folds straight
+ back, changing the artifact's bytes on the consumer's first format run. The threshold is exact:
+ a call is left flat while `indent + len(call)` fits, and `fallback_state` above is the same
+ shape past it.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' escalation_severity: z\n .enum(["low", "medium", "high"])\n .nullable()\n .default("medium"),' in content
+
+ def test_an_exploded_choice_keeps_its_own_commas(self, every_type_kind_crate: LibraryCrate):
+ """A choice is authored text and may carry a comma; split on it, the emission stops being TypeScript.
+
+ Nothing else in this repo catches it: the broken form is two *short* unterminated string literals,
+ so the print-width guard is blind to it and no always-on test parses the emitted TypeScript.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' escalation_reason: z.enum([\n "blocked, awaiting the owner",\n "stale, no movement for a week",' in content
+
+ def test_an_exploded_single_quoted_choice_keeps_its_own_commas(self, every_type_kind_crate: LibraryCrate):
+ """A choice carrying a `"` is spelled single-quoted, and it may carry a comma too.
+
+ The two guards either side of this one cover the halves separately — a comma in a double-quoted
+ choice, and a `"` in a choice short enough to stay flat. The defect lives in the intersection:
+ split a single-quoted member on its own comma and the emission stops being TypeScript.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' escalation_note: z.enum([\n \'say "hi", then continue\',\n "left unmarked",' in content
+
+ def test_an_exploded_choice_keeps_its_own_brackets(self, every_type_kind_crate: LibraryCrate):
+ """A choice is prose and its brackets need not balance — `a)` is an ordinary answer option.
+
+ The member-chain split counts brackets to find the depth-zero dots, so counting the ones *inside*
+ a literal walks the depth to zero mid-string and cuts the chain there, mid-literal.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' survey_answer: z.enum([\n "a) strongly agree with the proposal",\n' in content
+ assert ' "b) agree. with some reservations",\n "c unsure",\n ]),' in content
+
+ def test_a_quoted_choice_takes_the_quote_style_prettier_keeps(self, every_type_kind_crate: LibraryCrate):
+ """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.
+ """
+ content = emit_ts_zod(resolve_concepts_from_crate(every_type_kind_crate))[0].content
+
+ assert ' reviewer_verdict: z.enum([\'marked "urgent"\', "left unmarked"]),' in content
def test_temporal_defaults_emit_iso_wire_strings(self, temporal_defaults_crate: LibraryCrate):
content = emit_ts_zod(resolve_concepts_from_crate(temporal_defaults_crate))[0].content
- assert 'starts_on: z.string().default("2026-07-11")' in content
- assert 'recorded_at: z.string().default("2026-07-11T09:30:00")' in content
- assert 'starts_at: z.string().default("09:30:00")' in content
+ assert 'starts_on: z.string().nullable().default("2026-07-11")' in content
+ assert 'recorded_at: z.string().nullable().default("2026-07-11T09:30:00")' in content
+ assert 'starts_at: z.string().nullable().default("09:30:00")' in content
def test_dict_defaults_are_canonical(self, reordered_dict_default_crates: tuple[LibraryCrate, LibraryCrate]):
first_crate, second_crate = reordered_dict_default_crates
@@ -57,7 +144,10 @@ class TestTsZodEmitter:
second_output = emit_ts_zod(resolve_concepts_from_crate(second_crate))
assert first_output == second_output
- assert 'default({"alpha": "first", "zeta": "last"})' in first_output[0].content
+ # A *TypeScript* object literal, not a JSON one: prettier pads the braces and unquotes every key
+ # that is a plain identifier, at any line width, so the JSON spelling made a single dict-valued
+ # default enough to have a consumer's formatter rewrite the artifact and break its stamp.
+ assert 'default({ alpha: "first", zeta: "last" })' in first_output[0].content
def test_explicitly_empty_structure_emits_an_empty_object_schema(self):
crate = LibraryCrate(
@@ -91,8 +181,37 @@ class TestTsZodEmitter:
content = emit_ts_zod(resolve_concepts_from_crate(crate))[0].content
- assert "export type Node = {\n next?: Node;\n};" in content
+ # The declared type is what `z.ZodType<Node>` is checked against, so it must be the schema's
+ # inferred output exactly: `.nullish()` infers `Node | null | undefined`.
+ assert "export type Node = {\n next?: Node | null;\n};" in content
assert "export const NodeSchema: z.ZodType<Node> = z.object({" in content
+ assert "next: z.lazy(() => NodeSchema).nullish()" in content
+
+ def test_recursive_defaulted_field_declares_a_nullable_type(self):
+ """The other explicit-type branch: a defaulted field infers `T | null` with no `?` marker."""
+ crate = LibraryCrate(
+ concepts={
+ "graph.Node": ConceptBlueprint(
+ description="A recursive node",
+ structure={
+ "next": ConceptStructureBlueprint(
+ description="Next node",
+ type=ConceptStructureBlueprintFieldType.CONCEPT,
+ concept_ref="graph.Node",
+ required=False,
+ ),
+ "label": ConceptStructureBlueprint(description="A label", type=ConceptStructureBlueprintFieldType.TEXT, default_value="root"),
+ "depth": ConceptStructureBlueprint(description="How deep", type=ConceptStructureBlueprintFieldType.INTEGER, required=True),
+ },
+ )
+ }
+ )
+
+ content = emit_ts_zod(resolve_concepts_from_crate(crate))[0].content
+
+ assert "export type Node = {\n next?: Node | null;\n label: string | null;\n depth: number;\n};" in content
+ assert 'label: z.string().nullable().default("root")' in content
+ assert "depth: z.number().int()," in content
def test_mutually_recursive_concepts_use_explicit_types_and_annotated_schemas(self):
crate = LibraryCrate(
@@ -249,10 +368,10 @@ class TestTsZodEmitter:
`Image` materializes flat pixel dimensions.
"""
content = emit_ts_zod(resolve_concepts_from_crate(materialized_image_crate))[0].content
- assert "metadata: z.record(z.string(), z.unknown()).optional()" in content
+ assert "metadata: z.record(z.string(), z.unknown()).nullish()" in content
assert "@imprecise dict value type unspecified" in content
assert "captions: z.record(z.string(), z.string())" in content
- assert "width: z.number().int().optional()" in content
+ assert "width: z.number().int().nullish()" in content
def test_imprecision_and_opaque_are_surfaced(self, edge_crate: LibraryCrate):
content = emit_ts_zod(resolve_concepts_from_crate(edge_crate))[0].content
diff --git a/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py b/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py
new file mode 100644
index 000000000..dd615001b
--- /dev/null
+++ b/tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py
@@ -0,0 +1,212 @@
+"""The ts-zod projection must accept the payload the runtime actually puts on the wire.
+
+The two sides read one authored crate. `ConceptFactory` builds the class an interpreted run stores in
+memory, and that class annotates every non-required field `X | None`; the transport dump keeps nulls on
+purpose (`dump_for_transport()` is a `model_dump(serialize_as_any=True)` with no `exclude_none`, and the
+composer spells `exclude_none=False` at its dump sites). So an unset optional field reaches a consumer as
+an explicit `"key": null`. `emit_ts_zod` writes the schema that consumer parses it with — and `.optional()`
+means `T | undefined` in zod, which *rejects* an explicit null. A projection that spelled it that way would
+refuse the engine's own output, with nothing in this repo going red.
+
+Three layers, on one shared crate:
+
+1. **Wire pin** — build the runtime class and dump it the way transport does, asserting the unset keys are
+ present and null. This is the fact the projection must accommodate; if the transport dump ever flips to
+ `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 be
+ null-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.
+"""
+
+import json
+import shutil
+import subprocess # ruff: ignore[suspicious-subprocess-import]
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from pipelex.codegen.emitters.ts_zod import emit_ts_zod
+from pipelex.codegen.resolved_concepts import resolve_concepts_from_crate
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType
+from pipelex.core.domains.domain_blueprint import DomainBlueprint
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.libraries.crate_normalization import normalize_crate
+from pipelex.libraries.library_crate import LibraryCrate
+from pipelex.system.registries.class_registry_access import get_class_registry
+from tests.unit.pipelex.codegen.conftest import CRATE_TEST_VERSION
+
+_DOMAIN = "wire"
+
+# One authored source, read by both sides. Declaration order matters for the runtime reader only:
+# `Payload` references `Detail`, so `Detail`'s generated class has to be registered first.
+_AUTHORED: dict[str, ConceptBlueprint] = {
+ "Detail": ConceptBlueprint(
+ description="A nested detail",
+ structure={
+ "caption": ConceptStructureBlueprint(description="A caption", type=ConceptStructureBlueprintFieldType.TEXT, required=True),
+ "weight": ConceptStructureBlueprint(description="How much it counts", type=ConceptStructureBlueprintFieldType.NUMBER, required=False),
+ },
+ ),
+ "Payload": ConceptBlueprint(
+ description="A payload covering every presence spelling the wire carries",
+ structure={
+ "title": ConceptStructureBlueprint(description="Title", type=ConceptStructureBlueprintFieldType.TEXT, required=True),
+ "note": ConceptStructureBlueprint(description="An optional note", type=ConceptStructureBlueprintFieldType.TEXT, required=False),
+ "detail": ConceptStructureBlueprint(
+ description="A nested detail", type=ConceptStructureBlueprintFieldType.CONCEPT, concept_ref="Detail", required=False
+ ),
+ "tags": ConceptStructureBlueprint(
+ description="Free-form tags", type=ConceptStructureBlueprintFieldType.LIST, item_type="text", required=False
+ ),
+ "counts": ConceptStructureBlueprint(
+ description="Counts by key",
+ type=ConceptStructureBlueprintFieldType.DICT,
+ key_type="text",
+ value_type="integer",
+ required=False,
+ ),
+ "status": ConceptStructureBlueprint(description="Review status", choices=["draft", "final"], default_value="draft"),
+ },
+ ),
+}
+
+# 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(
+ concepts={f"{_DOMAIN}.{code}": blueprint for code, blueprint in _AUTHORED.items()},
+ domains={_DOMAIN: DomainBlueprint(code=_DOMAIN, description="Wire agreement domain")},
+ )
+
+
+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.fixture
+ def wire_payloads(self, load_empty_library: Any) -> list[dict[str, Any]]:
+ """What the runtime hands to transport for two ordinary instances, unset optionals and all.
+
+ The first leaves every optional unset — the shape the ledger item's hosted `PipeImgGen` run
+ produced. The second nulls the *defaulted* field explicitly, which a producer may do because the
+ generated annotation is `X | None`: that is the payload a bare `.default(…)` rejects.
+ """
+ load_empty_library()
+ registry = get_class_registry()
+ classes: dict[str, Any] = {}
+ for code, blueprint in _AUTHORED.items():
+ concept = ConceptFactory.make_from_blueprint(domain_code=_DOMAIN, concept_code=code, blueprint_or_string_description=blueprint)
+ classes[concept.structure_class_name] = registry.get_required_subclass(name=concept.structure_class_name, base_class=StuffContent)
+ classes[code] = classes[concept.structure_class_name]
+ # A concept reference is generated as a quoted forward ref, so the classes need the same rebuild
+ # against a shared namespace the library manager performs on load (`_rebuild_models_with_forward_refs`).
+ for structure_class in dict.fromkeys(classes.values()):
+ structure_class.model_rebuild(_types_namespace=classes)
+
+ # `Detail` exists only to be referenced; `Payload` is the one that gets dumped.
+ payload_class = classes["Payload"]
+ return [
+ payload_class(title="Everything optional left unset").model_dump(serialize_as_any=True),
+ payload_class(title="A producer nulling the defaulted field", status=None).model_dump(serialize_as_any=True),
+ ]
+
+ def test_the_wire_carries_unset_optionals_as_explicit_nulls(self, wire_payloads: list[dict[str, Any]]):
+ """The fact the projection has to accommodate — pinned here so it cannot change unnoticed."""
+ unset, nulled_default = wire_payloads
+
+ assert unset["title"] == "Everything optional left unset"
+ for field_name in ("note", "detail", "tags", "counts"):
+ assert field_name in unset, f"{field_name} was dropped from the transport dump"
+ assert unset[field_name] is None, f"{field_name} is {unset[field_name]!r}, not the explicit null the wire carries"
+ # A defaulted field is not nulled when unset — the default is applied — but it can be nulled explicitly.
+ assert unset["status"] == "draft"
+ assert nulled_default["status"] is None
+
+ def test_every_non_required_field_projects_null_tolerant(self):
+ """`.optional()` alone is `T | undefined` in zod, and would reject the payload pinned above."""
+ content = emit_ts_zod(resolve_concepts_from_crate(normalize_crate(_authored_crate(), mthds_version=CRATE_TEST_VERSION)))[0].content
+
+ assert ".optional()" not in content
+ for field_name in _NON_REQUIRED_FIELDS:
+ # Every field of this crate is short enough to stay on one line, so a missing match means the
+ # field vanished from the projection rather than that it was broken across lines.
+ line = next((line for line in content.splitlines() if line.strip().startswith(f"{field_name}: ")), None)
+ assert line is not None, f"{field_name} has no field line in the emitted schema"
+ assert ".nullish()" in line or ".nullable()" in line, f"{field_name} is not null-tolerant: {line.strip()}"
+ # The nested concept's own optional field, reached through the reference rather than declared beside it.
+ assert "weight: z.number().nullish()," in content
+
+ 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.
+ """
+ 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")
+
+ 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")
+ (tmp_path / "package.json").write_text('{ "type": "module" }\n', encoding="utf-8")
+ (tmp_path / "node_modules").mkdir()
+ (tmp_path / "node_modules" / "zod").symlink_to(zod_package, target_is_directory=True)
+ (tmp_path / "wire.json").write_text(json.dumps(wire_payloads), encoding="utf-8")
+ (tmp_path / "driver.ts").write_text(
+ 'import { readFileSync } from "node:fs";\n'
+ 'import { PayloadSchema } from "./types.ts";\n'
+ 'const wire = JSON.parse(readFileSync("wire.json", "utf-8"));\n'
+ "process.stdout.write(JSON.stringify(wire.map((one: unknown) => PayloadSchema.parse(one))));\n",
+ encoding="utf-8",
+ )
+
+ run = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]
+ [node, "--experimental-strip-types", "--no-warnings", "driver.ts"],
+ cwd=tmp_path,
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert run.returncode == 0, f"the emitted schema rejected the runtime's own payload:\n{run.stdout}\n{run.stderr}"
+
+ unset, nulled_default = json.loads(run.stdout)
+ # Nulls survive as nulls: the schema describes the wire, it does not fold `null` into `undefined`
+ # (the binder uses one schema for both parse and serialize, so a transform would desynchronize them).
+ for field_name in ("note", "detail", "tags", "counts"):
+ assert unset[field_name] is None, f"{field_name} came back as {unset[field_name]!r} instead of null"
+ assert unset["status"] == "draft"
+ assert nulled_default["status"] is None
diff --git a/wip/ts-zod-wire-null/plan.md b/wip/ts-zod-wire-null/plan.md
new file mode 100644
index 000000000..57b7cfcd4
--- /dev/null
+++ b/wip/ts-zod-wire-null/plan.md
@@ -0,0 +1,168 @@
+---
+status: active
+item: L-260820-ee327d
+---
+
+# ts-zod projection: accept the wire's explicit nulls
+
+Ledger item: L-260820-ee327d. Branch: `fix/Zod-codegen` (worktree `_zod`).
+
+## The problem
+
+The ts-zod emitter projects a non-required concept field as `.optional()`, which in zod means `T | undefined` and rejects `null`. The runtime serializes an unset optional field as an explicit `null`: the generated runtime class annotates every non-required field `X | None` (`pipelex/core/concepts/structure_generation/generator.py`, `_generate_field_line`), and the transport dump keeps nulls deliberately — `dump_for_transport()` is `model_dump(serialize_as_any=True)` with no `exclude_none` (`pipelex/core/memory/working_memory.py`), and the composer even spells `exclude_none=False` at every dump site (`pipelex/pipe_operators/compose/structured_content_composer.py`). So the generated `Schema.parse` rejects the very payload the runtime produces — live evidence in the ledger item: a successful hosted `PipeImgGen` run fails `ImageSchema.parse` with one issue per nulled optional.
+
+## Decision: fix the projection, not the wire
+
+Emit a null-tolerant zod modifier for non-required fields. The alternative — dumping the transport payload with `exclude_none=True` so absent means absent — is rejected:
+
+- The runtime keeps nulls **on purpose**: `exclude_none=False` is written out explicitly at the composer's dump sites. The transport dict also feeds the Temporal data converter and the hydrator; changing its shape is a wire redesign with its own review, not a codegen bug fix.
+- The Python projections already accept both spellings — `python-pydantic` and `python-structures` both render non-required fields as `X | None = Field(default=None)`. ts-zod is the one projection that disagrees with the runtime; this is a parity fix.
+- The wire genuinely carries both spellings of "unset" (a key omitted by a partial payload versus a key the runtime nulled). A projection should describe the wire honestly, and `.nullish()` is exactly that description. No `.transform()` to fold `null` into `undefined`: the binder uses one schema for both `parse` and `serialize`, and a transform would make them asymmetric.
+
+Consumer cost: parsed values are `T | null | undefined` instead of `T | undefined`; `??` covers both.
+
+## Phase 1 — emitter change
+
+All in `pipelex/codegen/emitters/ts_zod.py`:
+
+- `_render_field`: non-required without default → `.nullish()` (today `.optional()`); non-required **with** default → `.nullable().default(...)` (today `.default(...)` alone, which rejects null even though the runtime type is `X | None = Field(default=…)` and a producer can set it to `None` explicitly). The blueprint validator rejects `required = true` beside a default (E3), so every defaulted field is non-required — the `.default(...)` branch always needs `.nullable()`.
+- `_render_type_field` (the explicit-type path for recursive concepts): widen every non-required field's type with `| null`; keep the `?` marker only for the no-default case, as today. The declared type must match the schema's inferred output (`.nullish()` → `field?: T | null`; `.nullable().default(…)` → `field: T | null`) or the `z.ZodType<Name>` annotation stops typechecking.
+- Prettier-width modeling: `.nullish()` is shorter than `.optional()` — no risk there — but `.nullable().default(...)` adds width to a branch `_break_zod_expr` only models for `z.enum`. Extend the crate fixtures (Phase 2) so the width guard exercises the new form; if `test_emitted_ts_lines_fit_the_print_width` or the prettier-clean test reds, extend `_break_zod_expr` to model prettier's member-chain break for the overflowing shape rather than loosening the guard.
+
+`.nullish()` and `.nullable()` exist in both zod 3 and zod 4, so the emitted `import { z } from "zod"` contract is unchanged.
+
+## Phase 2 — tests
+
+- Update `tests/unit/pipelex/codegen/test_ts_zod_emitter.py`: the `.optional()` assertions become `.nullish()`; the defaulted assertions (`status`, `starts_on`, `recorded_at`) gain `.nullable()`. Add explicit coverage for both modifier branches and for the recursive-concept explicit-type path carrying `| null`.
+- Make sure the `every_type_kind_crate` fixture carries a non-required defaulted field, so the always-on width/whitespace guards and the local prettier-clean test exercise `.nullable().default(...)`.
+- New module `tests/unit/pipelex/codegen/test_ts_zod_wire_agreement.py` — the round-trip check the ledger item asks for, in three layers on one shared crate (non-required fields with and without defaults, nested concept, list/dict types):
+ 1. **Wire pin (always on, pure Python).** Build the runtime class the way the runtime does (`ConceptFactory` / the structure generator, as `test_projection_agrees_with_runtime_base.py` already does), instantiate it with the optionals unset, dump via the transport idiom (`model_dump(serialize_as_any=True)`), and assert the unset keys are present with `None`. This pins the wire truth the projection must accept; if the transport dump ever flips to `exclude_none`, this test reds and forces the projection decision to be revisited together with it.
+ 2. **Projection pin (always on).** Emit ts-zod for the same crate and assert every non-required field's expression is null-tolerant. Paired with (1), the cross-language contract is encoded in this repo even where CI has no node.
+ 3. **Executable round-trip (local-only, skip-gated like `test_emitted_ts_is_prettier_clean`).** When `node` (≥ 22.6, for `--experimental-strip-types`) and a globally installed `zod` (`npm root -g`) are available: write the emitted `types.ts` plus a tiny driver into a tmp dir, symlink the global `zod` into a local `node_modules`, feed the JSON from (1) through `Schema.parse`, and assert success and that nulls survive as nulls. Skip otherwise — the always-on pins hold the line in CI.
+
+## Phase 3 — docs and changelog
+
+- `docs/under-the-hood/codegen-projections.md`: state the optionality contract in one place — the runtime serializes unset optionals as explicit `null`, every projection must accept both spellings, and per target that means `X | None` (Python) and `.nullish()` / `.nullable().default(…)` with `| null` types (ts-zod).
+- `CHANGELOG.md` under `## [Unreleased]`: breaking for generated TypeScript artifacts — regenerate; parsed optional fields now type as `T | null | undefined`.
+
+## Phase 4 — landing and follow-through
+
+- Run `make agent-check` and `make agent-test`; PR against `dev` with `Closes L-260820-ee327d` in the body.
+- File the consumer cleanup now, blocked on this item: a `pipelex-starter-js`-owned item to delete `src/lib/wireOutput.ts` (`dropWireNulls`) and regenerate `src/generated/` once a pipelex release carrying this fix is deployed to the hosted codegen route. The workaround silently strips legitimate nulls inside opaque fields, so it should not outlive the fix.
+- Note for L-260830-344594 (pipelex-integrate skill): its plan carries a pre-ship re-check of this item — once this ships in the hosted engine, the skill never writes the wireOutput helper into user projects. Drop a `ledger note` on that item when this merges.
+
+The fix reaches consumers only through a pipelex release plus an api-dev deploy (the starter consumes the projection via hosted `POST /v1/codegen`); the release itself rides the normal release train and is not scheduled by this plan.
+
+## Checkpoint — Phases 1–3 done, green locally
+
+**`_break_zod_expr` did need extending, and the reason is prettier's member-chain rule, not width.** The modifier was a single string; `.nullable().default(…)` is two member calls, and once prettier breaks a member chain it puts *every* call on its own line — so the emitted overflow form had to become `z\n .enum([…])\n .nullable()\n .default("…")`. The fix is to carry the presence modifiers as a **list** end to end: `_presence_modifiers(concept_field)` returns the chain, `_render_field` joins it flat, and `_break_zod_expr` renders one member per line. Nothing else about the break logic changed — `z.enum([...])` is still the only expression that can genuinely overflow.
+
+Verified for real rather than reasoned about, with prettier and typescript installed into the session scratchpad (neither is on this machine's PATH, so both skip-gated tests skip in an ordinary run):
+
+- `prettier --check` is clean on the `every_type_kind_crate` emission carrying the new `fallback_state` field — the exact multi-member chain break above.
+- `tsc --strict` is clean on a recursive crate whose `Node` carries a nullish concept ref, a nullish list, a nullish enum, a nullish record, a defaulted text field and a required int. Dropping ` | null` from one declared type reproduces the failure the widening exists to prevent: *`Node | null | undefined` is not assignable to `Node | undefined`* on the `z.ZodType<Node>` annotation. The widening is load-bearing, not cosmetic.
+
+**The node round-trip gate keys on two things**, both probed at test time: `node --version` parsed and compared against 22.6 (`--experimental-strip-types`, which is what lets node run the emitted `.ts` directly), and a `zod` package with a readable `package.json` under `npm root -g`, symlinked into a tmp `node_modules`. A tmp `package.json` carrying `{"type": "module"}` silences node's typeless-package reparse warning. Anything missing skips; the two always-on pins carry CI. Note this session ran `npm install -g zod` to make the gate open locally — a machine without it simply skips.
+
+**The wire pin needed one thing the plan did not anticipate.** A concept reference is generated as a *quoted forward ref*, so instantiating the runtime class raises `PydanticUserError: not fully defined` until the classes are rebuilt against a shared namespace. The fixture mirrors what the library manager does on load (`_rebuild_models_with_forward_refs`) rather than working around it, which keeps the pin faithful to the runtime path.
+
+**Mutation-tested.** Reverting `_presence_modifiers` to `.optional()` / bare `.default(…)` reddens both the projection pin and the executable round-trip, the latter with zod's own *"expected record, received null"* on the runtime's own payload — the ledger item's failure, reproduced in this repo.
+
+## Checkpoint — pre-landing review, two stamp defects found and fixed
+
+Reviewing the branch with a real prettier (3.9.6, installed into the session scratchpad — it is not on this machine's PATH, so the skip-gated prettier test never runs here) turned up two ways the emitted `types.ts` was not prettier-stable. Both break the same thing: a consumer's formatter run changes the bytes and `pipelex codegen check` reports an untouched artifact as `[hand-edited]`.
+
+**1. The `.nullable()` widening pushed ordinary defaulted fields past the print width, and only `z.enum` was modelled.** `_break_zod_expr`'s premise — "only `z.enum([...])` can genuinely overflow" — was already wrong and this change made it reachable on the commonest shape: the *field name* and the *default literal* are authored and unbounded, and neither is part of `expr`. Measured on one crate carrying a field named `default_summary_style` defaulting to `"a concise executive summary"`: 75 columns on this branch's merge-base and prettier-clean, 86 columns here and rewritten. `_render_field` detected the overflow and handed it to `_break_zod_expr`, which returned the identical flat string.
+
+Probing prettier across every shape `_zod_type` can produce showed the real rule is simpler than the deferred declared-type case, and keys on **call count, not expression**: two or more calls in the chain and prettier breaks the whole chain (`z` alone on the property line, one call per line); a single call has no chain to break, so it explodes that call's arguments in place. `_break_zod_expr` now splits the expression into its member chain (`_split_member_chain`, on depth-zero dots — every literal in the emitted grammar sits inside a bracket) and renders that rule, keeping the enum-member explosion for a call still too wide after the break. The emission is now byte-identical to prettier's own output for the defaulted `z.string()`, `z.record(…)` + `.nullish()`, `z.number().int()` + `.nullish()`, `z.lazy(…)` + `.nullish()`, `z.array(…)` + `.nullish()`, bare enum, enum + `.nullish()`, and enum + `.nullable().default(…)`.
+
+Two fields were added to `every_type_kind_crate` for it — a defaulted text field and a nested dict — so the **always-on** width guard carries the shape in CI where there is no node. Mutation-tested: restoring the enum-only break reddens `test_emitted_ts_lines_fit_the_print_width` naming both lines.
+
+**2. A dict-valued default was rendered as JSON, which prettier rewrites at any width.** `_format_default_value` was `json.dumps(..., sort_keys=True)`, so a default emitted as `{"alpha": "first"}` while prettier writes `{ alpha: "first" }` — braces padded, and quotes dropped per key from every key that is a plain identifier (a key like `per-reviewer` keeps them). No line-width involvement at all: one dict default anywhere in a crate was enough. This is **pre-existing and independent of this campaign**, and `test_dict_defaults_are_canonical` was actively pinning the JSON bytes. Defaults now render through `_ts_literal` / `_ts_object_key`, the test pins the TypeScript spelling, and `every_type_kind_crate` gained a `quotas` default carrying both key spellings.
+
+**3. An exploded choice list was split on every comma, in every target.** Re-reading the rewritten `_break_zod_expr` turned this up: the member split was `str.split(",")`, so a choice like `"blocked, awaiting the owner"` became two unterminated string literals. Not a formatting difference — the emission stops being TypeScript. The same defect sat in `python_common._split_top_level`, which explodes a `Literal[...]` annotation the same way, so both Python targets emitted unparseable Python on the same input; the Python half also has to walk *both* quote styles, because `escape_py_string` falls back to a single-quoted `repr` for a choice containing a `"`. Both splits now walk the string literals.
+
+The Python half was already well guarded — reverting it reddens the ruff and line-length-stability tests loudly. The TypeScript half was guarded by **nothing**, and that is the lesson: the broken form is a run of *short* lines, so the print-width guard cannot see it, and no always-on test parses the emitted TypeScript (the prettier gate skips in CI and on this machine). `test_an_exploded_choice_keeps_its_own_commas` is the direct assertion that closes it, mutation-tested.
+
+**4. A string carrying a `"` was always emitted double-quoted with escapes, and both formatters normalize it away.** `escape_py_string` deliberately converted repr's single-quoted form to double, and `json.dumps` always double-quotes; but ruff and prettier share one rule — double by default, single only where that **strictly reduces** the escape count — so `"marked \"urgent\""` is rewritten to `'marked "urgent"'` on the consumer's first format run, at any width, in all three targets. Probing ruff and prettier across the mixed, tied and backslash-adjacent cases pinned the rule exactly, and both emitters now implement it; every case round-trips back to the authored value, and the emission is byte-identical to what each formatter produces.
+
+**The same blind spot appeared twice, and it is the thing to carry forward.** For defects 3 and 4 the Python half was caught loudly by the always-on ruff and line-length-stability guards, and the TypeScript half was caught by **nothing** — reverting either TS fix left the suite green. `test_emitted_ts_lines_fit_the_print_width` only measures *width*, and the prettier gate skips both in CI and on any machine without a node toolchain, which is every machine here. So the TypeScript target has no always-on guard on its *content*, only on its line lengths; each TS fix needed a direct byte assertion written for it. Worth a proper fix — a vendored TS parse, or making the prettier gate non-optional in CI — rather than another round of hand-written assertions. Filed as [L-260901-26da36](http://localhost:4747/i/L-260901-26da36).
+
+### One defect found and deliberately deferred
+
+The print-width guard exercises `_render_field` but never `_render_type_field`, because no fixture crate is recursive — so the whole declared-type path is unmeasured. Probing it turned up a real, reachable defect rather than a mere coverage hole: a recursive concept with an ordinary four-choice enum field emits a declared-type line at **118 characters**, prettier rewrites it to the leading-`|` broken form, and the resulting byte change makes `pipelex codegen check` report an untouched file as `[hand-edited]`.
+
+It is **pre-existing and orthogonal to this campaign**: the same line measures 111 characters on this branch's parent commit, so the ` | null` widening makes the overflow easier to reach but does not cause it.
+
+It is not a one-liner, which is why it was not folded in here. Probing prettier 3.9.6 across every shape `_ts_type` can produce: a literal union breaks in three tiers (flat, then break after the `?:`, then leading-`|` one per line); `Record<string, X> | null` and `Array<union> | null` explode the type-argument list; but `Array<atom> | null` and a bare long atom **stay flat past 80**. Those last two are the trap — prettier tolerates them, so the always-on width guard is *stricter* than prettier on this path, and simply adding a recursive fixture to it reddens shapes that are already prettier-clean. A correct fix models the union tiers and the type-argument explosion together, and teaches the guard the same distinction.
+
+Filed as [L-260901-47759d](http://localhost:4747/i/L-260901-47759d) (owner `pipelex`), carrying the repro, the probe matrix and the parent-commit measurement.
+
+## Checkpoint — review round 2, two splitter defects fixed and one deferred
+
+Round 2 ran with no usable PR input: the branch's only review thread was already answered and resolved in round 1, and greptile has not re-reviewed since. The whole round came from the two reviewers run locally against `origin/dev` — cubic and Codex — which is exactly the case they exist for.
+
+**Both fixed defects are the same mistake in two places, and both emit TypeScript that does not parse.** The round-1 fix introduced `_ts_string`, which spells a string single-quoted where that strictly reduces escapes; before it, every string went through `json.dumps` and was always double-quoted. Two new splitters were written in that same commit and neither was taught the new spelling.
+
+1. **`_split_enum_members` walked only `"`.** Raised independently by cubic and Codex. A choice carrying both a `"` and a comma — `'say "hi", then continue'` — is spelled single-quoted and then cut at its own comma into two unterminated literals. *Not* a regression: the round-1 baseline split on every comma, so this input was broken there too. It was admitted under round 2's ship-blocker clause, because the consumer's build breaks rather than merely its stamp, and because the changelog already claimed the split walked the literals.
+
+2. **`_split_member_chain` counted brackets inside literals.** Found in verification; neither bot named it, and it is the round's clean regression. Inside `z.enum([…])` the base depth is 2, so a choice list carrying two net-unmatched closers before a `.` walks the depth to zero mid-literal and cuts the member chain there. Plain enumerated prose does it: `["a) strongly agree with the proposal", "b) agree. with some reservations", "c unsure"]`. **The baseline emitter, on the identical input, emits valid TypeScript** — valid to invalid across round 1, since `_split_member_chain` is entirely new there.
+
+Both now track the enclosing quote before counting anything, which is what `python_common._split_top_level` already did — the Python half was right all along and only the TypeScript half was left behind. Verified with prettier 3.9.6 installed into the session scratchpad: both shapes parse and are prettier-clean, and the skip-gated prettier test passes when run with it on PATH. Mutation-tested: reverting either splitter reddens its own byte assertion *and* the new class invariant.
+
+**The blind spot got a cheap always-on guard at last.** `test_emitted_ts_never_breaks_a_line_inside_a_string_literal` scans each emitted code line and asserts none ends inside an unterminated literal. It needs no node toolchain, so it runs in CI, and it reddens on all three defects of this class rather than on the two that happened to be found — which is the point, since hand-written byte assertions have now missed this class three times. It is a stopgap, not the fix: a real parse or a non-optional prettier gate is still [L-260901-26da36](http://localhost:4747/i/L-260901-26da36). Note the guard skips comment lines deliberately — an authored description may hold an apostrophe, and the first draft failed on `/** The reviewer's answer */`.
+
+### Deferred — `_ts_object_key` bypasses the quote rule
+
+`_ts_object_key` renders a non-identifier object key with `json.dumps` rather than `_ts_string`, so a dict-default key carrying more `"` than `'` is emitted double-quoted with escapes and prettier rewrites it:
+
+```
+- .default({ "marked \"urgent\"": 3 }),
++ .default({ 'marked "urgent"': 3 }),
+```
+
+Reachable — `default_value = { 'marked "urgent"' = 3 }` is legal TOML on a `type = "dict"` field — but narrow: `per-reviewer` and `it's` are both already spelled the way prettier wants. Raised by cubic; Codex reviewed the same diff and did not flag it.
+
+**Deferred under the round-2 bar, deliberately.** It is a stamp instability only — the emission is valid TypeScript — and it is *not* a regression: the round-1 baseline rendered the whole dict as JSON and prettier rewrote both the brace padding and the quote, so round 1 made it strictly narrower and never worse. The fix looks like one word (`json.dumps(text)` → `_ts_string(text)`), which is precisely why it was left alone: the bar exists to stop a converging PR from taking on work that is neither a regression nor a blocker. It should be picked up in the follow-up that closes [L-260901-26da36](http://localhost:4747/i/L-260901-26da36), where a real TS parse would catch the whole family at once.
+
+## Checkpoint — review round 3, one regression fixed
+
+`/review` against `dev` with a real prettier (3.9.6, scratchpad install) found one defect and confirmed one known deferral.
+
+**The chain break exploded an enum's members even when the enum fitted on its own line — a regression this branch introduces.** `_break_zod_expr`'s new member-chain path ran `_explode_enum_call` on any `.enum([…])` in the chain, unconditionally. Prettier does not: once the chain is broken it re-measures each call at its new indent and leaves flat any that fits, and the threshold is exact — probed member by member, `indent + len(call) <= 80` stays on the line, `81` explodes.
+
+The shape that reaches it is ordinary, not contrived: `escalation_severity: z.enum(["low", "medium", "high"]).nullable().default("medium"),` is 86 columns flat, so it breaks; the `.enum([…])` is then 36 columns at indent 4 and prettier folds it straight back. **It is a regression rather than a pre-existing defect**, because `.nullable()` is what pushes the line over: the same field emits 75 columns on this branch's merge-base, stays flat, and is prettier-clean there. Verified both directions by emitting the same crate with the merge-base emitter.
+
+`_render_broken_call` now applies the measurement, `every_type_kind_crate` carries the shape (`escalation_severity`, deliberately just inside the width where `fallback_state` is past it), and `test_a_broken_chain_keeps_a_call_that_fits_on_its_own_line` is the byte assertion. Mutation-tested: restoring the unconditional explode reddens it. The whole fixture emission is prettier-clean for real, and `test_emitted_ts_is_prettier_clean` passes with prettier on PATH rather than skipping.
+
+**The deferred `_ts_object_key` case was re-confirmed and left deferred.** A dict-default key carrying more `"` than `'` is still emitted `{ "marked \"urgent\"": 3 }` and prettier rewrites it to `{ 'marked "urgent"': 3 }`. It remains a stamp instability on valid TypeScript, not a regression, and belongs with [L-260901-26da36](http://localhost:4747/i/L-260901-26da36).
+
+## Checkpoint — review round 4, nothing found, and the round-3 fix verified against real prettier
+
+This pass reviewed the code that landed *after* the previous agent-comment round — the `_render_broken_call` fix and the `origin/dev` merge — which no reviewer had seen. It changed no product code. (It is this branch's fourth review pass but carries the `round=3` stamp on the PR, because one earlier pass was run by `/review` rather than by the agent-comment skill, and only the latter stamps.)
+
+**The PR's own threads contributed nothing again.** The single greptile thread was answered and resolved in round 1, and greptile's "Last reviewed commit" still names a commit several behind the branch head, so there has been no re-review. The whole round came from the two reviewers run locally against `origin/dev`.
+
+**Codex reviewed the branch diff and found nothing.** cubic raised three, none of which clears the bar:
+
+1. **The hand-rolled scanners are duplicated across `ts_zod.py` and `python_common.py`** and cubic would rather see the zod expression kept structural until final rendering. A design concern with no defect behind it, and the same concern already filed as [L-260901-26da36](http://localhost:4747/i/L-260901-26da36) — it belongs there, not in this PR.
+2. **`sorted(pairs)` in `_ts_literal` crashes on a dict default with mixed key types.** Adjudicated as unreachable — the argument is below.
+3. **`_ts_object_key` bypasses `_ts_string`.** The known deferral, re-raised for the third time; unchanged in status.
+
+### `sorted(pairs)` — why the mixed-key crash is unreachable
+
+Recorded in full because cubic is stateless and will raise it again, and a local-only finding has no PR thread to carry its adjudication.
+
+cubic is right on the narrow point: nothing *validates* the key types. `default_value` is typed `Any | None` (`pipelex/core/concepts/concept_structure_blueprint.py:70`) and the `DICT` branch of `_validate_default_value_type` checks only `isinstance(self.default_value, dict)`. So `{1: "a", "b": 2}` would reach `sorted(pairs)` and raise `TypeError: '<' not supported between instances of 'str' and 'int'`.
+
+It cannot get there. Both ingress formats guarantee string keys — a TOML table key is a bare or quoted key, a JSON object key is a string — and `clean_json_content` copies keys through verbatim without coercing them (`pipelex/tools/misc/json_utils.py`: `cleaned[key] = clean_json_content(content_dict[key])`, keys untouched). A dict whose keys are *uniformly* non-string sorts fine and is then handled by `_ts_object_key`; only the mixed case would crash, and no authored bundle can produce it.
+
+Worth naming the inconsistency underneath, since it is what made the finding look reachable: `_ts_object_key`'s docstring says it stringifies a non-string key because "a crash here would be a worse answer than the spelling the emitter has always produced" — and `sorted()`, one line earlier, defeats that promise for the mixed case. That defence is pre-existing and is itself the over-engineering; extending it to satisfy the finding would add a second guard on a state neither guard can be reached in. Left alone deliberately.
+
+### The round-3 fix now has empirical backing, not just a probe record
+
+`_render_broken_call` rests entirely on a claim about prettier's behaviour, and on this machine `test_emitted_ts_is_prettier_clean` skips — prettier is not on PATH — so the claim had never been executed here. Installing prettier 3.9.6 into the session scratchpad and putting it on PATH makes the whole `tests/unit/pipelex/codegen/` suite run with **no skips**: the prettier gate and the node round-trip in `test_ts_zod_wire_agreement.py` both execute (node v24.17.0 and a global `zod` are present on this machine) and all pass.
+
+**Mutation-tested against real prettier.** Restoring the unconditional explode reddens exactly two tests, and the second is the one that matters: `test_emitted_ts_is_prettier_clean` fails with prettier's own *"Code style issues found"* on the emitted `types.ts`, alongside the byte assertion `test_a_broken_chain_keeps_a_call_that_fits_on_its_own_line`. The fix is confirmed by the formatter it models, not only by an assertion written from a probe.
+
+One more reading of the threshold, checked independently rather than taken from the commit message: `indent + len(call) <= TS_PRINT_WIDTH` is exact because the trailing comma never lands on an enum. `_zod_type` emits `.enum([…])` only for a top-level `LITERAL`; a nested one is wrapped, so its member call spells `.array(…)` or `.record(…)` and `_is_enum_call` does not match it. An enum is therefore always the *first* call in a broken chain and never the last one that carries the `,`, so the measured width is the rendered width.