Skip to content

0045. Saved audiences: one condition language, dynamic audiences pinned by an expanded copy, and counts by bounded scans

  • Status: Proposed. The event-name cap of 200 (2026-11-20) and deferring audience entry and exit triggers (2026-11-19) are the maintainer’s decisions, Accepted and not reopened.
  • Date: 2026-11-19
  • Amends: ADR 0016 (a trigger’s audience uses this condition language, may reference a saved audience, and may be set on every trigger type; and its snapshot rule: membership is evaluated when the drain reaches each customer, among customers created by the occurrence time), ADR 0023 (deletion also removes the customer’s event summary rows)

The maintainer decided on 2026-11-19 that the first release has saved, reusable audiences. Their scenario: “30 days after sign-up, send this text to this audience; 60 days after, send two texts to audience 2”, measurable afterwards (ADR 0047).

Facts at 6ea2d7a:

  • A condition step tests one attribute (equals, not_equals, exists, not_exists); when it does not hold, the run exits with exited:condition_not_met (core/src/engine/definition.ts, core/src/engine/run.ts).
  • ADR 0016 gives schedule and once triggers an inline audience: <condition>, snapshotted at the occurrence time and drained in bounded batches with a cursor, under a per-occurrence recipient cap. The grammar is not written down.
  • A workflow version is immutable, and a send approval binds its definition hash (ADR 0007, ADR 0033). Rollback can make an earlier version of the current activation epoch live again (ADR 0044).
  • Customers live in the project store (a SQLite Durable Object, or Postgres), with attributes as a JSON document. A DO holds at most 10 GB; profiles are unlimited under fair use (ADR 0010, ADR 0014).

Options considered:

Option For Against
Dynamic audiences only, with an inline customer list predicate for fixed lists (chosen) one model; no membership rows to delete or approve a fixed list of thousands of customers is better as an attribute
Dynamic and static audiences lists without attributes static members widen a live workflow without approval, need a deletion cascade, and a second kind to explain
Versioned audiences, pinned by version small definitions a version table and its lifecycle, for what an expanded copy does
Materialized membership O(1) counts a write per audience per customer change; relative-time conditions change with no write

One grammar, validated with zod when a definition or audience is saved, for trigger audiences, condition steps, goals, saved audiences, and broadcasts (ADR 0049):

