@hogsend/engine 0.53.0 → 0.55.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 (39) hide show
  1. package/package.json +12 -11
  2. package/src/buckets/check-membership.ts +45 -3
  3. package/src/connectors/define-action.ts +15 -2
  4. package/src/container.ts +85 -0
  5. package/src/env.ts +21 -0
  6. package/src/index.ts +19 -0
  7. package/src/journeys/durable-law-harness.test.ts +107 -0
  8. package/src/journeys/durable-law-harness.ts +139 -0
  9. package/src/journeys/journey-boundary.test.ts +70 -0
  10. package/src/journeys/journey-boundary.ts +10 -1
  11. package/src/journeys/with-durable-gate.test.ts +258 -0
  12. package/src/journeys/with-durable-gate.ts +141 -0
  13. package/src/lib/bucket-emit.test.ts +145 -0
  14. package/src/lib/bucket-emit.ts +29 -3
  15. package/src/lib/connector-actions.test.ts +292 -1
  16. package/src/lib/connector-actions.ts +65 -6
  17. package/src/lib/email-providers-from-env.ts +15 -16
  18. package/src/lib/enrichment-ledger.ts +207 -0
  19. package/src/lib/enrichment-provider-registry.test.ts +64 -0
  20. package/src/lib/enrichment-provider-registry.ts +35 -0
  21. package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
  22. package/src/lib/enrichment-providers-from-env.test.ts +28 -0
  23. package/src/lib/enrichment-providers-from-env.ts +52 -0
  24. package/src/lib/enrichment-registry-singleton.ts +45 -0
  25. package/src/lib/ingestion.ts +5 -0
  26. package/src/lib/load-optional-plugin.test.ts +133 -0
  27. package/src/lib/load-optional-plugin.ts +142 -0
  28. package/src/lib/outbound.ts +27 -0
  29. package/src/lib/refine-chain.test.ts +764 -0
  30. package/src/lib/refine-chain.ts +583 -0
  31. package/src/lib/refine-traits.test.ts +141 -0
  32. package/src/lib/refine-traits.ts +128 -0
  33. package/src/lib/refine.ts +287 -0
  34. package/src/lib/sms-providers-from-env.ts +11 -11
  35. package/src/lib/webhook-catalog-sync.test.ts +112 -0
  36. package/src/lib/webhook-signing.ts +5 -1
  37. package/src/routes/admin/contacts.ts +113 -13
  38. package/src/workflows/bucket-backfill.ts +14 -0
  39. package/src/workflows/bucket-reconcile.ts +74 -15
