@hogsend/engine 0.46.1 → 0.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/connectors/presets/index.ts +8 -2
  4. package/src/container.ts +149 -7
  5. package/src/destinations/presets/posthog.ts +7 -0
  6. package/src/destinations/presets/segment.ts +5 -0
  7. package/src/env.ts +38 -0
  8. package/src/flags/reconcile.ts +195 -0
  9. package/src/index.ts +79 -0
  10. package/src/journeys/authoring.ts +32 -0
  11. package/src/journeys/define-journey.ts +45 -40
  12. package/src/journeys/execute-journey-run.ts +73 -32
  13. package/src/journeys/journey-boundary.ts +76 -0
  14. package/src/journeys/journey-context.ts +128 -70
  15. package/src/journeys/journey-task-factory.ts +31 -0
  16. package/src/journeys/journey-task-runtime.ts +31 -0
  17. package/src/journeys/journey-version.test.ts +236 -0
  18. package/src/journeys/journey-version.ts +158 -0
  19. package/src/journeys/record-once.ts +28 -2
  20. package/src/lib/connector-actions.test.ts +36 -0
  21. package/src/lib/connector-actions.ts +42 -4
  22. package/src/lib/contacts.ts +49 -0
  23. package/src/lib/conversions.test.ts +33 -0
  24. package/src/lib/conversions.ts +8 -0
  25. package/src/lib/email.ts +23 -2
  26. package/src/lib/enrollment-policy.ts +51 -0
  27. package/src/lib/feed.ts +55 -3
  28. package/src/lib/flags-registry.ts +48 -0
  29. package/src/lib/flags.ts +498 -0
  30. package/src/lib/fx.ts +374 -0
  31. package/src/lib/global-control-readout.ts +166 -0
  32. package/src/lib/groups.ts +362 -0
  33. package/src/lib/ingestion.ts +38 -0
  34. package/src/lib/journey-lift.ts +142 -0
  35. package/src/lib/operator-settings.ts +71 -0
  36. package/src/lib/outbound.ts +147 -0
  37. package/src/lib/preferences.ts +6 -80
  38. package/src/lib/recipient-preferences.ts +53 -0
  39. package/src/lib/sms.ts +21 -2
  40. package/src/lib/stable-stringify.test.ts +42 -0
  41. package/src/lib/stable-stringify.ts +23 -0
  42. package/src/lib/variant.ts +99 -0
  43. package/src/lib/webhook-signing.ts +16 -1
  44. package/src/lists/registry.ts +6 -2
  45. package/src/lists/subscription.ts +13 -0
  46. package/src/routes/admin/contacts.ts +53 -4
  47. package/src/routes/admin/conversions.ts +137 -0
  48. package/src/routes/admin/flags.ts +369 -0
  49. package/src/routes/admin/groups.ts +866 -0
  50. package/src/routes/admin/impact-schemas.ts +44 -0
  51. package/src/routes/admin/impact-wire.test.ts +181 -0
  52. package/src/routes/admin/impact.ts +486 -0
  53. package/src/routes/admin/index.ts +12 -0
  54. package/src/routes/admin/journey-impact.ts +446 -0
  55. package/src/routes/admin/journeys.ts +70 -100
  56. package/src/routes/admin/settings.ts +145 -0
  57. package/src/routes/admin/targeting.ts +256 -0
  58. package/src/routes/events/index.ts +11 -0
  59. package/src/routes/flags/index.ts +120 -0
  60. package/src/routes/groups/index.ts +417 -0
  61. package/src/routes/index.ts +23 -1
  62. package/src/testing.ts +25 -0
  63. package/src/webhook-sources/presets/index.ts +5 -1
  64. package/src/webhook-sources/presets/intercom.ts +230 -0
  65. package/src/webhook-sources/presets/segment.ts +56 -4
  66. package/src/worker.ts +3 -0
  67. package/src/workflows/bucket-backfill.ts +1 -14
  68. package/src/workflows/impact-digest.ts +761 -0
  69. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
