FEAT-021: Segments — Zealot Groups ported onto CustomerRef

[agreenspan]

FEAT-021: Segments

Zealot's Groups / FanUsersGroup ported onto the template's CustomerRef. Ticket: tickets/FEAT-021-segments.md (decisions, what shipped, open items).

Shape (after the 2026-09-10 rulings)

• Segment — owner false-polymorphic over ProviderModel (the provider whose customers are segmented, so the owner enum is CustomerRef.providerModel); conditions (required) json-rules tree over a lens rooted at CustomerRef; type static | dynamic says when the rule runs — static is computed once when created or its conditions change, dynamic continuously; reconcile-pause triple (cycle | danglingReference | dynamicReference | evaluationError); soft-delete; audit-enabled.
• SegmentMember — segmentId × customerRefId, written only by reconcile. A hand-picked audience is a static segment whose rule is id in [...]; there is no source column and no member add/remove endpoint.
• ProviderModel grew to User | Organization | Space — CustomerRef.providerUserId / providerOrganizationId, relations, every customer × provider partial unique, registry provider axis, factory deps, includeProvider / provider schema carry all three.
• Lens — segmentLensFor(ownerModel): tenancy bind on the provider FK, customer branches (User / Organization / Space → contacts, tag attachments, received communications), segmentMembers → segment.id with a Segment.id source so "members of segment X" is a picker. A boot probe asserts the membership source stays reachable for every provider branch.
• Hooks — segmentConditions (required on every write, validate against the lens, normalize, refuse self-reference / path-read references / references to segments the owner does not have), segmentMemberOwner (member's customer ref must belong to the owner as provider), segmentReconcile (post-commit enqueue: a segment's own row → reconcileSegment for either type; writes on every other model the lens reaches → per-customer-ref job, dynamic segments only; the model→customer-ref reverse map refuses to boot if the lens reaches a model it cannot map).
• Jobs — reconcileSegment (set-based via toPrisma, superseding per segment, fans out to dynamic dependents), reconcileCustomerRefSegments (hydrate one ref via fetchLens, check() per dynamic segment in dependency order), sweepSegments (cron 04:00 UTC: pause verdicts + dependency-ordered enqueue of dynamic segments).
• App event — segment.membershipChanged → websocket refetch of the member list + per-user meReadManySegmentMemberships refetch.
• Routes — /segment/:id read/update/delete, /segment/:id/segmentMembers list; segments + segmentMemberships read-many on /me, /user/:id, /organization/:id, /space/:id (/v1/user is mounted for the first time; db:user read = self or admin); segments create on /me, /organization/:id, /space/:id. The customer-facing membership shape carries id / name / owner / type / createdAt only — the rule is opaque to members.
• Web — Segments page (owned + member-of) in user, organization and space contexts.

One call to review

Inbound triggers are DB hooks, outbound is the app event. Zealot triggers off app events; the template's row-level event log is AuditLog, and every write goes through the hooked client, so the webhook hook's shape was used. Flipping to app events is a small change (hook body → emits in controllers; handler → job stays).

Validation

• apps/api/src/modules/segment/tests/ — 35 tests: conditions hook (required on both types; user / organization owners validate against their own lens), reference graph, pause verdicts, reconcile (set-based, provider scoping, static computed at save and inert afterwards, hand-picked ids scoped to the owner's customers, user and organization as providers, user-write trigger, contact-write trigger through the owner, cross-provider communications excluded, segment-of-segment in one pass and in dependency order, evaluation-error retry, flip to static keeps members / flip back catches up), routes end to end (customer-facing shape, user-context reads self-only, hand-picked static segment through the API).
• An adversarial review pass ran before the first push; its confirmed findings (sender bind on communicationsReceived, in-memory segment-of-segment row, permanent evaluation-error pause, provider rule leaking through /me/segmentMemberships, unowned references accepted at save) are fixed and pinned by tests.
• bun run typecheck: clean for every workspace except @template/sdk, whose tracked src/client/index.ts imports untracked ../core/*.gen files that exist only in the main checkout as stale artifacts (pre-existing; not touched here). bun run typecheck:fe: clean.
• bun test (api): 1065 pass, 2 pre-existing failures in lensWhere.test.ts (atLeast rules written without a condition, untouched here). db 293, permissions 81, ui 244 pass.
• biome check on every file this branch touches: clean. Repo-wide lint has 134 pre-existing errors in files this branch does not touch.
• CI rules: no-raw-global-assign-in-tests fails on two pre-existing files not touched here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VjP2vYXsVd8AELiHnRvQzK