@@ -0,0 +1,70 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import { deriveJourneyKey, type JourneyKeyKind } from "./journey-boundary.js";
4
+
5
+ const ANCHOR = "run-anchor-1";
6
+ const SITE = "wait-event:nps-answer";
7
+ const DISCRIMINANT = "welcome";
8
+
9
+ test('the "refine" key kind is prefixed journeyRefine:', () => {
10
+ const key = deriveJourneyKey({
11
+ kind: "refine",
12
+ anchor: ANCHOR,
13
+ site: SITE,
14
+ discriminant: DISCRIMINANT,
15
+ });
16
+
17
+ assert.ok(
18
+ key.startsWith("journeyRefine:"),
19
+ `expected a journeyRefine: prefix, got "${key}"`,
20
+ );
21
+ assert.equal(key, `journeyRefine:${ANCHOR}:${SITE}:${DISCRIMINANT}`);
22
+ });
23
+
24
+ test('"refine" keys are disjoint from every other kind for identical inputs', () => {
25
+ // A collision here would make a refineContact() lookup dedupe against an
26
+ // unrelated email/SMS send sharing the same nearest wait label — the lookup
27
+ // would be silently dropped (or the send suppressed), with no error.
28
+ const kinds: JourneyKeyKind[] = [
29
+ "send",
30
+ "smsSend",
31
+ "trigger",
32
+ "connector",
33
+ "refine",
34
+ ];
35
+
36
+ const keys = kinds.map((kind) =>
37
+ deriveJourneyKey({
38
+ kind,
39
+ anchor: ANCHOR,
40
+ site: SITE,
41
+ discriminant: DISCRIMINANT,
42
+ }),
43
+ );
44
+
45
+ assert.equal(
46
+ new Set(keys).size,
47
+ kinds.length,
48
+ `expected ${kinds.length} distinct keys, got ${JSON.stringify(keys)}`,
49
+ );
50
+
51
+ const refineKey = deriveJourneyKey({
52
+ kind: "refine",
53
+ anchor: ANCHOR,
54
+ site: SITE,
55
+ discriminant: DISCRIMINANT,
56
+ });
57
+ for (const kind of kinds) {
58
+ if (kind === "refine") continue;
59
+ assert.notEqual(
60
+ refineKey,
61
+ deriveJourneyKey({
62
+ kind,
63
+ anchor: ANCHOR,
64
+ site: SITE,
65
+ discriminant: DISCRIMINANT,
66
+ }),
67
+ `"refine" collided with "${kind}"`,
68
+ );
69
+ }
70
+ });
@@ -222,7 +222,12 @@ export function supportsEviction(hatchetCtx: unknown): boolean {
222
222
  }
223
223
 
224
224
  /** The kind of side effect a key is derived for — keeps the namespaces apart. */
225
- export type JourneyKeyKind = "send" | "smsSend" | "trigger" | "connector";
225
+ export type JourneyKeyKind =
226
+ | "send"
227
+ | "smsSend"
228
+ | "trigger"
229
+ | "connector"
230
+ | "refine";
226
231
 