condition := { all: [condition, ...] } 1 to 20 items
| { any: [condition, ...] } 1 to 20 items
| { not: condition }
| { attribute | path, operator, value? } attribute predicate
| { event, operator, within? | since? } performed | not_performed
| { inAudience: "aud_…" } a saved audience, expanded at save
| { customers: [externalId, ...] } 1 to 1,000, resolved at save
  • Attribute predicates. attribute is one top-level key, taken literally (it may contain dots); path is an array of 1 to 3 keys for nested values. Operators: equals, not_equals, exists, not_exists, gt, gte, lt, lte, contains (substring of a string, or element of an array), in (up to 100 values), within_last and not_within_last (an ISO 8601 duration such as P30D, for dates).

  • Comparison semantics, defined once in core and tested with mixed types:

    • Values are compared by JSON type. A string that parses as an ISO 8601 date-time with an offset or Z is a date, compared as UTC epoch milliseconds; a date without an offset is a string. Numeric strings are strings.
    • A type mismatch makes equals, gt, gte, lt, lte, contains, in, within_last, and not_within_last false, and not_equals true. A missing attribute makes every operator false except not_exists and not_equals.
    • { not: c } is the negation of c under these rules, so not of a mismatch is true; the docs show this.
  • Event predicates. performed and not_performed, with within (a duration up to P365D) or, in goals only, since: "run_start". They read customer_event_stats(customer_id, event_name, last_at), upserted in the transaction that ingests the event. Only event names that a saved definition or audience references are summarised, at most EVENT_SUMMARY_MAX_NAMES per project (200, the maintainer’s decision of 2026-11-20); saving a condition that would exceed it is a validation error. A row exists only for a (customer, name) pair the customer has actually performed. Event counts and counts within a window are not supported.

  • A newly summarised name fails closed. When a name first becomes summarised, a bounded job backfills its rows from the raw events still in the store’s hot window, and the name records summarised_since: the start of that hot window. An event predicate whose window starts before summarised_since (a within longer than the name’s summarised age, or a since: "run_start" earlier than it) is unknown, and a condition with an unknown predicate anywhere in it is unknown as a whole, whatever not or any surround it. Each use resolves an unknown condition toward sending less:

    • a saved audience or a trigger audience does not select the customer;
    • a condition step does not hold, and the run exits (exited:condition_not_met);
    • a goal that is unknown at the pre-send check skips that send with skipped:condition_unknown, and the run goes on to its next step, where the check runs again; an unknown goal is never counted as a conversion, and an event evaluation that finds it unknown does not exit the run;
    • experiment eligibility at a send step uses the same pre-send check, so an unknown goal skips the customer with skipped:condition_unknown and they are not assigned (ADR 0048).

    So a newly summarised name never causes a send for lack of history, through an audience, a trigger audience, a condition, or a goal: at worst it sends less. The save response, audiences.preview, and the confirmation preview give fullyKnownFrom, the time from which every predicate of the condition is fully known.

  • Customer lists. { customers } is resolved at save: each external ID is replaced by the customer’s internal ID (cus_…), and an unknown ID is a validation error naming its index, not the ID. Definitions, their hashes, and the approval view hold internal IDs only. A deleted customer’s internal ID matches nothing, so versions keep no personal data after a deletion (ADR 0023).

  • No personal data as literals. An attribute predicate whose literal value looks like an email address is a validation error that points to { customers }, so addresses do not end up in definitions, hashes, or approval mail.

  • Limits. At most 5 levels deep and 50 predicates in total after expanding saved audiences. A reference cycle is a validation error.

  • The single-attribute condition step of today stays valid as shorthand.

  • One evaluator. A pure function in core evaluates a condition over one customer row and its event summary, with the clock injected. Condition steps and triggers call it for one customer; counts and occurrences call it for each row of a bounded scan batch. There is no SQL compilation of conditions.

  • An audience belongs to one project: aud_… ID, a name unique in the project, a description, and a condition. There is one kind, dynamic: membership is evaluated when used and never stored.
  • Pinning by expanded copy. When a workflow version is saved, each { inAudience } is expanded: the saved definition keeps { inAudience: "aud_x", conditionHash, condition: <the expanded copy> }. The copy is authoritative at run time; the ID is kept for reports and for audiences.get, which lists the workflows whose latest or live version holds a copy with a different conditionHash, so the AI can offer to update them. conditionHash is SHA-256 over the canonical JSON (RFC 8785) of the expanded condition, after customer lists are resolved to internal IDs. Editing an audience never changes a live workflow.
  • Deletion fails closed. audiences.delete is refused with conflict while the latest version, the live version, or any version a rollback could restore in the current activation epoch (ADR 0044) references the audience. If a version referencing a missing audience is ever about to go live (activation, publishing, rollback), that is refused with conflict and the reason audience_missing. A deleted audience’s ID is never reused.
  • Trigger audience (the field audience on a trigger). Every trigger type may carry one. For schedule and once, it selects who the occurrence reaches, as in ADR 0016. For event and attribute_date, it is checked for the one customer when the trigger fires, and a customer outside it gets no run (skipped:audience_condition_false, ADR 0016’s reason). The run records the saved audience IDs its trigger referenced, for reports (ADR 0047).
  • Condition steps and goals take any condition.
  • The maintainer’s scenario: an event trigger on sign-up, a 30-day delay, a condition { inAudience: "aud_1" }, a send, a 30-day delay, a condition { inAudience: "aud_2" }, and two sends.
  • Snapshot, amended. ADR 0016 says the audience is snapshotted at the occurrence time and customers who match only later are not added. Evaluating every customer against their data as it was at the occurrence would need attribute history, which the store does not keep. So this ADR amends that rule explicitly: the drain considers only customers created at or before the occurrence time (new customers are never added), and evaluates each of them when the cursor reaches them, on their data at that moment. A customer whose attributes change between the occurrence and the drain is judged on the new values. The drain runs in bounded batches right after the occurrence, so the gap is minutes, not days. Eligibility is still rechecked before each send.
  • Triggers on entering or leaving an audience are deferred (maintainer’s decision of 2026-11-19, following the recommendation).

audiences.preview takes a saved audience or an inline condition and answers “how many will this send to?”:

  • matching, eligible (with an address, not unsubscribed, not suppressed), excluded counts by reason (condition_unknown among them, for customers left out because a predicate is unknown, with fullyKnownFrom), up to 10 sample external IDs, countedAt, and exact.
  • A count scans the customers table in primary-key order, AUDIENCE_SCAN_BATCH rows per batch (configuration), and evaluates each row with the one evaluator. A project with at most AUDIENCE_SYNC_COUNT_LIMIT customers is counted within the request (exact: true). A larger one starts a count job driven by tick, which yields between batches, and the call answers status: "counting" with progress; a later call returns the result. Results are cached per conditionHash with countedAt.
  • At most AUDIENCE_MAX_CONCURRENT_COUNTS count jobs run per project (configuration); further requests wait for one to finish and say so.
  • A count is a point-in-time figure. The confirmation of ADR 0050 issues a token only with an exact count.

api actions with full parity (ADR 0005), target: "project", principal: "any" (the rule ADR 0041 set for project actions):

Action Scope, role Annotations
audiences.create, audiences.update write, member idempotent with a client idempotency key
audiences.get, audiences.list, audiences.preview read, member read-only
audiences.delete write, admin destructive
  • Customer deletion also deletes the customer’s customer_event_stats rows in the same transaction (ADR 0023). Conditions never go in logs or queue payloads (ADR 0032).
  • Audiences add no billable unit (ADR 0014). Their limits are configuration, not plan values in code.
  • The scenario is expressible with the built step types plus richer conditions, and is reported per step and audience by ADR 0047.
  • The data a condition reads (attributes, events) is not part of an approval; the condition is. This is the existing rule for attributes, not a new one.
  • Every scan evaluates rows in JavaScript. At the largest tier a count takes many batches; the load test decides whether hot attributes need indexed columns.
  • Open: audience entry and exit triggers; event counts and windows beyond within; conditions on engagement; static lists if inline lists and attributes prove insufficient.