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

[agreenspan]

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 + new resolveEntry.ts, 13 tests). EmailEntry is now serializable data — closures gone: entity/recipient where carry {bind} tokens + a bindings map (each value's context path); sender is a typed spec with bound id fields; data is a path-projection map. Pure resolveEntry fills binds from the ordered context (data → entity → sender → handoff) and calls resolveLensBindings/resolveBindings; the planner (sendEmail) is wired to it. Unlocks the serializable registry COMM-010 deferred + a statically-derivable lens surface.

  • Correction: {bind} ships in the pinned json-rules 2.14.1 (landed 2.11.0), not an unreleased 3.0.0; it resolves as a flat key into a bindings map (the resolver fills paths, json-rules does not path-navigate).

• 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 (113, incl. decompose + save.test.ts DB integration) + 32 api email units (registry + resolveEntry + 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

[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.