package/src/lib/fx.ts ADDED
@@ -0,0 +1,374 @@
1
+ import type { FxRateProvider, FxRateSheet } from "@hogsend/core";
2
+ import { defineFxRateProvider } from "@hogsend/core";
3
+ import type { Database } from "@hogsend/db";
4
+ import { fxRates } from "@hogsend/db";
5
+ import { eq, sql } from "drizzle-orm";
6
+ import type { env as envSchema } from "../env.js";
7
+ import type { Logger } from "./logger.js";
8
+
9
+ /**
10
+ * The base-currency FX lens (docs/groups.md §Base-currency lens) — an OPT-IN
11
+ * converted VIEW layered on top of the revenue spine's per-currency truth.
12
+ * The law (`lib/revenue.ts`) is untouched: currencies are never summed
13
+ * together; the lens converts each per-currency total through an operator-
14
+ * sanctioned quote→base rate and sums the CONVERSIONS. Off by default — the
15
+ * effective base resolves per call (Studio operator setting → env
16
+ * `BASE_CURRENCY`; see the container's resolver); when neither is set the
17
+ * lens resolves null everywhere and nothing changes.
18
+ *
19
+ * Two shipped presets, mirroring how analytics builds from env
20
+ * (`analyticsProvidersFromEnv`), except there is deliberately NO registry:
21
+ * exactly one rate source is resolved at boot (lean-first — multiple
22
+ * simultaneous FX sources have no use case). A consumer-supplied provider
23
+ * (`fx.provider`) wins over both presets.
24
+ *
25
+ * - `static` (the DEFAULT) — sovereign, zero network: the operator supplies
26
+ * the rates (`FX_RATES` JSON) and optionally their date (`FX_RATES_AS_OF`).
27
+ * - `frankfurter` (OPT-IN via `FX_PROVIDER=frankfurter`) — ECB daily
28
+ * reference rates, cached in `fx_rates` so conversions are pinned to a
29
+ * recorded sheet and the API is hit at most once per staleness window.
30
+ */
31
+
32
+ /** How long a fetched sheet serves before the network source is re-asked. */
33
+ const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
34
+
35
+ // ---------------------------------------------------------------------------
36
+ // Static preset (the default — operator-supplied rates, zero network)
37
+ // ---------------------------------------------------------------------------
38
+
39
+ /**
40
+ * Parse the `FX_RATES` env JSON into a quote→rate map. THROWS on anything
41
+ * malformed (bad JSON, non-object, non-finite or non-positive rates) — a
42
+ * typo'd rate sheet must fail the boot loudly, never silently convert money
43
+ * wrong (the same fail-loud posture as an unresolvable `EMAIL_PROVIDER`).
44
+ * Keys are uppercased so lookups never miss on case.
45
+ */
46
+ export function parseFxRatesEnv(raw: string): Record<string, number> {
47
+ let parsed: unknown;
48
+ try {
49
+ parsed = JSON.parse(raw);
50
+ } catch {
51
+ throw new Error(
52
+ 'FX_RATES is not valid JSON — expected e.g. {"JPY":0.0065,"GBP":1.27}',
53
+ );
54
+ }
55
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
56
+ throw new Error(
57
+ 'FX_RATES must be a JSON object of quote→base rates, e.g. {"JPY":0.0065}',
58
+ );
59
+ }
60
+ const rates: Record<string, number> = {};
61
+ for (const [code, rate] of Object.entries(parsed)) {
62
+ if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0) {
63
+ throw new Error(
64
+ `FX_RATES["${code}"] must be a positive number (got ${JSON.stringify(rate)})`,
65
+ );
66
+ }
67
+ rates[code.toUpperCase()] = rate;
68
+ }
69
+ return rates;
70
+ }
71
+
72
+ /**
73
+ * The sovereign default rate source: a fixed operator-supplied sheet, which
74
+ * is exactly the sovereignty trade: no network, no drift, rates change only
75
+ * when the operator changes them.
76
+ *
77
+ * THE HONESTY RULE: a static sheet is only meaningful against the ONE base
78
+ * it was quoted in (`quotedBase` — the env `BASE_CURRENCY` the operator's
79
+ * `FX_RATES` were written for). `getRates(base)` serves the sheet ONLY when
80
+ * `base === quotedBase` and resolves null for any other base — a USD-quoted
81
+ * sheet must never silently convert into EUR just because the effective base
82
+ * changed (e.g. via the Studio setting). A `quotedBase` of null (FX_RATES
83
+ * with no BASE_CURRENCY) is a base-less sheet: it serves null for EVERY
84
+ * base — inert, warned at boot in {@link fxProviderFromEnv}.
85
+ */
86
+ export function createStaticFxProvider(opts: {
87
+ rates: Record<string, number>;
88
+ asOf?: string | null;
89
+ /** The base the sheet's rates are quoted against (null = base-less/inert). */
90
+ quotedBase: string | null;
91
+ }): FxRateProvider {
92
+ const rates = Object.fromEntries(
93
+ Object.entries(opts.rates).map(([code, rate]) => [
94
+ code.toUpperCase(),
95
+ rate,
96
+ ]),
97
+ );
98
+ const asOf = opts.asOf ?? null;
99
+ const quotedBase = opts.quotedBase?.toUpperCase() ?? null;
100
+ return defineFxRateProvider({
101
+ meta: {
102
+ id: "static",
103
+ name: "Static (operator-supplied rates)",
104
+ },
105
+ async getRates(base) {
106
+ if (!quotedBase || base.toUpperCase() !== quotedBase) return null;
107
+ return { rates: { ...rates }, asOf };
108
+ },
109
+ });
110
+ }
111
+
112
+ // ---------------------------------------------------------------------------
113
+ // Frankfurter preset (opt-in — ECB daily reference rates, DB-cached)
114
+ // ---------------------------------------------------------------------------
115
+
116
+ /** The subset of Frankfurter's `/latest` response the provider reads. */
117
+ interface FrankfurterLatest {
118
+ date?: string;
119
+ rates?: Record<string, unknown>;
120
+ }
121
+
122
+ /**
123
+ * ECB daily reference rates via frankfurter.app, opt-in
124
+ * (`FX_PROVIDER=frankfurter`). ONE request serves every quote:
125
+ * `latest?from=<base>` returns base→quote rates (1 base = N quote) for all
126
+ * supported currencies, which we INVERT (quote→base = 1/N) — there is no
127
+ * `latest?to=<base>` batch form.
128
+ *
129
+ * Every successful fetch is upserted into `fx_rates`, and the cache is
130
+ * authoritative until it goes stale, so the API sees at most one call per
131
+ * staleness window and a day's conversions are pinned to one recorded sheet.
132
+ * Staleness is measured from `fetched_at`, NOT `as_of`: the ECB reference
133
+ * date legitimately freezes over weekends/holidays, so keying the refetch off
134
+ * `as_of` would re-hit the API on every request all weekend for rates that
135
+ * cannot have changed.
136
+ *
137
+ * FAIL-SOFT throughout: a failed/malformed fetch serves the last cached sheet
138
+ * when one exists, else resolves null. Nothing here ever throws into a
139
+ * request path.
140
+ */
141
+ export function createFrankfurterFxProvider(opts: {
142
+ db: Database;
143
+ logger?: Logger;
144
+ /** Test seam — injected fetch. Defaults to the global. */
145
+ fetchImpl?: typeof fetch;
146
+ /** Refetch window in ms. Defaults to 24h (ECB publishes daily). */
147
+ maxAgeMs?: number;
148
+ }): FxRateProvider {
149
+ const fetchImpl = opts.fetchImpl ?? fetch;
150
+ const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
151
+
152
+ const sheetFromRows = (
153
+ rows: (typeof fxRates.$inferSelect)[],
154
+ ): FxRateSheet => ({
155
+ rates: Object.fromEntries(rows.map((r) => [r.quote, Number(r.rate)])),
156
+ // Rows are upserted as one batch, but be defensive: label the sheet with
157
+ // the newest date present.
158
+ asOf: rows.reduce<string | null>(
159
+ (max, r) => (max === null || r.asOf > max ? r.asOf : max),
160
+ null,
161
+ ),
162
+ });
163
+
164
+ return defineFxRateProvider({
165
+ meta: {
166
+ id: "frankfurter",
167
+ name: "Frankfurter (ECB daily reference rates)",
168
+ },
169
+ async getRates(base) {
170
+ const baseCode = base.toUpperCase();
171
+ let cached: (typeof fxRates.$inferSelect)[] = [];
172
+ try {
173
+ cached = await opts.db
174
+ .select()
175
+ .from(fxRates)
176
+ .where(eq(fxRates.base, baseCode));
177
+
178
+ const newestFetch = cached.reduce<number>(
179
+ (max, r) => Math.max(max, r.fetchedAt.getTime()),
180
+ 0,
181
+ );
182
+ if (cached.length > 0 && Date.now() - newestFetch < maxAgeMs) {
183
+ return sheetFromRows(cached);
184
+ }
185
+
186
+ const res = await fetchImpl(
187
+ `https://api.frankfurter.app/latest?from=${encodeURIComponent(baseCode)}`,
188
+ );
189
+ if (!res.ok) {
190
+ throw new Error(`frankfurter responded ${res.status}`);
191
+ }
192
+ const body = (await res.json()) as FrankfurterLatest;
193
+ const asOf = body.date;
194
+ // 1 base = N quote on the wire; the lens wants quote→base, so 1/N.
195
+ const entries = Object.entries(body.rates ?? {}).filter(
196
+ (pair): pair is [string, number] =>
197
+ typeof pair[1] === "number" &&
198
+ Number.isFinite(pair[1]) &&
199
+ pair[1] > 0,
200
+ );
201
+ if (!asOf || entries.length === 0) {
202
+ throw new Error("frankfurter returned no usable rates");
203
+ }
204
+ const fetchedAt = new Date();
205
+ const rows = entries.map(([quote, perBase]) => ({
206
+ base: baseCode,
207
+ quote: quote.toUpperCase(),
208
+ rate: 1 / perBase,
209
+ asOf,
210
+ fetchedAt,
211
+ }));
212
+ await opts.db
213
+ .insert(fxRates)
214
+ .values(rows)
215
+ .onConflictDoUpdate({
216
+ target: [fxRates.base, fxRates.quote],
217
+ set: {
218
+ rate: sql`excluded.rate`,
219
+ asOf: sql`excluded.as_of`,
220
+ fetchedAt: sql`excluded.fetched_at`,
221
+ },
222
+ });
223
+ return {
224
+ rates: Object.fromEntries(rows.map((r) => [r.quote, r.rate])),
225
+ asOf,
226
+ };
227
+ } catch (error) {
228
+ // Fail-soft: a stale sheet labeled with its true asOf beats no sheet;
229
+ // no sheet beats an invented one. Never throw into a request path.
230
+ opts.logger?.warn(
231
+ `frankfurter FX rates unavailable${
232
+ cached.length > 0 ? " — serving the last cached sheet" : ""
233
+ }`,
234
+ { error: error instanceof Error ? error.message : String(error) },
235
+ );
236
+ return cached.length > 0 ? sheetFromRows(cached) : null;
237
+ }
238
+ },
239
+ });
240
+ }
241
+
242
+ // ---------------------------------------------------------------------------
243
+ // Env resolution + the lens (what the container holds)
244
+ // ---------------------------------------------------------------------------
245
+
246
+ /**
247
+ * Resolve the ONE env-configured rate source, mirroring the env-preset spirit
248
+ * of `analyticsProvidersFromEnv` without the registry: `FX_PROVIDER=
249
+ * frankfurter` opts into the network source; otherwise a set `FX_RATES`
250
+ * builds the sovereign static sheet (throwing at boot on a malformed one);
251
+ * otherwise there is no source. A consumer `fx.provider` wins over this
252
+ * entirely (checked at the container call site).
253
+ */
254
+ export function fxProviderFromEnv(
255
+ env: typeof envSchema,
256
+ deps: { db: Database; logger?: Logger },
257
+ ): FxRateProvider | undefined {
258
+ if (env.FX_PROVIDER === "frankfurter") {
259
+ return createFrankfurterFxProvider({ db: deps.db, logger: deps.logger });
260
+ }
261
+ if (env.FX_RATES) {
262
+ if (!env.BASE_CURRENCY) {
263
+ // Called once at boot per container, so this warns ONCE: a sheet with
264
+ // no quoted base is inert (serves null for every base — even one later
265
+ // chosen in Studio), because we cannot know which base its rates were
266
+ // written for. Warned rather than thrown: the deploy still boots and
267
+ // the per-currency truth serves unchanged.
268
+ deps.logger?.warn(
269
+ "FX_RATES is set but BASE_CURRENCY is not — the static rate sheet has no quoted base and is INERT (no conversions will be served, even if a base currency is chosen in Studio). Set BASE_CURRENCY to the currency FX_RATES is quoted against.",
270
+ );
271
+ }
272
+ return createStaticFxProvider({
273
+ rates: parseFxRatesEnv(env.FX_RATES),
274
+ asOf: env.FX_RATES_AS_OF ?? null,
275
+ quotedBase: env.BASE_CURRENCY ?? null,
276
+ });
277
+ }
278
+ return undefined;
279
+ }
280
+
281
+ /**
282
+ * A resolved quote→base sheet, normalized for consumers: keys uppercased,
283
+ * non-usable rates dropped, and the identity rate (base→base = 1) injected so
284
+ * no reader special-cases the base currency. Carries the base it converts TO
285
+ * — a sheet is only meaningful relative to its base, so readers never have to
286
+ * pair it back up with the lens.
287
+ */
288
+ export interface FxRatesToBase {
289
+ baseCurrency: string;
290
+ rates: Record<string, number>;
291
+ asOf: string | null;
292
+ }
293
+
294
+ /**
295
+ * The minimal FX surface the container exposes (`client.fx`). The effective
296
+ * base currency is resolved PER CALL (never boot-frozen): the container's
297
+ * resolver walks code pin → Studio operator setting → env `BASE_CURRENCY`,
298
+ * so a base chosen/changed/cleared in Studio takes effect on the next
299
+ * request without a reboot. Null base = the lens is OFF: `getRatesToBase`
300
+ * resolves null and every consumer renders the unconverted truth, unchanged.
301
+ */
302
+ export interface FxLens {
303
+ /** The active rate source's id (`meta.id`), or null when none is wired. */
304
+ providerId: string | null;
305
+ /**
306
+ * Resolve the operator's EFFECTIVE reporting currency (uppercased), or
307
+ * null when the lens is off. Fail-soft: a throwing resolver reads as off.
308
+ */
309
+ getBaseCurrency(): Promise<string | null>;
310
+ /**
311
+ * Resolve the quote→base sheet from the active provider. Null when the
312
+ * lens is off, no provider is configured, or the provider has nothing to
313
+ * serve. NEVER throws — the lens is the fail-soft chokepoint even for a
314
+ * misbehaving BYO provider, so no request path needs its own guard.
315
+ */
316
+ getRatesToBase(): Promise<FxRatesToBase | null>;
317
+ }
318
+
319
+ /** Build the container's {@link FxLens} from the base resolver + provider. */
320
+ export function createFxLens(opts: {
321
+ /**
322
+ * Resolves the effective base per call (the container builds it from the
323
+ * code pin / operator setting / env precedence). Null = lens off.
324
+ */
325
+ resolveBaseCurrency: () => Promise<string | null>;
326
+ provider?: FxRateProvider;
327
+ logger: Logger;
328
+ }): FxLens {
329
+ const provider = opts.provider;
330
+ const resolveBase = async (): Promise<string | null> => {
331
+ try {
332
+ const base = await opts.resolveBaseCurrency();
333
+ return base ? base.toUpperCase() : null;
334
+ } catch (error) {
335
+ // Same fail-soft posture as a misbehaving provider below: a resolver
336
+ // that throws (e.g. a DB blip reading the operator setting) degrades
337
+ // to lens-off for this request, never into a thrown request path.
338
+ opts.logger.warn(
339
+ "FX base-currency resolution threw — the base-currency lens is off for this request",
340
+ { error: error instanceof Error ? error.message : String(error) },
341
+ );
342
+ return null;
343
+ }
344
+ };
345
+ return {
346
+ providerId: provider?.meta.id ?? null,
347
+ getBaseCurrency: resolveBase,
348
+ async getRatesToBase() {
349
+ const baseCurrency = await resolveBase();
350
+ if (!baseCurrency || !provider) return null;
351
+ try {
352
+ const sheet = await provider.getRates(baseCurrency);
353
+ if (!sheet) return null;
354
+ const rates: Record<string, number> = {};
355
+ for (const [code, rate] of Object.entries(sheet.rates)) {
356
+ if (typeof rate === "number" && Number.isFinite(rate) && rate > 0) {
357
+ rates[code.toUpperCase()] = rate;
358
+ }
359
+ }
360
+ rates[baseCurrency] = 1;
361
+ return { baseCurrency, rates, asOf: sheet.asOf ?? null };
362
+ } catch (error) {
363
+ // The provider contract says "never throw", but the lens holds the
364
+ // line for providers that do anyway: converted figures degrade to
365
+ // absent; the per-currency truth is always still served.
366
+ opts.logger.warn(
367
+ `FX provider "${provider.meta.id}" threw resolving rates — the base-currency lens is off for this request`,
368
+ { error: error instanceof Error ? error.message : String(error) },
369
+ );
370
+ return null;
371
+ }
372
+ },
373
+ };
374
+ }
@@ -0,0 +1,166 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { sql } from "drizzle-orm";
3
+ import { globalControlPercent, isGlobalControl } from "./holdout.js";
4
+ import { computeLift, type LiftVerdict } from "./lift-stats.js";
5
+
6
+ /**
7
+ * Program-level global-control readout (impact-experiments spec D4.5e).
8
+ * Assignment lives only in env + hash (no assignment table), so the
9
+ * readout recomputes membership per contact as
10
+ * key = externalId ?? anonymousId ?? id, which is what
11
+ * isGlobalControl(options.userId ?? options.to) hashes at send time
12
+ * (lib/tracked.ts:245-246, lib/sms-tracked.ts:225-226) for JOURNEY sends —
13
+ * a journey's `userId` is the ingest-resolved key
14
+ * (event.userId ?? event.anonymousId, lib/ingestion.ts), so an
15
+ * anonymous-triggered journey hashes the same anonymousId the readout
16
+ * falls back to.
17
+ *
18
+ * DISCLOSED APPROXIMATION: two OTHER send paths resolve a different key and
19
+ * can disagree with the readout for a contact whose external_id is NULL but
20
+ * anonymous_id is set (the readout hashes anonymous_id; these paths hash the
21
+ * contact's UUID instead, never anonymous_id):
22
+ * - bare POST /v1/emails — regardless of whether the caller supplied a
23
+ * userId, the route always resolves the send's userId as
24
+ * recipient.externalId ?? recipient.contactId (routes/emails/index.ts),
25
+ * so it can never fall through to anonymous_id.
26
+ * - list-audience campaign broadcasts — the send-campaign cursor query
27
+ * resolves the same externalId ?? contactId fallback
28
+ * (workflows/send-campaign.ts), also never anonymous_id.
29
+ * Journey sends stay in parity with the readout (see above); the
30
+ * divergence is bounded to these two paths, so the fallback chain remains
31
+ * a reasonable, disclosed approximation for a mixed-population program —
32
+ * not a blanket "no userId" case.
33
+ *
34
+ * Converter outcomes aggregate ALL definitions (global control suppresses
35
+ * all non-transactional sends, so any registered conversion is a fair
36
+ * program-level outcome; no definitionId knob in v1). ITT caveat: this is
37
+ * a cross-sectional randomized comparison — outcome window
38
+ * occurred_at >= since for BOTH buckets; random assignment keeps it
39
+ * causal, window symmetry keeps it fair.
40
+ */
41
+
42
+ /** In-request scan ceiling — above this the readout reports `skipped`
43
+ * (honest ceiling; a cached cron materialization is explicitly deferred). */
44
+ export const GLOBAL_CONTROL_SCAN_CEILING = 500_000;
45
+
46
+ const DEFAULT_BATCH_SIZE = 5_000;
47
+
48
+ type ContactPageRow = {
49
+ id: string;
50
+ external_id: string | null;
51
+ anonymous_id: string | null;
52
+ };
53
+
54
+ /**
55
+ * Fetches one keyset-paginated page of live contacts. Extracted to a
56
+ * top-level function (rather than inlined in the pagination loop) with an
57
+ * explicit return type — TS's control-flow narrowing of `cursor` across
58
+ * loop iterations otherwise creates a self-referential inference cycle
59
+ * (`pageQuery` → `page` → `rows` → next-iteration `cursor` → `pageQuery`)
60
+ * that surfaces as a spurious implicit-any (TS7022) when inlined.
61
+ */
62
+ async function fetchContactPage(
63
+ db: Database,
64
+ cursor: string | null,
65
+ batchSize: number,
66
+ ): Promise<ContactPageRow[]> {
67
+ const pageQuery =
68
+ cursor === null
69
+ ? sql`select id, external_id, anonymous_id from contacts
70
+ where deleted_at is null
71
+ order by id asc limit ${batchSize}`
72
+ : sql`select id, external_id, anonymous_id from contacts
73
+ where deleted_at is null and id > ${cursor}::uuid
74
+ order by id asc limit ${batchSize}`;
75
+ const page = await db.execute<ContactPageRow>(pageQuery);
76
+ return [...page];
77
+ }
78
+
79
+ export type GlobalControlReadout =
80
+ | { state: "off" }
81
+ | {
82
+ state: "skipped";
83
+ reason: "too_many_contacts";
84
+ percent: number;
85
+ contactCount: number;
86
+ }
87
+ | ({
88
+ state: "computed";
89
+ causal: true;
90
+ percent: number;
91
+ contactsScanned: number;
92
+ treatment: { contacts: number; converters: number; rate: number };
93
+ control: { contacts: number; converters: number; rate: number };
94
+ } & LiftVerdict);
95
+
96
+ export async function computeGlobalControlReadout(opts: {
97
+ db: Database;
98
+ since: Date;
99
+ /** Scan ceiling override — the route always uses the default; the
100
+ * parameter exists so the skipped state is testable. */
101
+ scanCeiling?: number;
102
+ batchSize?: number;
103
+ }): Promise<GlobalControlReadout> {
104
+ const percent = globalControlPercent();
105
+ if (percent === 0) return { state: "off" };
106
+
107
+ const ceiling = opts.scanCeiling ?? GLOBAL_CONTROL_SCAN_CEILING;
108
+ const batchSize = opts.batchSize ?? DEFAULT_BATCH_SIZE;
109
+ const sinceTs = sql`${opts.since.toISOString()}::timestamptz`;
110
+
111
+ const countRows = await opts.db.execute<{ count: number }>(
112
+ sql`select count(*)::int as count
113
+ from contacts where deleted_at is null`,
114
+ );
115
+ const contactCount = Number([...countRows][0]?.count ?? 0);
116
+ if (contactCount > ceiling) {
117
+ return {
118
+ state: "skipped",
119
+ reason: "too_many_contacts",
120
+ percent,
121
+ contactCount,
122
+ };
123
+ }
124
+
125
+ const converterRows = await opts.db.execute<{ contact_id: string }>(
126
+ sql`select distinct contact_id from conversions
127
+ where occurred_at >= ${sinceTs}`,
128
+ );
129
+ const converterSet = new Set([...converterRows].map((r) => r.contact_id));
130
+
131
+ let cursor: string | null = null;
132
+ let scanned = 0;
133
+ const treatment = { contacts: 0, converters: 0 };
134
+ const control = { contacts: 0, converters: 0 };
135
+ while (true) {
136
+ const rows = await fetchContactPage(opts.db, cursor, batchSize);
137
+ if (rows.length === 0) break;
138
+ for (const row of rows) {
139
+ const key = row.external_id ?? row.anonymous_id ?? row.id;
140
+ const bucket = isGlobalControl(key) ? control : treatment;
141
+ bucket.contacts += 1;
142
+ if (converterSet.has(row.id)) bucket.converters += 1;
143
+ }
144
+ scanned += rows.length;
145
+ cursor = rows[rows.length - 1]?.id ?? null;
146
+ if (rows.length < batchSize) break;
147
+ }
148
+
149
+ const verdict = computeLift({ treatment, control });
150
+ return {
151
+ state: "computed",
152
+ causal: true,
153
+ percent,
154
+ contactsScanned: scanned,
155
+ treatment: {
156
+ ...treatment,
157
+ rate:
158
+ treatment.contacts > 0 ? treatment.converters / treatment.contacts : 0,
159
+ },
160
+ control: {
161
+ ...control,
162
+ rate: control.contacts > 0 ? control.converters / control.contacts : 0,
163
+ },
164
+ ...verdict,
165
+ };
166
+ }