feat(email): MJML slot/component composition + interpolation — combined draft (bindings for comment)

[agreenspan]

Update (2026-09-08) — ready for review

Main is merged in (169 commits, four conflicts in the render package resolved), Steven's three open findings are addressed, and the engine is at parity with Zealot's post-July state. Four commits on top of the merge:

1. Merge origin/main — main's reserved {{system.now}}/{{system.year}} tokens ride the settle()-based interpolate as a pre-pass (clock-resolved, non-overridable, before conditionals and substitution); the caller-supplied system bucket stays for rail-provided values (system.unsubscribeUrl). Both prototype-key lookupCascade tests kept.
2. Each lens binds by name from the stage object in hand (findings OpenTelemetry in API #2 and Add FEAT-013 and FEAT-014 tickets, update feature matrix #3) — a registry entry is lenses plus a sender pick: the entity lens binds from the handoff, the sender ids and the recipient where pick off the entity row, cc/bcc off the recipient row. bindLens/bindWhere ask the engine (lensRequiredBindings/requiredBindings) which names a lens needs, assert each is a key of the map, and hand the engine a flat map; a missing name throws, a present null passes through and the where fails closed. The bind side tables (BindSources, EntitySpec, fill, UnresolvedBindError, resolveEntry.ts) are gone. The inquiry entry picks sourceOrganizationId/targetUserId, and the registry invariant test uses the engine's own requiredBindings to pin that every recipient bind and sender id is a field the entity picks.
3. parseBlocks is the single grammar gate, expand is the single guarded walk (finding Claude/refactor polymorphism hook #1, Zealot 5088a1360 / #2112) — parseBlocks throws a typed ParseBlocksError (mismatched_close | stray_close | unclosed_open | invalid_slug | invalid_modifier | duplicate_slot) wherever the grammar is parsed; validateBlocks is folded in and deleted; the whole-body assertNoDuplicateExposedSlots runs at the component save. expand owns the render walk with the override scope chain (a fill renders in the scope that authored it, so a slot re-exposed through a nested component's override still receives the grandparent's fill), the render-time circular_ref guard, one lookup per level and one parse per slug. renderBlocks (a second unguarded copy of the walk) is deleted. expandWith(mjml, lookup) takes the loader so recompose renders pinned snapshots through the same engine. This absorbs feat(email): concentric slot pass-through — fill a slot re-exposed through a nested component #91's first three commits; feat(email): concentric slot pass-through — fill a slot re-exposed through a nested component #91 is now stacked on this as its template-specific remainder.
4. {{#each}} parity with Zealot #1689 post-review — limits.ts (100 elements, depth 2; over either cap the block sinks and renders nothing); validateConditions desugars a leaf's binding-rooted field/path to the absolute path before checkRuleAgainstLens, walks each logical leaf independently, reports unknown binding roots per leaf; whitespace-tolerant rule markers; rules/walkConditionTree + rules/resolveBindingPath. Template keeps four scope roots (sender | recipient | data | system).

Verified: packages/email 347/347; apps/api 1021 pass, 2 fail — the lens count-scope tests that #95 fixes on main. Typecheck clean on db/email/api; biome clean.

Deliberately not ported (Zealot has them, they are follow-ups, not this PR): regions.ts/authoring.ts builder decorations (#1698), mjmlNesting.ts (#2090, needs the editor), preflight/ content checks (#2171), rules/buildEmailRuleLens + componentExpectations (#1655, needs a lens builder on this side), JSON-opacity save warnings (no warnings channel in save yet), EACH_HYDRATION_TAKE (no hydration consumer yet).

Open questions for the architect (from the port):

• validateConditions takes the lens as options.lens rather than Zealot's positional argument, to keep the save callers untouched. No caller passes a lens yet.
• With system as a scope root, a system.unsubscribeUrl rule is lens-checked like any other root, so a future lens builder must model System. Zealot treats system as pre-pass only.
• Zealot also bans {{#each}} in subjects at render time as defense-in-depth; here only the save-time ban exists.
• ParseBlocksError has no HTTP mapping because none of its siblings (MjmlValidationError, ConditionValidationError, DivergentDuplicateSlugError) do either — there is no email save endpoint in this repo yet.

---

What this is

Draft, for comment. Combines the built MJML slot/component render engine with the converged design (COMM-009), the cascade-diff decomposer, and a declarative (bindings-based) registry.

Update (2026-07-06) — the two design pieces are now built + tested

• Cascade-diff decomposer (packages/email/src/render/decompose.ts, pure, 13 tests). Walks the parseBlocks AST; per component ref, partitions caller overrides (kept inline, caller-owned) from the component's own body (chrome + :default slots), diffs the body against an injected cascade resolver → noop/inherit (unchanged) vs write (new/diverged), attributing nested refs by region (ref in a :default → owned by the enclosing component; ref in an override → bubbles to the caller). Replaces mapRefs/resolveVariants variant-indexing — no slug:idx, no fork-suffixing; fork = a new slug (an FE rename). Covers the parent-ships-child-pre-filled nesting regression + child-first write ordering.

• Declarative registry via json-rules bindings (apps/api/src/lib/email/registry.ts). EmailEntry is serializable data — closures gone: entity/recipient where carry {bind} tokens whose names are fields of the stage object that binds them; sender is a typed pick of entity fields; data is the list of handoff fields forwarded to the render scope. (Superseded on 2026-09-10 by item 2 above: the bind side tables that first shipped here are gone.)

• decompose wired into save.ts (collectSlugs + decompose). saveEmailTemplate now decomposes the hydrated payload against the owner cascade: an inlined body equal to the resolved cascade body is a noop/inherit (no write); a divergence (or unknown slug) writes the same slug at the current tier (shadow) — no slug:idx variants, no fork-suffixes. save.test.ts rewritten to the noop/shadow/no-variant model (+ explicit org-shadow coverage). The superseded extractRefs (mapRefs) + resolveVariants modules were removed.

• Fixed a pre-existing enqueue ↔ handlers import cycle (on main, backmerged here). Jobs re-enqueue jobs, so handlers import enqueueJob and the registry imports every handler — enqueue's static registry import closed an eval-time loop that TDZ-threw whenever a single handler module loaded before handlers/index.ts (e.g. a handler's own test). enqueue now lazy-loads the registry at its single call site (JobPayloads stays a static type). This unblocked sendEmail.test.ts, which was previously unrunnable.

• Migrated sendEmail.test.ts to the declarative registry — now 7/7, exercising the bindings resolver end-to-end through the planner + DB.

Verified: full email render suite green + api email units (registry + bind + sendEmail handler). No type errors in touched files.

Built earlier (this branch, render foundation)

• parseBlocks.ts — pure parser for {{#component:slug}} / {{#slot:name}} / {{#slot:name:default}}.
• renderBlocks.ts — recursive render, overrides.get(name) ?? node.children (empty-default-holds-position).
• expand.ts — thin wrapper + per-slug-memoized cascade loader.
• interpolate.ts — deep-path support with a __proto__/prototype/constructor guard + reserved system lens; unsubscribeUrl → system.

Related

• Template: COMM-009 (slots + grammar), COMM-010 (send-governance matrix — storage/validation shipped, enforcement deferred), COMM-011 (multi-lens recipients — backlog).
• Zealot: ZLT-3271 (engine port target) + ZLT-3272 (builder + lens model).
• Builder mockup (converged model): https://claude.ai/code/artifact/62c92778-88b1-4196-b435-6b9847942876

Review pass (2026-09-10)

Aron's review notes, all landed: errors live one-per-file in src/errors/; validators in src/validations/ (validateConditions, validateNoCycle, the stray-tag and duplicate-slot asserts that used to sit inside parseBlocks); settle, conditionParser and validateConditions are folders of one-function files; parseBlocks is only the parser, with node types in render/nodes.ts and tag grammar in render/blockTags.ts; the unused Lens enum is gone (the four roots are SCOPE_ROOTS/ScopeRoot in the grammar and Variables derives from it); expand prefetches through the shared slug walker; the JSON-parse catch is one helper; comment walls cut; saveScopedRow skips tombstones (test); the render-time orphan {{/each}} sink is gone since save-time balance checks already reject it.

Parked until the stack is reviewed: the render error strategy (sink vs throw, the inline-errors env flag, the bare Error in save), the one-template-per-pair ruling into COMM-012.

[stevenolay]

Three inline notes on the open findings: parseBlocks robustness, silent bind resolution, and the inquiry picks binding. Full summary in the top-level comment.

[stevenolay]

stack.pop() closes whatever block is currently open without checking it matches the close tag, so malformed input corrupts the tree silently (no error). Three cases:

• Mismatched close: {{#component:card}}hi{{/slot:x}}tail{{/component:card}}. The {{/slot:x}} pops the card early, so tail and the real close land outside the card.
• Unclosed open: {{#component:card}}body swallows the rest of the document.
• Stray space: {{# component:card }} isn't matched by TAG (no \s), so it stays literal text, but a clean {{/component:card}} still pops a frame that was never pushed.

This got more load-bearing after 2a1f677, since collectSlugs runs parseBlocks on the save path now too, so a malformed tag can corrupt what gets persisted, not just what renders. Suggestion: on pop, assert the top-of-stack kind and name match the close (else throw), and assert an empty stack at the end (unclosed-block error). That turns silent corruption into a save-time validation error.

[stevenolay]

A mis-declared bind path resolves to undefined here, which becomes WHERE <field> = NULL downstream: zero recipients, no email, no error. fill does get(context, path) per bind, so a wrong or renamed or unthreaded path yields undefined, resolveBindings emits null, and an equals recipient where matches no rows.

Good news, and I checked this against json-rules directly: it fails closed (or throws loudly if the bind name is entirely missing), never "match everyone", so no leak, just a dropped send. The gap is that json-rules ships requiredBindings / validateBindNames for exactly this and nothing calls them, and the registry invariant test only asserts bind names are declared, not that they resolve, and only for recipients. A resolve-time requiredBindings assert across entity/sender/recipients/cc/bcc would make a typo'd path fail loudly instead of silently sending to nobody. registry.ts:83 is a live example of how easy this is to hit.

[stevenolay]

This binds entity.sourceOrganizationId, and :84 binds the recipient from entity.targetUserId, but neither field is in the entity picks (['id', 'content', 'sourceOrganization'] on :77).

It resolves today only because fetchLens issues findMany with no select, so the raw row happens to carry every scalar, and sendEmail passes that raw row (not the pruned projection) to the resolvers. Add a select to fetchLens, or switch the resolvers to the pruned entity, and both binds go to undefined, then null: sender organizationId: null and recipient matches nobody, silently (per the resolve-time gap on resolveEntry.ts:20). Either add these two scalars to picks, or pin the raw-row dependency with a comment so a future select doesn't quietly break addressing.

[stevenolay]

Did a full pass over the PR (render pipeline, decomposer, registry/resolver, removed-behavior and security), verifying each finding against the code. The hard parts hold up well: nested-ref attribution, child-first write ordering, and the noop/inherit diff all check out, and the security surface is clean (the __proto__/prototype/constructor guard and the server-only, un-spoofable system lens).

Nice to see a few already resolved by the recent commits:

• The split-brain save path (old indexer wrote, new engine validated) is closed now that decompose is wired into save (2a1f677), and the same-slug shadow model is explicit and tested. Only residual: divergent duplicate bodies under one slug collapse silently to last-wins (bySlug.set), which is fine if the builder guarantees one-slug-one-body per payload, otherwise an optional defensive assert.
• The sendEmail handler test is migrated to the declarative registry (ff98516), so the addressing path has real coverage again.

Three open findings, details inline:

1. parseBlocks silently corrupts structure on malformed tags (parseBlocks.ts:39). Close tags pop the stack without a kind/name match, and it is now load-bearing on the save path via collectSlugs. A balance and kind check turns it into a save-time error.
2. Silent bind failure (resolveEntry.ts:20). A mis-declared path resolves to WHERE = NULL, so no recipients and no error. It fails closed (no leak), but requiredBindings exists and nothing calls it.
3. The inquiry entry binds fields not in its picks (registry.ts:83-84). Works only by luck (raw-row findMany), one select away from silently emailing nobody.

None are blockers and the direction is solid. Context on our side: since ZLT-3271/3272 port these exact modules, we inherit the shadow/last-wins model as-is, and I would want the parseBlocks guard and the bind assert regardless.