DB-backed cache for evaluated audience results.

L1 — audience_segments.cached_at + audience_memberships table.
      A result is fresh if cached_at is within TTL minutes.
      put-cached writes memberships and stamps cached_at + member_count.
      get-cached reads memberships when stamp is fresh, else nil.
      invalidate / invalidate-all clear cached_at and memberships.

L2 — wagoe-cache (Redis / in-memory) can be layered in later.
      The wagoe-cache param is accepted but not yet wired.

HTTP handlers and route definitions for audience management.

Web Pages (mounted under /web/audiences):
  GET    /audiences               — list all segments
  GET    /audiences/builder       — new segment form
  GET    /audiences/builder/:id   — edit existing segment

API Endpoints (mounted under /api/audiences):
  POST   /audiences               — create audience
  PUT    /audiences/:id           — update audience
  DELETE /audiences/:id           — delete audience
  POST   /audiences/preview       — returns count + sample
  POST   /audiences/:id/evaluate  — trigger evaluation
  GET    /audiences/:id/members   — list members

Integrant lifecycle management for the audience module.

Config keys:

:wagoe/audience
  {:db-ctx          (ig/ref :wagoe/db-context)
   :cache-service   (ig/ref :wagoe/cache)
   :user-data-source (ig/ref :wagoe/user-data-source)}

  Returns {:store <IAudienceRepository> :resolver <IAudienceResolver> :cache <IAudienceCache>}

:wagoe/audience-routes
  {:audience-service (ig/ref :wagoe/audience)}

  Returns {:api [...] :web [...]} for composition
  by the HTTP handler.

Database persistence for audience definitions and memberships.

Implements IAudienceRepository using next.jdbc + HoneySQL.

Column layout for audience_segments:
  audience_id  VARCHAR — keyword name (e.g. "premium-users")
  filters      TEXT/JSONB — serialised as JSON
  tags         TEXT/JSONB — serialised as JSON
  composition  TEXT/JSONB — optional, serialised as JSON
  cache_config TEXT/JSONB — optional, serialised as JSON

JSON columns use cheshire for serialisation.  On PostgreSQL the
columns are JSONB; on H2 (tests) they are stored as TEXT — both
are handled by `->json` below.

Load-time registry of audience segment definitions and the `defaudience` macro.

The registry is mutable process state, so it lives in the shell — the audience
core namespaces (compiler, composition, filter, ui) stay pure. Definitions are
registered at namespace load via the `defaudience` macro (validated against the
AudienceDefinition schema) and read at runtime by the audience service.

Evaluation service for audience segments.

Implements IAudienceResolver with a hybrid SQL + predicate pipeline:

  1. Check L1 DB cache (via get-cached-with-ttl when TTL is known).
  2. Load definition from in-process registry, fall back to repository.
  3. Compile definition into {:sql-clauses [...] :predicates [...]}.
  4. If :compose present, resolve composed segments recursively.
  5. Phase 1 — SQL: query user IDs via IUserDataSource.query-users-sql.
  6. Phase 2 — predicates: load-users for candidates, filter in-process.
  7. Build SegmentResult.
  8. Cache result when cache + TTL are configured.
  9. Return result.

FC/IS boundary: this shell namespace is allowed to perform I/O.