FEAT-021: Segments — reinstated with business-event triggers and four membership events

[agreenspan]

FEAT-021 segments, reworked as one reviewable PR (the first cut, #100, was reverted on main in 4404a1e), plus the email-lens redesign the segment work forced.

Segments

• Every segment is a rule; type says when it runs. Static is computed at create and on rule change, dynamic continuously. A hand-picked audience is a static id in [...] rule. Members are written only by reconcile.
• Two reconcile rails, one AST. reconcileSegment (set rail, toPrisma over the resolved lens) and reconcileCustomerRefSegments (entity rail, fetchLens + check per segment in dependency order). sweepSegments is the nightly backstop over sound dynamic segments.
• Inbound triggers are business events handled by jobs, never in-transaction hooks. RECONCILE_TRIGGERS maps every model the segment lens reads to its events and a test asserts coverage; customerRef.created, user.updated, tag.deleted, tagAttachment.created/deleted were added to close the map and have handlers but no emitters yet (no write paths in template).
• Outbound is four events, two perspectives, emitted from the diff by publishMembershipChanges whichever rail produced it.
• Degraded, not paused. Rule health is never stored: RuleReference edges (INFRA-030) plus a read-time closure over the owner's graph. Reads carry ruleIssues derived from the row's own included edges; the owner-wide closure runs only when a rule names a live segment.
• One customer reference lens, tenancy by bind. polymorphicIs(model, axis) (packages/db/src/registries/polymorphicIs.ts) reads any false-polymorphic axis — owner, provider, resource, sender — into one condition with an optional bind per kind; customerRefLens (modules/customerRef/lib) is the provider's view of a customer that segments, reach and health consume; tag scoping sits on the relation, not only on the picker source; live, platformOrBound and boundAndLive (packages/db/src/lens/scopes.ts) back both lenses.

The email lens

Built on the segment work because the old email "rule lens" could not be hydrated and render never applied a lens:

• Four lenses, one per scope root (sender, recipient, data, system), no synthetic root, no bridges; every path, token, loop and rule dispatches on its root. emailLens({ sender, recipient, data, narrowing }) takes lenses; registry entries declare their data lens (fieldsLens for ad-hoc fields); the narrowing is read from the template row, falling back to the slug's default-tier row.
• The lens is the row owner's. scopeEmailLens scopes Tag (platform or owned), Segment (owned), Organization and Space (self and, for a Space, its organization) on the model and on the picker source alike. The picker lists every source the lens admits.
• One admission predicate. admitRuleReferences decides for the save-time edge writer, for preflight and for the segment save gate; degraded segments leave the render live set; recipients reach delivery hydrated through the recipient lens; message targeting compiles through the platform recipient lens.
• The variables a template renders with are what the lens exposes. prune applies the lens's data narrowing as well as its picks (a hidden list element is dropped, a hidden to-one becomes null, and the root row itself must be admitted: a foreign sender row is null, so its tokens print nothing) and interpolate projects every slot's variables through its lens before any token or rule reads them, so an unfiltered loop cannot print a foreign tag's name from supplied variables; the planner's pruned recipient carries the same boundary into delivery.
• A loop reads only its lens. A rule under {{#each}} is the array rule the lens judges and evaluates (scopedRule): binding leaves element-relative, root leaves climbing with $$ (json-rules 2.24 scope refs), an element-relative path as $.. A leaf naming another lens's root, the element itself, or an index used as a path is an issue at save, render and reference extraction, never a raw check; a loop iterates only what the narrowing's where admits; a loop over the opaque data bag stays as written.
• Hooks rely on the polymorphism machinery (immutable axis and keys, rules hook per polymorphic model registered first); no service takes a db parameter; RuleDegradedError/RuleEvaluationError (shared), validateRuleForLens and ruleHealthFromEdges (db) are generic; segment validators live in modules/segment/validations; admin body schemas are picks off the template input schema; makeAppEvent runs its tasks through db.parallel.

Known gaps (tracked in tickets/FEAT-021-segments.md)

The five reconcile events (customerRef.created, user.updated, tag.deleted, tagAttachment.created/deleted) have handlers and tests but no emitters: template has no tag module, tag attachment write path, user update route or customer reference provisioning yet, so these are integration obligations for those features, not broken current behaviour; the rules hook still skips AuditLog until COMM-014 removes the audit hook's dead hard-delete branch.

Verification

Tested at 6a7395f4: bun run check (lint, typecheck, every suite, CI rules), the isolated segmentRoutes.test.ts run, and the adversarial probes on polymorphicIs, scopedRule and admission.

🤖 Generated with Claude Code