227
232
  const KEY_PREFIX: Record<JourneyKeyKind, string> = {
228
233
  send: "journeySend",
@@ -232,6 +237,10 @@ const KEY_PREFIX: Record<JourneyKeyKind, string> = {
232
237
  smsSend: "journeySmsSend",
233
238
  trigger: "journeyTrigger",
234
239
  connector: "journeyConnector",
240
+ // Refinement lookups (`refineContact()`) get their own namespace for the
241
+ // same reason as smsSend — a refine + any other side effect under the same
242
+ // nearest wait label must never collide.
243
+ refine: "journeyRefine",
235
244
  };
236
245
 
237
246
  /**
@@ -0,0 +1,258 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import {
4
+ assertUniformDurableJournal,
5
+ createRecordingBoundary,
6
+ } from "./durable-law-harness.js";
7
+ import { runWithJourneyBoundary } from "./journey-boundary.js";
8
+ import { callerRefFromArgs, withDurableGate } from "./with-durable-gate.js";
9
+
10
+ // The branded ref every test keys from — an "authored argument" by fiat.
11
+ const REF = callerRefFromArgs("u1");
12
+ assert.ok(REF);
13
+
14
+ // ---------------------------------------------------------------------------
15
+ // AC 1 — exactly ONE memoize per invocation, no matter which path gates()
16
+ // returns from
17
+ // ---------------------------------------------------------------------------
18
+
19
+ test("AC 1: memoize is issued exactly once, identically, for every return path of gates() — including an early return", async () => {
20
+ const { results, journal } = await assertUniformDurableJournal({
21
+ expectedJournal: ['memoize:["journeyRefine:run-1:u1:u1"]'],
22
+ paths: {
23
+ // The classic footgun: gates() returns from its FIRST line. The memoize
24
+ // must still have been issued before gates() ever ran.
25
+ earlyReturn: () =>
26
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
27
+ return { status: "skipped", reason: "no_lookup_key" };
28
+ }),
29
+ midReturn: () =>
30
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
31
+ await Promise.resolve();
32
+ return { status: "cached" };
33
+ }),
34
+ fullRun: () =>
35
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
36
+ await Promise.resolve();
37
+ await Promise.resolve();
38
+ return { status: "refined" };
39
+ }),
40
+ },
41
+ });
42
+
43
+ // The verdicts genuinely differ; the journal (asserted above) did not.
44
+ assert.deepEqual(results.earlyReturn, {
45
+ status: "skipped",
46
+ reason: "no_lookup_key",
47
+ });
48
+ assert.deepEqual(results.midReturn, { status: "cached" });
49
+ assert.deepEqual(results.fullRun, { status: "refined" });
50
+ assert.deepEqual(journal, ['memoize:["journeyRefine:run-1:u1:u1"]']);
51
+ });
52
+
53
+ test("AC 1: gates() receives the derived key, to thread into Layer-2 writes", async () => {
54
+ const { boundary } = createRecordingBoundary();
55
+ let received: string | undefined = "sentinel";
56
+ await runWithJourneyBoundary(boundary, () =>
57
+ withDurableGate({ kind: "refine", callerRef: REF }, async (key) => {
58
+ received = key;
59
+ return null;
60
+ }),
61
+ );
62
+ assert.equal(received, "journeyRefine:run-1:u1:u1");
63
+ });
64
+
65
+ test("AC 1: an eviction-capable engine replays the recorded verdict without re-entering gates()", async () => {
66
+ const { boundary, durableCalls } = createRecordingBoundary({
67
+ memoStrategy: "skip",
68
+ recordedValue: { status: "cached" },
69
+ });
70
+ let entered = 0;
71
+ const result = await runWithJourneyBoundary(boundary, () =>
72
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
73
+ entered += 1;
74
+ return { status: "refined" };
75
+ }),
76
+ );
77
+
78
+ assert.deepEqual(result, { status: "cached" });
79
+ assert.equal(entered, 0);
80
+ assert.deepEqual(durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
81
+ });
82
+
83
+ test("two sites deriving one key collide loudly instead of silently over-deduping", async () => {
84
+ const { boundary } = createRecordingBoundary({ currentLabel: "wait:same" });
85
+ await runWithJourneyBoundary(boundary, async () => {
86
+ await withDurableGate({ kind: "refine", callerRef: REF }, async () => 1);
87
+ await assert.rejects(
88
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => 2),
89
+ /duplicate idempotency key/,
90
+ );
91
+ });
92
+ });
93
+
94
+ // ---------------------------------------------------------------------------
95
+ // AC 2 — no boundary: gates() runs directly, zero durable calls
96
+ // ---------------------------------------------------------------------------
97
+
98
+ test("AC 2: with no boundary, gates() runs directly with no key and no durable calls", async () => {
99
+ let received: string | undefined = "sentinel";
100
+ let entered = 0;
101
+ const result = await withDurableGate(
102
+ { kind: "refine", callerRef: REF },
103
+ async (key) => {
104
+ entered += 1;
105
+ received = key;
106
+ return { status: "refined" };
107
+ },
108
+ );
109
+
110
+ assert.deepEqual(result, { status: "refined" });
111
+ assert.equal(entered, 1);
112
+ // No boundary → no key: Layer 2's unique index carries exactly-once alone.
113
+ assert.equal(received, undefined);
114
+ });
115
+
116
+ // ---------------------------------------------------------------------------
117
+ // AC 3 — key determinism
118
+ // ---------------------------------------------------------------------------
119
+
120
+ async function journalFor(opts: {
121
+ callerRef: string;
122
+ idempotencyLabel?: string;
123
+ currentLabel?: string;
124
+ }): Promise<string[]> {
125
+ const { boundary, durableCalls } = createRecordingBoundary({
126
+ currentLabel: opts.currentLabel,
127
+ });
128
+ const ref = callerRefFromArgs(opts.callerRef);
129
+ assert.ok(ref);
130
+ await runWithJourneyBoundary(boundary, () =>
131
+ withDurableGate(
132
+ {
133
+ kind: "refine",
134
+ callerRef: ref,
135
+ idempotencyLabel: opts.idempotencyLabel,
136
+ },
137
+ async () => null,
138
+ ),
139
+ );
140
+ return durableCalls;
141
+ }
142
+
143
+ test("AC 3: same callerRef + same label derive the same key; either differing re-keys", async () => {
144
+ // Identical inputs → identical key, across independent invocations.
145
+ assert.deepEqual(
146
+ await journalFor({ callerRef: "u1", idempotencyLabel: "second-pass" }),
147
+ await journalFor({ callerRef: "u1", idempotencyLabel: "second-pass" }),
148
+ );
149
+
150
+ const base = await journalFor({ callerRef: "u1" });
151
+ assert.deepEqual(base, ['memoize:["journeyRefine:run-1:u1:u1"]']);
152
+
153
+ // A different callerRef re-keys...
154
+ assert.notDeepEqual(await journalFor({ callerRef: "u2" }), base);
155
+ // ...and a different label re-keys.
156
+ assert.notDeepEqual(
157
+ await journalFor({ callerRef: "u1", idempotencyLabel: "second-pass" }),
158
+ base,
159
+ );
160
+ });
161
+
162
+ test("AC 3: the site precedence is idempotencyLabel ?? nearest wait label ?? callerRef", async () => {
163
+ assert.deepEqual(await journalFor({ callerRef: "u1" }), [
164
+ 'memoize:["journeyRefine:run-1:u1:u1"]',
165
+ ]);
166
+ assert.deepEqual(
167
+ await journalFor({ callerRef: "u1", currentLabel: "wait:nps" }),
168
+ ['memoize:["journeyRefine:run-1:wait:nps:u1"]'],
169
+ );
170
+ assert.deepEqual(
171
+ await journalFor({
172
+ callerRef: "u1",
173
+ currentLabel: "wait:nps",
174
+ idempotencyLabel: "second-pass",
175
+ }),
176
+ ['memoize:["journeyRefine:run-1:second-pass:u1"]'],
177
+ );
178
+ });
179
+
180
+ test("AC 3: the kind namespaces the key, so two kinds under one label never collide", async () => {
181
+ const { boundary, durableCalls } = createRecordingBoundary({
182
+ currentLabel: "wait:same",
183
+ });
184
+ await runWithJourneyBoundary(boundary, async () => {
185
+ await withDurableGate({ kind: "refine", callerRef: REF }, async () => 1);
186
+ await withDurableGate({ kind: "connector", callerRef: REF }, async () => 2);
187
+ });
188
+ assert.deepEqual(durableCalls, [
189
+ 'memoize:["journeyRefine:run-1:wait:same:u1"]',
190
+ 'memoize:["journeyConnector:run-1:wait:same:u1"]',
191
+ ]);
192
+ });
193
+
194
+ // ---------------------------------------------------------------------------
195
+ // AC 4 — a value not routed through callerRefFromArgs fails to TYPE-CHECK.
196
+ // These closures are never invoked; `check-types` is the assertion — if the
197
+ // forbidden call ever compiles, the @ts-expect-error itself becomes an error.
198
+ // ---------------------------------------------------------------------------
199
+
200
+ test("AC 4 (type-level): a bare string — e.g. a DB-read value — cannot be passed as callerRef", () => {
201
+ const rejectsPlainString = (dbDerived: string) =>
202
+ // @ts-expect-error — string is not assignable to CallerRef; route the
203
+ // caller's OWN argument through callerRefFromArgs instead.
204
+ withDurableGate({ kind: "refine", callerRef: dbDerived }, async () => null);
205
+
206
+ const rejectsLiteral = () =>
207
+ // @ts-expect-error — even a literal must go through the chokepoint.
208
+ withDurableGate({ kind: "refine", callerRef: "u1" }, async () => null);
209
+
210
+ const rejectsInterpolation = (row: { email: string }) =>
211
+ withDurableGate(
212
+ // @ts-expect-error — a template string over a resolved row is still a
213
+ // plain string, not a CallerRef.
214
+ { kind: "refine", callerRef: `${row.email}` },
215
+ async () => null,
216
+ );
217
+
218
+ // The closures exist only to be type-checked.
219
+ assert.equal(typeof rejectsPlainString, "function");
220
+ assert.equal(typeof rejectsLiteral, "function");
221
+ assert.equal(typeof rejectsInterpolation, "function");
222
+ });
223
+
224
+ test("AC 4: callerRefFromArgs trims, and refuses an empty value", () => {
225
+ assert.equal(callerRefFromArgs(" c-9 "), "c-9");
226
+ assert.equal(callerRefFromArgs(" "), undefined);
227
+ assert.equal(callerRefFromArgs(""), undefined);
228
+ assert.equal(callerRefFromArgs(undefined), undefined);
229
+ });
230
+
231
+ // ---------------------------------------------------------------------------
232
+ // AC 6 — a throw from gates() propagates, with no recorded verdict
233
+ // ---------------------------------------------------------------------------
234
+
235
+ test("AC 6: a throw from gates() propagates unswallowed, after the single memoize was issued", async () => {
236
+ const { boundary, durableCalls } = createRecordingBoundary();
237
+ await assert.rejects(
238
+ runWithJourneyBoundary(boundary, () =>
239
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
240
+ throw new Error("vendor 503");
241
+ }),
242
+ ),
243
+ /vendor 503/,
244
+ );
245
+ // The journal still holds exactly the one memoize — the rejection rode
246
+ // through it (Hatchet records no value for a rejected closure, so a replay
247
+ // re-enters gates()).
248
+ assert.deepEqual(durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
249
+ });
250
+
251
+ test("AC 6: with no boundary a throw propagates too", async () => {
252
+ await assert.rejects(
253
+ withDurableGate({ kind: "refine", callerRef: REF }, async () => {
254
+ throw new Error("vendor 503");
255
+ }),
256
+ /vendor 503/,
257
+ );
258
+ });
@@ -0,0 +1,141 @@
1
+ import {
2
+ deriveJourneyKey,
3
+ getJourneyBoundary,
4
+ type JourneyKeyKind,
5
+ registerKey,
6
+ } from "./journey-boundary.js";
7
+
8
+ // ---------------------------------------------------------------------------
9
+ // CallerRef — the branded discriminant
10
+ // ---------------------------------------------------------------------------
11
+
12
+ /**
13
+ * The brand is a module-private `unique symbol`: no other module can name it,
14
+ * so no other module can construct a {@link CallerRef} structurally. The ONLY
15
+ * two ways to produce one are {@link callerRefFromArgs} and a deliberate
16
+ * `as CallerRef` cast — the first is the sanctioned chokepoint, the second is
17
+ * greppable and indefensible in review. That is the point: provenance ("this
18
+ * string came from the caller's own arguments, not from an awaited DB read")
19
+ * is not something TypeScript can track through data flow, so the design
20
+ * substitutes a single, named, reviewable construction site for it.
21
+ */
22
+ declare const CALLER_REF: unique symbol;
23
+
24
+ /**
25
+ * A string proven — by construction — to be derived from the CALLER'S OWN
26
+ * ARGUMENTS, and therefore legal as a durable-memo key discriminant.
27
+ *
28
+ * THE LAW (`lib/feed.ts:152-165`): the Hatchet journal is positional, and
29
+ * `boundary.memoize` is a durable call, so its KEY must never contain the
30
+ * result of a live DB read. Hatchet re-derives task input from the recorded
31
+ * payload, so an ARGUMENT is identical on a run and its replay — a resolved
32
+ * row value is not (defects 2 and 3 of this class both keyed a memo off a
33
+ * value the database could change mid-sleep).
34
+ *
35
+ * A bare `string` — including every string that arrives via `await` — fails to
36
+ * type-check where a `CallerRef` is required. Route it through
37
+ * {@link callerRefFromArgs} ONLY when the value is an authored argument.
38
+ */
39
+ export type CallerRef = string & { readonly [CALLER_REF]: true };
40
+
41
+ /**
42
+ * Brand a value from the caller's own arguments as a {@link CallerRef}.
43
+ *
44
+ * CONTRACT (the compiler cannot check this half — the call site carries it):
45
+ * `value` must be derived exclusively from the caller's authored arguments.
46
+ * Never pass a value produced by an awaited read (a `contacts` row, a ledger
47
+ * row, a provider response) — that is precisely the bug class this type
48
+ * exists to make unwritable.
49
+ *
50
+ * Trims, and returns `undefined` for an empty/whitespace value so callers can
51
+ * fall through their argument-precedence chain with `??`/`if`.
52
+ */
53
+ export function callerRefFromArgs(
54
+ value: string | undefined,
55
+ ): CallerRef | undefined {
56
+ const trimmed = value?.trim();
57
+ return trimmed ? (trimmed as CallerRef) : undefined;
58
+ }
59
+
60
+ // ---------------------------------------------------------------------------
61
+ // withDurableGate — the one correct shape, owned once
62
+ // ---------------------------------------------------------------------------
63
+
64
+ export interface WithDurableGateOptions {
65
+ /** The side-effect namespace — keeps e.g. a refine and a send from ever
66
+ * colliding under one wait label. */
67
+ kind: JourneyKeyKind;
68
+ /**
69
+ * The memo-key discriminant, derived ONLY from the caller's own arguments —
70
+ * the branded type makes a raw (possibly DB-read) string a type error at the
71
+ * call site. See {@link CallerRef}.
72
+ */
73
+ callerRef: CallerRef;
74
+ /**
75
+ * Disambiguates the key when two sites of the same `kind` in one journey
76
+ * share a nearest wait label. Mirrors `sendEmail`/`sendSms`/`refineContact`.
77
+ */
78
+ idempotencyLabel?: string;
79
+ }
80
+
81
+ /**
82
+ * Run `gates` under the positional-journal law, so the law is structural
83
+ * rather than prose.
84
+ *
85
+ * Four bugs of one class shipped in one release, by three different authors,
86
+ * every one green on every gate: an early return placed before the memoize, a
87
+ * memo key derived from a value the function itself writes, a live read
88
+ * feeding both the decision to memoize and the key, and a skip path that
89
+ * issued zero durable calls. Each author re-derived this shape by hand and
90
+ * got one line of it wrong. This primitive owns the shape, so the ordering is
91
+ * no longer the author's to write.
92
+ *
93
+ * What it does, in this order and UNCONDITIONALLY:
94
+ *
95
+ * 1. Resolve the journey boundary. With NO boundary (a webhook, a cron, a
96
+ * test) there is no replay to defend against and no anchor to key from —
97
+ * `gates()` runs directly, zero durable calls, and Layer 2 (the callee's
98
+ * unique-index dedup) carries exactly-once on its own.
99
+ * 2. With a boundary: derive the key from `kind` + the replay-stable
100
+ * `runAnchor` + the site (`idempotencyLabel ?? nearest wait label ??
101
+ * callerRef`) + the branded `callerRef` — arguments only, never a
102
+ * resolved value.
103
+ * 3. `registerKey` — an intra-run collision (two sites, one key) throws
104
+ * loudly at dev time instead of silently over-deduping.
105
+ * 4. Issue `boundary.memoize([key], …)` — EXACTLY ONCE, with nothing between
106
+ * the boundary check and this call that reads a database or branches on
107
+ * one. Every stateful read and every verdict — including every skip —
108
+ * lives INSIDE `gates`, so it is recorded by the durable memo and
109
+ * replayed verbatim.
110
+ *
111
+ * `gates` receives the derived key (undefined outside a boundary) to thread
112
+ * into its Layer-2 writes as the idempotency key. A throw from `gates`
113
+ * propagates unswallowed; the memo layer records no value for a rejected
114
+ * closure, so a replay re-enters it.
115
+ */
116
+ export async function withDurableGate<T>(
117
+ opts: WithDurableGateOptions,
118
+ gates: (idempotencyKey?: string) => Promise<T>,
119
+ ): Promise<T> {
120
+ // `async` is part of the contract: a `registerKey` collision surfaces as a
121
+ // REJECTION, exactly as it did when this block lived inside the (async)
122
+ // `runRefineChain` — never as a synchronous throw at the call expression.
123
+ const boundary = getJourneyBoundary();
124
+
125
+ // Outside a journey run there is no replay to defend against and no boundary
126
+ // to key from — run the gates directly (connector-actions.ts:342).
127
+ if (!boundary) return gates();
128
+
129
+ // UNCONDITIONAL from here: derive → register → memoize. Nothing between this
130
+ // comment and the `memoize` call may read the database or branch on one.
131
+ const site = opts.idempotencyLabel ?? boundary.currentLabel ?? opts.callerRef;
132
+ const key = deriveJourneyKey({
133
+ kind: opts.kind,
134
+ anchor: boundary.runAnchor,
135
+ site,
136
+ discriminant: opts.callerRef,
137
+ });
138
+ registerKey(boundary, key);
139
+
140
+ return boundary.memoize([key], () => gates(key));
141
+ }
@@ -0,0 +1,145 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
4
+ import type { BucketMeta } from "@hogsend/core";
5
+ import type { JourneyRegistry } from "@hogsend/core/registry";
6
+ import type { Database } from "@hogsend/db";
7
+ import type { IngestEvent, ingestEvent } from "./ingestion.js";
8
+ import type { Logger } from "./logger.js";
9
+
10
+ // bucket-emit's import chain reaches env.ts (validates required env vars at
11
+ // import time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at
12
+ // import time) — stub both BEFORE the dynamic import. Nothing is ever
13
+ // contacted: the ingest seam intercepts everything. The token is the same
14
+ // well-formed dummy JWT apps/api's vitest config injects.
15
+ process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
16
+ process.env.BETTER_AUTH_SECRET ??= "test-secret";
17
+ process.env.HATCHET_CLIENT_TOKEN ??=
18
+ "eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
19
+ const { emitBucketTransition } = await import("./bucket-emit.js");
20
+
21
+ // ---------------------------------------------------------------------------
22
+ // Issue #608 — the `contactId` provenance pin. `emitBucketTransition`
23
+ // re-ingests every transition; `userId` is the contact's CANONICAL key
24
+ // (`external_id ?? anonymous_id ?? id`), but the resolver treats a bare
25
+ // `userId` as an EXTERNAL key, so an anonymous-only contact gets a phantom
26
+ // `external_id` twin minted per transition unless the pin rides the re-ingest.
27
+ // These tests assert at the `ingest` seam (no live DB — the Section 14
28
+ // pattern): the pin must ride BOTH re-ingests (per-bucket alias AND generic),
29
+ // and its absence must degrade to exactly the pin-less call shape.
30
+ // ---------------------------------------------------------------------------
31
+
32
+ const noop = () => {};
33
+ const logger: Logger = {
34
+ debug: noop,
35
+ info: noop,
36
+ warn: noop,
37
+ error: noop,
38
+ } as unknown as Logger;
39
+
40
+ const bucket: BucketMeta = {
41
+ id: "power-users",
42
+ name: "Power users",
43
+ } as BucketMeta;
44
+
45
+ /** A registry stub with a journey bound to the generic `bucket:<kind>` form, so
46
+ * the SECOND (generic) re-ingest actually fires and can be asserted on. */
47
+ function genericBoundRegistry(): JourneyRegistry {
48
+ return {
49
+ getByTriggerEvent: (event: string) =>
50
+ event === "bucket:entered" || event === "bucket:left" ? [{}] : [],
51
+ } as unknown as JourneyRegistry;
52
+ }
53
+
54
+ /** Recording ingest stub — captures each re-ingested event. */
55
+ function recordingIngest() {
56
+ const events: IngestEvent[] = [];
57
+ const ingest: typeof ingestEvent = async (opts) => {
58
+ events.push(opts.event);
59
+ return { stored: true, exits: [], contactKey: opts.event.userId ?? "" };
60
+ };
61
+ return { events, ingest };
62
+ }
63
+
64
+ // db/hatchet are never touched by the stubbed ingest; emitOutbound is
65
+ // fire-and-forget (`void ...catch(logger.warn)`) so its rejection on the empty
66
+ // db stub is swallowed by design.
67
+ const db = {} as Database;
68
+ const hatchet = {} as HatchetClient;
69
+
70
+ const CONTACT_ID = "9f3a1c2e-0000-4000-8000-000000000608";
71
+
72
+ test("entered: the contactId pin rides BOTH re-ingests (alias + generic)", async () => {
73
+ const { events, ingest } = recordingIngest();
74
+
75
+ await emitBucketTransition({
76
+ db,
77
+ registry: genericBoundRegistry(),
78
+ hatchet,
79
+ logger,
80
+ kind: "entered",
81
+ bucket,
82
+ userId: "anon-608",
83
+ userEmail: null,
84
+ contactId: CONTACT_ID,
85
+ epoch: 1,
86
+ ingest,
87
+ });
88
+
89
+ assert.equal(events.length, 2);
90
+ const [alias, generic] = events;
91
+ assert.equal(alias?.event, "bucket:entered:power-users");
92
+ assert.equal(generic?.event, "bucket:entered");
93
+ // The pin on EACH leg — dropping it on either one leaves the phantom-twin
94
+ // mint half-alive (issue #608).
95
+ assert.equal(alias?.contactId, CONTACT_ID);
96
+ assert.equal(generic?.contactId, CONTACT_ID);
97
+ });
98
+
99
+ test("left: the contactId pin rides the leave re-ingest too", async () => {
100
+ const { events, ingest } = recordingIngest();
101
+
102
+ await emitBucketTransition({
103
+ db,
104
+ registry: genericBoundRegistry(),
105
+ hatchet,
106
+ logger,
107
+ kind: "left",
108
+ bucket,
109
+ userId: "anon-608",
110
+ userEmail: null,
111
+ contactId: CONTACT_ID,
112
+ epoch: 2,
113
+ reason: "criteria",
114
+ ingest,
115
+ });
116
+
117
+ assert.equal(events.length, 2);
118
+ for (const event of events) {
119
+ assert.equal(event.contactId, CONTACT_ID);
120
+ }
121
+ });
122
+
123
+ test("no contactId: degrades to exactly the pin-less re-ingest", async () => {
124
+ const { events, ingest } = recordingIngest();
125
+
126
+ await emitBucketTransition({
127
+ db,
128
+ registry: genericBoundRegistry(),
129
+ hatchet,
130
+ logger,
131
+ kind: "entered",
132
+ bucket,
133
+ userId: "anon-608",
134
+ userEmail: null,
135
+ epoch: 1,
136
+ ingest,
137
+ });
138
+
139
+ // A producer with no resolved contact row in scope (e.g. the fast-expiry
140
+ // timer) must NOT invent a pin — the resolver falls back to value keys.
141
+ assert.equal(events.length, 2);
142
+ for (const event of events) {
143
+ assert.equal(event.contactId, undefined);
144
+ }
145
+ });