suaveplan/openspec/archive/2026-05-23-enterprise-audience-rules/proposal.md

Migrate @suaveplan/audience-rules

Package: @suaveplan/audience-rules Status: PROPOSED Type: new-package (migration from ../suaveplan/packages/universal/audience-rules/) Design: (none — see specs/audience-rules/spec.md for the normative contract) Spec delta: ./specs/audience-rules/spec.md

Why

Audience segmentation is a universal-tier primitive consumed by every recipient-selection surface (campaigns, broadcasts, deliveries, notifications). Upstream @suaveplan/audience-rules exists at packages/universal/audience-rules/ on main: it ships a working rule evaluator with 14 operators, AND/OR chaining, dot-notation field resolution, three refresh modes, predicate helpers, an InMemorySegmentStore, and an EventEmitter for refresh notifications. It is functionally complete but enterprise-incomplete — EventEmitter is the legacy @suaveplan/events v1 API (genesis uses typed EventBus<TMap>), there is no structured error class, no defineCodes registry, no Zod boundary, and no injectable Clock / IdGenerator (the in-memory store uses new Date() directly and a numeric counter at module scope).

This migration ports the full public surface to genesis under the §0a parity rules and lifts it to enterprise quality: typed EventBus<SegmentRefresherEventMap> from genesis @suaveplan/events, structured AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode> with stable AUDIENCE_RULES.* code registry, Zod boundary validation on every public input, injectable Clock + IdGenerator on the in-memory store, sibling .md per implementation file, explicit-named feature barrels, 100% Istanbul coverage.

What changes

• ADDED: 17 public exports preserved from upstream's src/index.ts — SegmentEvaluator, ContactDataProvider, SegmentRefresher, SegmentStore, InMemorySegmentStore, the seven predicate factories (hasTag, channelIs, statusIs, lastActivityBefore, lastActivityAfter, metadataEquals, metadataContains), and the entity / input / result types (ContactData, Segment, SegmentRule, SegmentOperator, LogicalOp, RefreshMode, SegmentEvaluationResult, CreateSegmentInput, UpdateSegmentInput).
• ADDED: AUDIENCE_RULES_CODES registry via defineCodes("AUDIENCE_RULES", [...]) with stable codes (INVALID_INPUT, SEGMENT_NOT_FOUND, UNKNOWN_OPERATOR, PROVIDER_FAILED).
• ADDED: AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode> with optional segmentId / tenantId discriminants.
• ADDED: Zod schemas for SegmentRule, CreateSegmentInput, UpdateSegmentInput enforced at the public store boundary.
• ADDED: Injectable Clock + IdGenerator on InMemorySegmentStore (defaults: () => Date.now() + a deterministic per-instance counter). new Date() and counter mutation removed from production paths.
• MODIFIED: SegmentRefresher consumes the genesis typed EventBus<SegmentRefresherEventMap> instead of the upstream untyped EventEmitter. The consumer API (on("segment:refreshed", handler)) is preserved verbatim.
• MODIFIED: SegmentEvaluator.applyOperator raises AudienceRulesError with UNKNOWN_OPERATOR for an unrecognised operator (upstream silently returned false). The discriminated SegmentOperator union makes the unknown branch reachable only via a Rule cast — the test exercises this case explicitly.

Parity Checklist

Capability	Upstream	Migrated	Notes
SegmentEvaluator + ContactDataProvider	✅	✅	dot-notation field resolution preserved verbatim
14 comparison operators (eq/neq/gt/gte/lt/lte/contains/not_contains/in/not_in/exists/not_exists/starts_with/ends_with)	✅	✅	switch retained
AND/OR logical chaining	✅	✅	left-to-right; default and
Three refresh modes (realtime/scheduled/manual)	✅	✅	type-only enum preserved
Seven predicate factories	✅	✅	verbatim
SegmentStore interface + InMemorySegmentStore	✅	⬆️	Enhanced: Clock + IdGenerator injection, Zod boundary
SegmentRefresher + event emission	✅	⬆️	Enhanced: typed EventBus<SegmentRefresherEventMap> replaces untyped EventEmitter
Multi-tenant isolation via tenantId	✅	✅	preserved on Segment and store list
Structured error class + code registry	🚫	⬆️	Added: AudienceRulesError + AUDIENCE_RULES_CODES
Zod-validated public boundaries	🚫	⬆️	Added: Zod schemas on store inputs
OTel instrumentation	🚫	🚫	Scoped out: upstream has none and audience-rules is a lightweight evaluator; instrumentation belongs in api-plugin-audience-rules (HTTP layer) where request-level cardinality is meaningful.

Out of scope

• SurrealDB / Postgres store adapters — upstream defers these to a hypothetical api-plugin-audience-rules; genesis matches.
• Scheduled-refresh timer wiring — upstream exposes the scheduled refresh mode as a type only; the timer driver is a consumer responsibility. Genesis matches.
• Real-time push refresh (e.g. CDC-driven re-evaluation) — same reason; consumer responsibility.

Source mapping

Requirement	Source lines	Notes
Public surface (17 exports)	src/index.ts:1-26	verbatim
Segment, SegmentRule, SegmentOperator, LogicalOp, RefreshMode, SegmentEvaluationResult, ContactData, CreateSegmentInput, UpdateSegmentInput types	src/types/segment.types.ts:1-92	verbatim shape
SegmentEvaluator.evaluate + evaluateRule + 14-operator switch + dot-notation resolveField + AND/OR matchesRules	src/core/segment-evaluator/segment-evaluator.ts:1-141	verbatim algorithm
SegmentRefresher.refresh + refreshAll + event emission	src/core/segment-refresher/segment-refresher.ts:1-66	EventEmitter → typed EventBus
SegmentStore + InMemorySegmentStore (6 methods)	src/stores/segment.store.ts:1-90	Enhanced with Clock+IdGenerator + Zod
Seven predicate factories	src/predicates/predicates.ts:1-44	verbatim
Universal-tier purity	upstream package.json (no engines, no browser field)	preserved

Requirements with no source line

Requirement	Justification
AudienceRulesError + AUDIENCE_RULES_CODES registry	Genesis-wide policy: every package raises a typed error.
Zod boundary at the store	Genesis-wide policy: every public input is Zod-validated.
Injectable Clock + IdGenerator	Genesis-wide policy: no Date.now() / new Date() / counter mutation in production paths.
Typed EventBus swap	Genesis @suaveplan/events ships typed EventBus<TMap>; migration must use it.

Verification approach

• src/error-codes/error-codes.test.ts — registry shape, every code constructible, discriminants exposed
• src/segment-evaluator/segment-evaluator.test.ts — every operator, AND/OR chaining, dot-notation resolution, empty-rules / empty-contacts edge cases, unknown-operator raises UNKNOWN_OPERATOR
• src/segment-refresher/segment-refresher.test.ts — refresh, refreshAll, typed event emission, cache update, undefined for unknown segment
• src/store/store.test.ts — every interface method, multi-tenant isolation, Zod validation, Clock + IdGenerator injection
• src/predicates/predicates.test.ts — every factory produces correct rule shape and evaluator matches behave correctly
• src/audience-rules.spec-conformance.test.ts — tier purity, barrel shape, subpath exports, error-code registry, runner-import gate

Impact

Affected dependents

bunx turbo ls --filter=...@suaveplan/audience-rules returns no dependents on genesis (no consumer migrated yet).

• No dependents (verified by bunx turbo ls --filter=...@suaveplan/audience-rules).