@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.
- package/package.json +12 -11
- package/src/buckets/check-membership.ts +45 -3
- package/src/connectors/define-action.ts +15 -2
- package/src/container.ts +85 -0
- package/src/env.ts +21 -0
- package/src/index.ts +19 -0
- package/src/journeys/durable-law-harness.test.ts +107 -0
- package/src/journeys/durable-law-harness.ts +139 -0
- package/src/journeys/journey-boundary.test.ts +70 -0
- package/src/journeys/journey-boundary.ts +10 -1
- package/src/journeys/with-durable-gate.test.ts +258 -0
- package/src/journeys/with-durable-gate.ts +141 -0
- package/src/lib/bucket-emit.test.ts +145 -0
- package/src/lib/bucket-emit.ts +29 -3
- package/src/lib/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- package/src/lib/email-providers-from-env.ts +15 -16
- package/src/lib/enrichment-ledger.ts +207 -0
- package/src/lib/enrichment-provider-registry.test.ts +64 -0
- package/src/lib/enrichment-provider-registry.ts +35 -0
- package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
- package/src/lib/enrichment-providers-from-env.test.ts +28 -0
- package/src/lib/enrichment-providers-from-env.ts +52 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -0
- package/src/lib/ingestion.ts +5 -0
- package/src/lib/load-optional-plugin.test.ts +133 -0
- package/src/lib/load-optional-plugin.ts +142 -0
- package/src/lib/outbound.ts +27 -0
- package/src/lib/refine-chain.test.ts +764 -0
- package/src/lib/refine-chain.ts +583 -0
- package/src/lib/refine-traits.test.ts +141 -0
- package/src/lib/refine-traits.ts +128 -0
- package/src/lib/refine.ts +287 -0
- package/src/lib/sms-providers-from-env.ts +11 -11
- package/src/lib/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
- package/src/workflows/bucket-backfill.ts +14 -0
- package/src/workflows/bucket-reconcile.ts +74 -15
|
@@ -0,0 +1,764 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type { EnrichmentProvider, EnrichmentResult } from "@hogsend/core";
|
|
4
|
+
import { assertUniformDurableJournal } from "../journeys/durable-law-harness.js";
|
|
5
|
+
import {
|
|
6
|
+
type JourneyBoundary,
|
|
7
|
+
runWithJourneyBoundary,
|
|
8
|
+
} from "../journeys/journey-boundary.js";
|
|
9
|
+
import {
|
|
10
|
+
type RefineChainDeps,
|
|
11
|
+
type RefineContactOptions,
|
|
12
|
+
type RefineContactResult,
|
|
13
|
+
type RefineEmitInput,
|
|
14
|
+
type RefineTarget,
|
|
15
|
+
refineOutboundDedupeKey,
|
|
16
|
+
runRefineChain,
|
|
17
|
+
} from "./refine-chain.js";
|
|
18
|
+
|
|
19
|
+
// ---------------------------------------------------------------------------
|
|
20
|
+
// Harness — a boundary that RECORDS every durable call, and a fake provider
|
|
21
|
+
// with a call COUNTER. AC 11 cannot be proved by return values alone: the
|
|
22
|
+
// positional-journal law is about which durable calls were issued, in which
|
|
23
|
+
// order, so that is what the stub records.
|
|
24
|
+
// ---------------------------------------------------------------------------
|
|
25
|
+
|
|
26
|
+
const NOW = new Date("2026-07-25T12:00:00.000Z");
|
|
27
|
+
const FOUND: EnrichmentResult = {
|
|
28
|
+
found: true,
|
|
29
|
+
person: { title: "CTO", seniority: "c_suite" },
|
|
30
|
+
company: { name: "Acme", employeeCount: 250 },
|
|
31
|
+
raw: { ok: true },
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
/** Every chain call names its subject — the memo key is derived from THIS. */
|
|
35
|
+
const SUBJECT: RefineContactOptions = { userId: "u1" };
|
|
36
|
+
|
|
37
|
+
interface RecordingBoundary {
|
|
38
|
+
boundary: JourneyBoundary;
|
|
39
|
+
/** One entry per durable call, in issuance order. */
|
|
40
|
+
durableCalls: string[];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function recordingBoundary(
|
|
44
|
+
currentLabel?: string,
|
|
45
|
+
memoStrategy: "run" | "skip" = "run",
|
|
46
|
+
): RecordingBoundary {
|
|
47
|
+
const durableCalls: string[] = [];
|
|
48
|
+
const boundary: JourneyBoundary = {
|
|
49
|
+
stateId: "state-1",
|
|
50
|
+
runAnchor: "run-1",
|
|
51
|
+
currentLabel,
|
|
52
|
+
seenKeys: new Set(),
|
|
53
|
+
seenRecordLabels: new Set(),
|
|
54
|
+
memoize: async (deps, fn) => {
|
|
55
|
+
durableCalls.push(`memoize:${JSON.stringify(deps)}`);
|
|
56
|
+
// "skip" models an eviction-capable engine replaying a recorded value
|
|
57
|
+
// WITHOUT re-entering the closure.
|
|
58
|
+
if (memoStrategy === "skip") {
|
|
59
|
+
return { status: "cached" } as unknown as never;
|
|
60
|
+
}
|
|
61
|
+
return fn();
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
return { boundary, durableCalls };
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
interface FakeProvider {
|
|
68
|
+
provider: EnrichmentProvider;
|
|
69
|
+
calls: () => number;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function fakeProvider(
|
|
73
|
+
behaviour: "found" | "throw" | "miss" = "found",
|
|
74
|
+
): FakeProvider {
|
|
75
|
+
let calls = 0;
|
|
76
|
+
const provider: EnrichmentProvider = {
|
|
77
|
+
meta: { id: "fake", name: "Fake" },
|
|
78
|
+
capabilities: { personLookup: true, companyLookup: true },
|
|
79
|
+
enrichPerson: async () => {
|
|
80
|
+
calls += 1;
|
|
81
|
+
if (behaviour === "throw") throw new Error("vendor 503");
|
|
82
|
+
if (behaviour === "miss") return { found: false, raw: null };
|
|
83
|
+
return FOUND;
|
|
84
|
+
},
|
|
85
|
+
};
|
|
86
|
+
return { provider, calls: () => calls };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
interface Harness {
|
|
90
|
+
deps: RefineChainDeps;
|
|
91
|
+
providerCalls: () => number;
|
|
92
|
+
ledgerWrites: number;
|
|
93
|
+
ingests: number;
|
|
94
|
+
/** Every outbound `contact.refined` emit, in order. */
|
|
95
|
+
emits: RefineEmitInput[];
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function harness(overrides: {
|
|
99
|
+
provider?: EnrichmentProvider;
|
|
100
|
+
providerCalls?: () => number;
|
|
101
|
+
ledgerRow?: {
|
|
102
|
+
status: "found" | "not_found" | "error";
|
|
103
|
+
expiresAt: Date;
|
|
104
|
+
traits?: Record<string, unknown> | null;
|
|
105
|
+
};
|
|
106
|
+
monthlyCap?: number;
|
|
107
|
+
usedThisMonth?: number;
|
|
108
|
+
domainOnly?: boolean;
|
|
109
|
+
target?: RefineTarget | null;
|
|
110
|
+
ingest?: () => Promise<void>;
|
|
111
|
+
}): Harness {
|
|
112
|
+
const fake = fakeProvider();
|
|
113
|
+
const provider = overrides.provider ?? fake.provider;
|
|
114
|
+
const providerCalls = overrides.providerCalls ?? fake.calls;
|
|
115
|
+
const state = {
|
|
116
|
+
ledgerWrites: 0,
|
|
117
|
+
ingests: 0,
|
|
118
|
+
emits: [] as RefineEmitInput[],
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
const deps: RefineChainDeps = {
|
|
122
|
+
provider,
|
|
123
|
+
providerId: provider.meta.id,
|
|
124
|
+
ttlDays: 90,
|
|
125
|
+
monthlyCap: overrides.monthlyCap ?? 0,
|
|
126
|
+
now: () => NOW,
|
|
127
|
+
logger: { info: () => {}, warn: () => {}, error: () => {} },
|
|
128
|
+
budgetWindowStart: () => new Date("2026-07-01T00:00:00.000Z"),
|
|
129
|
+
resolveTarget: async () =>
|
|
130
|
+
overrides.target !== undefined
|
|
131
|
+
? overrides.target
|
|
132
|
+
: overrides.domainOnly
|
|
133
|
+
? { contactId: "c1", userId: "u1", domain: "acme.com" }
|
|
134
|
+
: {
|
|
135
|
+
contactId: "c1",
|
|
136
|
+
userId: "u1",
|
|
137
|
+
email: "a@acme.com",
|
|
138
|
+
refinedProperties: { refined_title: "old" },
|
|
139
|
+
},
|
|
140
|
+
findLedgerRow: async () => overrides.ledgerRow ?? null,
|
|
141
|
+
countLookupsSince: async () => overrides.usedThisMonth ?? 0,
|
|
142
|
+
writeLedgerRow: async () => {
|
|
143
|
+
state.ledgerWrites += 1;
|
|
144
|
+
},
|
|
145
|
+
ingest: async () => {
|
|
146
|
+
state.ingests += 1;
|
|
147
|
+
if (overrides.ingest) await overrides.ingest();
|
|
148
|
+
},
|
|
149
|
+
emitRefined: (input) => {
|
|
150
|
+
state.emits.push(input);
|
|
151
|
+
},
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
return {
|
|
155
|
+
deps,
|
|
156
|
+
providerCalls,
|
|
157
|
+
get ledgerWrites() {
|
|
158
|
+
return state.ledgerWrites;
|
|
159
|
+
},
|
|
160
|
+
get ingests() {
|
|
161
|
+
return state.ingests;
|
|
162
|
+
},
|
|
163
|
+
get emits() {
|
|
164
|
+
return state.emits;
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
const unexpired = (
|
|
170
|
+
status: "found" | "not_found" | "error",
|
|
171
|
+
traits?: Record<string, unknown> | null,
|
|
172
|
+
) => ({
|
|
173
|
+
status,
|
|
174
|
+
expiresAt: new Date(NOW.getTime() + 86_400_000),
|
|
175
|
+
...(traits !== undefined ? { traits } : {}),
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
async function runInBoundary(
|
|
179
|
+
deps: RefineChainDeps,
|
|
180
|
+
opts: RefineContactOptions = SUBJECT,
|
|
181
|
+
boundaryArgs: Parameters<typeof recordingBoundary> = [],
|
|
182
|
+
): Promise<{ result: RefineContactResult; durableCalls: string[] }> {
|
|
183
|
+
const { boundary, durableCalls } = recordingBoundary(...boundaryArgs);
|
|
184
|
+
const result = await runWithJourneyBoundary(boundary, () =>
|
|
185
|
+
runRefineChain(deps, opts),
|
|
186
|
+
);
|
|
187
|
+
return { result, durableCalls };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// ---------------------------------------------------------------------------
|
|
191
|
+
// AC 11 — THE POSITIONAL-JOURNAL LAW
|
|
192
|
+
// ---------------------------------------------------------------------------
|
|
193
|
+
|
|
194
|
+
test("AC 11: memoize is issued EXACTLY ONCE per invocation, identically, no matter which gate returns", async () => {
|
|
195
|
+
// Six chains that return from six DIFFERENT gates. Refinement is the worst
|
|
196
|
+
// case for the law because TWO live reads want to sit in front of the memo:
|
|
197
|
+
// the ledger gate reads the very row the `refined` path writes at its final
|
|
198
|
+
// step, and resolving the subject reads a `contacts` row that gains an email
|
|
199
|
+
// mid-sleep. Either one, early-returned, diverges on EVERY replay.
|
|
200
|
+
const cached = await runInBoundary(
|
|
201
|
+
harness({ ledgerRow: unexpired("found") }).deps,
|
|
202
|
+
);
|
|
203
|
+
const budget = await runInBoundary(
|
|
204
|
+
harness({ monthlyCap: 5, usedThisMonth: 5 }).deps,
|
|
205
|
+
);
|
|
206
|
+
const refined = await runInBoundary(harness({}).deps);
|
|
207
|
+
const notFoundCached = await runInBoundary(
|
|
208
|
+
harness({ ledgerRow: unexpired("not_found") }).deps,
|
|
209
|
+
);
|
|
210
|
+
const providerError = await runInBoundary(
|
|
211
|
+
harness({ provider: fakeProvider("throw").provider }).deps,
|
|
212
|
+
);
|
|
213
|
+
// The gate the SHIPPED code returned from before the memoize — the whole
|
|
214
|
+
// point of this regression.
|
|
215
|
+
const noLookupKey = await runInBoundary(harness({ target: null }).deps);
|
|
216
|
+
|
|
217
|
+
// The verdicts genuinely differ...
|
|
218
|
+
assert.equal(cached.result.status, "cached");
|
|
219
|
+
assert.deepEqual(budget.result, {
|
|
220
|
+
status: "skipped",
|
|
221
|
+
reason: "budget_exceeded",
|
|
222
|
+
});
|
|
223
|
+
assert.equal(refined.result.status, "refined");
|
|
224
|
+
assert.equal(notFoundCached.result.status, "not_found");
|
|
225
|
+
assert.deepEqual(providerError.result, {
|
|
226
|
+
status: "skipped",
|
|
227
|
+
reason: "provider_error",
|
|
228
|
+
});
|
|
229
|
+
assert.deepEqual(noLookupKey.result, {
|
|
230
|
+
status: "skipped",
|
|
231
|
+
reason: "no_lookup_key",
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
// ...and yet the durable journal is byte-identical across all six.
|
|
235
|
+
const expected = ['memoize:["journeyRefine:run-1:u1:u1"]'];
|
|
236
|
+
assert.deepEqual(cached.durableCalls, expected);
|
|
237
|
+
assert.deepEqual(budget.durableCalls, expected);
|
|
238
|
+
assert.deepEqual(refined.durableCalls, expected);
|
|
239
|
+
assert.deepEqual(notFoundCached.durableCalls, expected);
|
|
240
|
+
assert.deepEqual(providerError.durableCalls, expected);
|
|
241
|
+
assert.deepEqual(noLookupKey.durableCalls, expected);
|
|
242
|
+
});
|
|
243
|
+
|
|
244
|
+
test("AC 11: the memo key is derived from the nearest wait label, and idempotencyLabel wins", async () => {
|
|
245
|
+
const labelled = await runInBoundary(harness({}).deps, SUBJECT, ["wait:nps"]);
|
|
246
|
+
assert.deepEqual(labelled.durableCalls, [
|
|
247
|
+
'memoize:["journeyRefine:run-1:wait:nps:u1"]',
|
|
248
|
+
]);
|
|
249
|
+
|
|
250
|
+
const explicit = await runInBoundary(harness({}).deps, {
|
|
251
|
+
...SUBJECT,
|
|
252
|
+
idempotencyLabel: "second-pass",
|
|
253
|
+
});
|
|
254
|
+
assert.deepEqual(explicit.durableCalls, [
|
|
255
|
+
'memoize:["journeyRefine:run-1:second-pass:u1"]',
|
|
256
|
+
]);
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
test("AC 11: the memo key is derived from the CALLER's arguments, never a resolved contact value", async () => {
|
|
260
|
+
// Same call, three different resolved subjects. The key may not move.
|
|
261
|
+
const expected = ['memoize:["journeyRefine:run-1:u1:u1"]'];
|
|
262
|
+
for (const target of [
|
|
263
|
+
null,
|
|
264
|
+
{ contactId: "c1", userId: "u1", domain: "acme.com" },
|
|
265
|
+
{ contactId: "c1", userId: "u1", email: "a@acme.com" },
|
|
266
|
+
] as (RefineTarget | null)[]) {
|
|
267
|
+
const { durableCalls } = await runInBoundary(harness({ target }).deps);
|
|
268
|
+
assert.deepEqual(durableCalls, expected);
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
// contactId beats email beats userId, and the email is normalized so a
|
|
272
|
+
// differently-cased argument cannot re-key the memo.
|
|
273
|
+
const byEmail = await runInBoundary(harness({}).deps, {
|
|
274
|
+
email: " A@Acme.com ",
|
|
275
|
+
userId: "u1",
|
|
276
|
+
});
|
|
277
|
+
assert.deepEqual(byEmail.durableCalls, [
|
|
278
|
+
'memoize:["journeyRefine:run-1:a@acme.com:a@acme.com"]',
|
|
279
|
+
]);
|
|
280
|
+
|
|
281
|
+
const byContactId = await runInBoundary(harness({}).deps, {
|
|
282
|
+
contactId: "c-9",
|
|
283
|
+
email: "a@acme.com",
|
|
284
|
+
userId: "u1",
|
|
285
|
+
});
|
|
286
|
+
assert.deepEqual(byContactId.durableCalls, [
|
|
287
|
+
'memoize:["journeyRefine:run-1:c-9:c-9"]',
|
|
288
|
+
]);
|
|
289
|
+
});
|
|
290
|
+
|
|
291
|
+
test("D1 variant A: a contact that gains an email between run and replay issues the SAME journal", async () => {
|
|
292
|
+
// The mainstream flow: a journey enrols on an anonymous event, refines (no
|
|
293
|
+
// lookup key yet), then sleeps for three days. The user fills in the trial
|
|
294
|
+
// form during the sleep, so `contacts.email` is promoted. With eviction live
|
|
295
|
+
// the sleep resumes by replaying from the top — and the shipped code issued
|
|
296
|
+
// ZERO memos on the run and ONE on the replay, shifting every later durable
|
|
297
|
+
// call and killing the run.
|
|
298
|
+
const anonymous = harness({ target: null });
|
|
299
|
+
const identified = harness({});
|
|
300
|
+
|
|
301
|
+
const run = await runInBoundary(anonymous.deps);
|
|
302
|
+
const replay = await runInBoundary(identified.deps);
|
|
303
|
+
|
|
304
|
+
assert.deepEqual(run.result, { status: "skipped", reason: "no_lookup_key" });
|
|
305
|
+
assert.deepEqual(run.durableCalls, replay.durableCalls);
|
|
306
|
+
assert.deepEqual(run.durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
|
|
307
|
+
});
|
|
308
|
+
|
|
309
|
+
test("D1 variant B: a domain-only contact that gains an email derives the SAME memo key, so a replay never re-spends", async () => {
|
|
310
|
+
// Same run anchor, same authored call, a subject that upgraded domain→email
|
|
311
|
+
// mid-sleep. The shipped code keyed the memo on the RESOLVED lookup key, so
|
|
312
|
+
// the replay missed the memo, missed the (differently-keyed) ledger row, and
|
|
313
|
+
// charged the vendor twice for one logical refinement.
|
|
314
|
+
const beforeUpgrade = harness({ domainOnly: true });
|
|
315
|
+
const afterUpgrade = harness({});
|
|
316
|
+
|
|
317
|
+
const run = await runInBoundary(beforeUpgrade.deps);
|
|
318
|
+
const replay = await runInBoundary(afterUpgrade.deps);
|
|
319
|
+
assert.deepEqual(run.durableCalls, replay.durableCalls);
|
|
320
|
+
|
|
321
|
+
// ...and on an eviction-capable engine the replay never re-enters the
|
|
322
|
+
// closure at all: zero provider calls, zero spend.
|
|
323
|
+
const evicting = harness({});
|
|
324
|
+
const { boundary } = recordingBoundary(undefined, "skip");
|
|
325
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
326
|
+
runRefineChain(evicting.deps, SUBJECT),
|
|
327
|
+
);
|
|
328
|
+
assert.equal(evicting.providerCalls(), 0);
|
|
329
|
+
});
|
|
330
|
+
|
|
331
|
+
test("AC 11: an eviction-capable engine replays the RECORDED verdict without re-entering the closure", async () => {
|
|
332
|
+
// `memoStrategy: "skip"` models a live-eviction Hatchet: the closure is never
|
|
333
|
+
// run on the replay, so no resolve, no gate, no provider call, no ledger
|
|
334
|
+
// write, no ingest.
|
|
335
|
+
const h = harness({});
|
|
336
|
+
const { boundary, durableCalls } = recordingBoundary(undefined, "skip");
|
|
337
|
+
const result = await runWithJourneyBoundary(boundary, () =>
|
|
338
|
+
runRefineChain(h.deps, SUBJECT),
|
|
339
|
+
);
|
|
340
|
+
|
|
341
|
+
assert.deepEqual(result, { status: "cached" });
|
|
342
|
+
assert.equal(h.providerCalls(), 0);
|
|
343
|
+
assert.equal(h.ledgerWrites, 0);
|
|
344
|
+
assert.equal(h.ingests, 0);
|
|
345
|
+
assert.deepEqual(durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
|
|
346
|
+
});
|
|
347
|
+
|
|
348
|
+
test("two refine sites under one wait label collide loudly instead of silently over-deduping", async () => {
|
|
349
|
+
const h = harness({});
|
|
350
|
+
const { boundary } = recordingBoundary("wait:same");
|
|
351
|
+
|
|
352
|
+
await runWithJourneyBoundary(boundary, async () => {
|
|
353
|
+
await runRefineChain(h.deps, SUBJECT);
|
|
354
|
+
await assert.rejects(
|
|
355
|
+
runRefineChain(h.deps, SUBJECT),
|
|
356
|
+
/duplicate idempotency key/,
|
|
357
|
+
);
|
|
358
|
+
});
|
|
359
|
+
});
|
|
360
|
+
|
|
361
|
+
// ---------------------------------------------------------------------------
|
|
362
|
+
// Gate-ordering behaviour that needs no database
|
|
363
|
+
// ---------------------------------------------------------------------------
|
|
364
|
+
|
|
365
|
+
test("with NO boundary the chain runs directly — zero durable calls, Layer 2 carries it", async () => {
|
|
366
|
+
const h = harness({});
|
|
367
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
368
|
+
|
|
369
|
+
assert.equal(result.status, "refined");
|
|
370
|
+
assert.equal(h.providerCalls(), 1);
|
|
371
|
+
assert.equal(h.ledgerWrites, 1);
|
|
372
|
+
assert.equal(h.ingests, 1);
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
test("step 0: a call naming no subject at all skips WITHOUT reading the database", async () => {
|
|
376
|
+
const h = harness({});
|
|
377
|
+
let resolves = 0;
|
|
378
|
+
h.deps.resolveTarget = async () => {
|
|
379
|
+
resolves += 1;
|
|
380
|
+
return null;
|
|
381
|
+
};
|
|
382
|
+
const { result, durableCalls } = await runInBoundary(h.deps, {});
|
|
383
|
+
|
|
384
|
+
assert.deepEqual(result, { status: "skipped", reason: "no_lookup_key" });
|
|
385
|
+
assert.equal(h.providerCalls(), 0);
|
|
386
|
+
// A PURE argument check — nothing to key from, and no DB read to diverge on.
|
|
387
|
+
assert.equal(resolves, 0);
|
|
388
|
+
assert.deepEqual(durableCalls, []);
|
|
389
|
+
});
|
|
390
|
+
|
|
391
|
+
test("step 2: an unresolvable subject skips INSIDE the memo, so the verdict replays verbatim", async () => {
|
|
392
|
+
const h = harness({ target: null });
|
|
393
|
+
const { result, durableCalls } = await runInBoundary(h.deps);
|
|
394
|
+
|
|
395
|
+
assert.deepEqual(result, { status: "skipped", reason: "no_lookup_key" });
|
|
396
|
+
assert.equal(h.providerCalls(), 0);
|
|
397
|
+
// The resolve is a LIVE `contacts` read, so its verdict is memo-recorded like
|
|
398
|
+
// every other stateful one — the memoize is still issued.
|
|
399
|
+
assert.deepEqual(durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
|
|
400
|
+
});
|
|
401
|
+
|
|
402
|
+
test("AC 6: no active provider skips with zero spend and never throws", async () => {
|
|
403
|
+
const h = harness({});
|
|
404
|
+
h.deps.provider = undefined;
|
|
405
|
+
h.deps.providerId = undefined;
|
|
406
|
+
const { result, durableCalls } = await runInBoundary(h.deps);
|
|
407
|
+
|
|
408
|
+
assert.deepEqual(result, { status: "skipped", reason: "no_provider" });
|
|
409
|
+
assert.equal(h.providerCalls(), 0);
|
|
410
|
+
assert.deepEqual(durableCalls, []);
|
|
411
|
+
});
|
|
412
|
+
|
|
413
|
+
test("an unexpired `error` ledger row does NOT short-circuit — the vendor is retried", async () => {
|
|
414
|
+
const h = harness({ ledgerRow: unexpired("error") });
|
|
415
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
416
|
+
|
|
417
|
+
assert.equal(result.status, "refined");
|
|
418
|
+
assert.equal(h.providerCalls(), 1);
|
|
419
|
+
});
|
|
420
|
+
|
|
421
|
+
test("an EXPIRED found row does not short-circuit", async () => {
|
|
422
|
+
const h = harness({
|
|
423
|
+
ledgerRow: {
|
|
424
|
+
status: "found",
|
|
425
|
+
expiresAt: new Date(NOW.getTime() - 1_000),
|
|
426
|
+
},
|
|
427
|
+
});
|
|
428
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
429
|
+
|
|
430
|
+
assert.equal(result.status, "refined");
|
|
431
|
+
assert.equal(h.providerCalls(), 1);
|
|
432
|
+
});
|
|
433
|
+
|
|
434
|
+
test("force bypasses the ledger gate but NOT the budget cap", async () => {
|
|
435
|
+
const bypass = harness({ ledgerRow: unexpired("found") });
|
|
436
|
+
assert.equal(
|
|
437
|
+
(await runRefineChain(bypass.deps, { ...SUBJECT, force: true })).status,
|
|
438
|
+
"refined",
|
|
439
|
+
);
|
|
440
|
+
assert.equal(bypass.providerCalls(), 1);
|
|
441
|
+
|
|
442
|
+
const capped = harness({
|
|
443
|
+
ledgerRow: unexpired("found"),
|
|
444
|
+
monthlyCap: 2,
|
|
445
|
+
usedThisMonth: 2,
|
|
446
|
+
});
|
|
447
|
+
assert.deepEqual(
|
|
448
|
+
await runRefineChain(capped.deps, { ...SUBJECT, force: true }),
|
|
449
|
+
{
|
|
450
|
+
status: "skipped",
|
|
451
|
+
reason: "budget_exceeded",
|
|
452
|
+
},
|
|
453
|
+
);
|
|
454
|
+
assert.equal(capped.providerCalls(), 0);
|
|
455
|
+
});
|
|
456
|
+
|
|
457
|
+
test("a domain-only contact looks up by domain kind", async () => {
|
|
458
|
+
const h = harness({ domainOnly: true });
|
|
459
|
+
const { durableCalls } = await runInBoundary(h.deps);
|
|
460
|
+
|
|
461
|
+
assert.deepEqual(durableCalls, ['memoize:["journeyRefine:run-1:u1:u1"]']);
|
|
462
|
+
assert.equal(h.providerCalls(), 1);
|
|
463
|
+
});
|
|
464
|
+
|
|
465
|
+
// ---------------------------------------------------------------------------
|
|
466
|
+
// D2 — a cache hit suppresses SPEND, never the outcome
|
|
467
|
+
// ---------------------------------------------------------------------------
|
|
468
|
+
|
|
469
|
+
test("D2: a cache hit lands the STORED patch on a contact that never received it", async () => {
|
|
470
|
+
// The shared-domain case: contact B hits the row contact A paid for. The
|
|
471
|
+
// ledger has no contact dimension, so "already paid for" says nothing about
|
|
472
|
+
// whether THIS contact has the traits.
|
|
473
|
+
const stored = { refined_title: "CTO", refined_company_employees: 250 };
|
|
474
|
+
const h = harness({
|
|
475
|
+
ledgerRow: unexpired("found", stored),
|
|
476
|
+
target: { contactId: "c2", userId: "u2", domain: "acme.com" },
|
|
477
|
+
});
|
|
478
|
+
|
|
479
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
480
|
+
|
|
481
|
+
assert.deepEqual(result, { status: "cached", properties: stored });
|
|
482
|
+
// AC 2 is intact — zero spend, no new ledger row...
|
|
483
|
+
assert.equal(h.providerCalls(), 0);
|
|
484
|
+
assert.equal(h.ledgerWrites, 0);
|
|
485
|
+
// ...and yet the loop closed for B.
|
|
486
|
+
assert.equal(h.ingests, 1);
|
|
487
|
+
});
|
|
488
|
+
|
|
489
|
+
test("D2: a cache hit re-runs the ingest even when the contact already holds the traits", async () => {
|
|
490
|
+
// Holding the properties is NOT the same as having been evaluated against the
|
|
491
|
+
// buckets: only the ingest path re-runs `checkBucketMembership`, and a
|
|
492
|
+
// contact can carry the traits with no membership (exactly what a failed
|
|
493
|
+
// ingest leaves behind). So the cached verdict always re-lands.
|
|
494
|
+
const stored = { refined_title: "CTO", refined_company_employees: 250 };
|
|
495
|
+
const h = harness({
|
|
496
|
+
ledgerRow: unexpired("found", stored),
|
|
497
|
+
target: {
|
|
498
|
+
contactId: "c1",
|
|
499
|
+
userId: "u1",
|
|
500
|
+
domain: "acme.com",
|
|
501
|
+
refinedProperties: { ...stored },
|
|
502
|
+
},
|
|
503
|
+
});
|
|
504
|
+
|
|
505
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
506
|
+
|
|
507
|
+
assert.deepEqual(result, { status: "cached", properties: stored });
|
|
508
|
+
assert.equal(h.ingests, 1);
|
|
509
|
+
assert.equal(h.providerCalls(), 0);
|
|
510
|
+
assert.equal(h.ledgerWrites, 0);
|
|
511
|
+
});
|
|
512
|
+
|
|
513
|
+
test("D2: a legacy row with no stored patch falls back to the caller's own traits", async () => {
|
|
514
|
+
const h = harness({ ledgerRow: unexpired("found", null) });
|
|
515
|
+
|
|
516
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
517
|
+
|
|
518
|
+
assert.deepEqual(result, {
|
|
519
|
+
status: "cached",
|
|
520
|
+
properties: { refined_title: "old" },
|
|
521
|
+
});
|
|
522
|
+
assert.equal(h.ingests, 0);
|
|
523
|
+
assert.equal(h.providerCalls(), 0);
|
|
524
|
+
});
|
|
525
|
+
|
|
526
|
+
// ---------------------------------------------------------------------------
|
|
527
|
+
// D4b — a failed ingest is a verdict, not an exception
|
|
528
|
+
// ---------------------------------------------------------------------------
|
|
529
|
+
|
|
530
|
+
test("D4b: a failed ingest does not throw out of the chain and does not report success", async () => {
|
|
531
|
+
const h = harness({
|
|
532
|
+
ingest: async () => {
|
|
533
|
+
throw new Error("hatchet unavailable");
|
|
534
|
+
},
|
|
535
|
+
});
|
|
536
|
+
|
|
537
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
538
|
+
|
|
539
|
+
// The spend is recorded (the vendor answered) but the caller is told the
|
|
540
|
+
// loop did not close — refinement must never fail the journey run.
|
|
541
|
+
assert.deepEqual(result, { status: "skipped", reason: "ingest_failed" });
|
|
542
|
+
assert.equal(h.ledgerWrites, 1);
|
|
543
|
+
});
|
|
544
|
+
|
|
545
|
+
test("D4b: the retry after a failed ingest re-lands the stored patch for FREE", async () => {
|
|
546
|
+
const stored = { refined_title: "CTO" };
|
|
547
|
+
const h = harness({ ledgerRow: unexpired("found", stored) });
|
|
548
|
+
|
|
549
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
550
|
+
|
|
551
|
+
assert.deepEqual(result, { status: "cached", properties: stored });
|
|
552
|
+
assert.equal(h.providerCalls(), 0);
|
|
553
|
+
assert.equal(h.ingests, 1);
|
|
554
|
+
});
|
|
555
|
+
|
|
556
|
+
// ---------------------------------------------------------------------------
|
|
557
|
+
// PRD 08 — the outbound `contact.refined` event
|
|
558
|
+
// ---------------------------------------------------------------------------
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* The sorted trait key names FOUND flattens to — NAMES, never values, and
|
|
562
|
+
* VENDOR facts only: `refined_at` / `refined_provider` are provenance, already
|
|
563
|
+
* carried as the envelope's `at` / `provider`, so they are not traits.
|
|
564
|
+
*/
|
|
565
|
+
const FOUND_TRAIT_KEYS = [
|
|
566
|
+
"refined_company_employees",
|
|
567
|
+
"refined_company_name",
|
|
568
|
+
"refined_seniority",
|
|
569
|
+
"refined_title",
|
|
570
|
+
];
|
|
571
|
+
|
|
572
|
+
/** NOW as the dedupe key serializes it. */
|
|
573
|
+
const NOW_ISO = NOW.toISOString();
|
|
574
|
+
|
|
575
|
+
test("AC 1: a `refined` verdict emits contact.refined with the contact key, provider id and trait NAMES", async () => {
|
|
576
|
+
const h = harness({});
|
|
577
|
+
|
|
578
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
579
|
+
|
|
580
|
+
assert.equal(result.status, "refined");
|
|
581
|
+
assert.equal(h.emits.length, 1);
|
|
582
|
+
assert.deepEqual(h.emits[0], {
|
|
583
|
+
userId: "u1",
|
|
584
|
+
email: "a@acme.com",
|
|
585
|
+
contactId: "c1",
|
|
586
|
+
provider: "fake",
|
|
587
|
+
traitKeys: FOUND_TRAIT_KEYS,
|
|
588
|
+
refinedAt: NOW,
|
|
589
|
+
dedupeKey: `refine:fake:email:a@acme.com:${NOW_ISO}`,
|
|
590
|
+
});
|
|
591
|
+
|
|
592
|
+
// The payload carries key NAMES, never the vendor's values: the event says
|
|
593
|
+
// what changed and a subscriber that wants the values reads the contact.
|
|
594
|
+
const emitted = h.emits[0] as RefineEmitInput;
|
|
595
|
+
assert.ok(!JSON.stringify(emitted.traitKeys).includes("CTO"));
|
|
596
|
+
assert.ok(!JSON.stringify(emitted.traitKeys).includes("Acme"));
|
|
597
|
+
// Provenance is NOT a trait — it rides as `provider` / `refinedAt` instead.
|
|
598
|
+
assert.ok(!emitted.traitKeys.includes("refined_at"));
|
|
599
|
+
assert.ok(!emitted.traitKeys.includes("refined_provider"));
|
|
600
|
+
});
|
|
601
|
+
|
|
602
|
+
test("AC 1: a found-but-empty vendor answer reports NO traits rather than two metadata keys", async () => {
|
|
603
|
+
// `flattenTraits` stamps refined_at/refined_provider unconditionally, so if
|
|
604
|
+
// provenance counted as a trait this payload would claim two changes for an
|
|
605
|
+
// answer that told us nothing about the person.
|
|
606
|
+
const empty: EnrichmentProvider = {
|
|
607
|
+
meta: { id: "fake", name: "Fake" },
|
|
608
|
+
capabilities: { personLookup: true, companyLookup: true },
|
|
609
|
+
enrichPerson: async () => ({ found: true, raw: {} }),
|
|
610
|
+
};
|
|
611
|
+
const h = harness({ provider: empty });
|
|
612
|
+
|
|
613
|
+
assert.equal((await runRefineChain(h.deps, SUBJECT)).status, "refined");
|
|
614
|
+
assert.deepEqual(h.emits[0]?.traitKeys, []);
|
|
615
|
+
});
|
|
616
|
+
|
|
617
|
+
test("AC 1: a domain-keyed refinement emits with the domain lookup in its dedupe key", async () => {
|
|
618
|
+
const h = harness({ domainOnly: true });
|
|
619
|
+
|
|
620
|
+
assert.equal((await runRefineChain(h.deps, SUBJECT)).status, "refined");
|
|
621
|
+
assert.equal(h.emits.length, 1);
|
|
622
|
+
assert.equal(h.emits[0]?.dedupeKey, `refine:fake:domain:acme.com:${NOW_ISO}`);
|
|
623
|
+
// No email on the subject — the key fields carry only what actually resolved.
|
|
624
|
+
assert.equal(h.emits[0]?.email, undefined);
|
|
625
|
+
assert.equal(h.emits[0]?.userId, "u1");
|
|
626
|
+
});
|
|
627
|
+
|
|
628
|
+
test("AC 2: `cached`, `not_found` and `skipped` emit NOTHING — a cache hit is not an event", async () => {
|
|
629
|
+
const cached = harness({
|
|
630
|
+
ledgerRow: unexpired("found", { refined_title: "CTO" }),
|
|
631
|
+
});
|
|
632
|
+
const notFoundCached = harness({ ledgerRow: unexpired("not_found") });
|
|
633
|
+
const notFoundLive = harness({ provider: fakeProvider("miss").provider });
|
|
634
|
+
const noLookupKey = harness({ target: null });
|
|
635
|
+
const noProvider = harness({});
|
|
636
|
+
noProvider.deps.provider = undefined;
|
|
637
|
+
noProvider.deps.providerId = undefined;
|
|
638
|
+
const budget = harness({ monthlyCap: 5, usedThisMonth: 5 });
|
|
639
|
+
const providerError = harness({ provider: fakeProvider("throw").provider });
|
|
640
|
+
const ingestFailed = harness({
|
|
641
|
+
ingest: async () => {
|
|
642
|
+
throw new Error("hatchet unavailable");
|
|
643
|
+
},
|
|
644
|
+
});
|
|
645
|
+
|
|
646
|
+
const cases: [string, Harness, string][] = [
|
|
647
|
+
["cached", cached, "cached"],
|
|
648
|
+
["not_found (ledger)", notFoundCached, "not_found"],
|
|
649
|
+
["not_found (live)", notFoundLive, "not_found"],
|
|
650
|
+
["skipped:no_lookup_key", noLookupKey, "skipped"],
|
|
651
|
+
["skipped:no_provider", noProvider, "skipped"],
|
|
652
|
+
["skipped:budget_exceeded", budget, "skipped"],
|
|
653
|
+
["skipped:provider_error", providerError, "skipped"],
|
|
654
|
+
["skipped:ingest_failed", ingestFailed, "skipped"],
|
|
655
|
+
];
|
|
656
|
+
|
|
657
|
+
for (const [name, h, expected] of cases) {
|
|
658
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
659
|
+
assert.equal(result.status, expected, name);
|
|
660
|
+
assert.deepEqual(h.emits, [], `${name} must not emit contact.refined`);
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
// The control: the SAME harness shape on the genuine path does emit, so the
|
|
664
|
+
// assertions above are not passing for a trivial reason.
|
|
665
|
+
const refined = harness({});
|
|
666
|
+
assert.equal((await runRefineChain(refined.deps, SUBJECT)).status, "refined");
|
|
667
|
+
assert.equal(refined.emits.length, 1);
|
|
668
|
+
});
|
|
669
|
+
|
|
670
|
+
test("AC 3: re-driving the SAME answer recomputes the SAME dedupeKey, so the second delivery is absorbed", async () => {
|
|
671
|
+
// Two independent drives of the same logical refinement — a task retry, or a
|
|
672
|
+
// boundary-less re-run — landing the same answer at the same instant.
|
|
673
|
+
const first = harness({});
|
|
674
|
+
const second = harness({});
|
|
675
|
+
await runRefineChain(first.deps, SUBJECT);
|
|
676
|
+
await runRefineChain(second.deps, SUBJECT);
|
|
677
|
+
|
|
678
|
+
assert.equal(first.emits[0]?.dedupeKey, second.emits[0]?.dedupeKey);
|
|
679
|
+
assert.equal(
|
|
680
|
+
first.emits[0]?.dedupeKey,
|
|
681
|
+
refineOutboundDedupeKey({
|
|
682
|
+
provider: "fake",
|
|
683
|
+
lookupKind: "email",
|
|
684
|
+
lookupKey: "a@acme.com",
|
|
685
|
+
refinedAt: NOW,
|
|
686
|
+
}),
|
|
687
|
+
);
|
|
688
|
+
|
|
689
|
+
// A DIFFERENT subject is a different key — the dedupe never collapses two
|
|
690
|
+
// real refinements into one delivery.
|
|
691
|
+
const other = harness({
|
|
692
|
+
target: { contactId: "c2", userId: "u2", email: "b@acme.com" },
|
|
693
|
+
});
|
|
694
|
+
await runRefineChain(other.deps, { userId: "u2" });
|
|
695
|
+
assert.notEqual(other.emits[0]?.dedupeKey, first.emits[0]?.dedupeKey);
|
|
696
|
+
});
|
|
697
|
+
|
|
698
|
+
test("AC 3: a genuinely NEW lookup of the same subject is NOT absorbed — the TTL-refresh case", async () => {
|
|
699
|
+
// 90 days on, the TTL expires, the vendor is asked again and reports a new
|
|
700
|
+
// job title. `webhook_deliveries` has a PERMANENT unique (endpointId,
|
|
701
|
+
// dedupeKey) index and nothing ever deletes a delivery row, so a key made
|
|
702
|
+
// only of (provider, kind, key) would silence this refinement forever — the
|
|
703
|
+
// exact event a CRM sync subscriber exists to receive.
|
|
704
|
+
const LATER = new Date(NOW.getTime() + 90 * 24 * 60 * 60 * 1000);
|
|
705
|
+
const today = harness({});
|
|
706
|
+
const ninetyDaysOn = harness({});
|
|
707
|
+
ninetyDaysOn.deps.now = () => LATER;
|
|
708
|
+
|
|
709
|
+
await runRefineChain(today.deps, SUBJECT);
|
|
710
|
+
await runRefineChain(ninetyDaysOn.deps, SUBJECT);
|
|
711
|
+
|
|
712
|
+
assert.notEqual(today.emits[0]?.dedupeKey, ninetyDaysOn.emits[0]?.dedupeKey);
|
|
713
|
+
assert.equal(
|
|
714
|
+
ninetyDaysOn.emits[0]?.dedupeKey,
|
|
715
|
+
`refine:fake:email:a@acme.com:${LATER.toISOString()}`,
|
|
716
|
+
);
|
|
717
|
+
|
|
718
|
+
// ...and the instant is serialized stably, not as a locale string.
|
|
719
|
+
assert.match(
|
|
720
|
+
today.emits[0]?.dedupeKey ?? "",
|
|
721
|
+
/:\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
|
|
722
|
+
);
|
|
723
|
+
});
|
|
724
|
+
|
|
725
|
+
test("AC 3: a re-drive never reaches the emit anyway — the LEDGER GATE returns `cached` first", async () => {
|
|
726
|
+
// The instant in the key costs nothing on the re-drive side, because the
|
|
727
|
+
// dedupe is not what defends a re-drive. Attempt 2 finds the row attempt 1
|
|
728
|
+
// wrote and returns `cached` (refine-chain.ts step 3), which has no emit at
|
|
729
|
+
// all — so a duplicate delivery needs a concurrent race, not a retry.
|
|
730
|
+
const redrive = harness({
|
|
731
|
+
ledgerRow: unexpired("found", { refined_title: "CTO" }),
|
|
732
|
+
});
|
|
733
|
+
|
|
734
|
+
assert.equal((await runRefineChain(redrive.deps, SUBJECT)).status, "cached");
|
|
735
|
+
assert.deepEqual(redrive.emits, []);
|
|
736
|
+
});
|
|
737
|
+
|
|
738
|
+
test("AC 11 holds WITH the emit: the durable journal is identical on every verdict", async () => {
|
|
739
|
+
// The emit sits on the already-decided `refined` verdict inside the gate
|
|
740
|
+
// closure and issues no durable call, so adding it may not move the journal.
|
|
741
|
+
const refined = harness({});
|
|
742
|
+
const cached = harness({ ledgerRow: unexpired("found", { a: 1 }) });
|
|
743
|
+
const notFound = harness({ ledgerRow: unexpired("not_found") });
|
|
744
|
+
const skipped = harness({ target: null });
|
|
745
|
+
|
|
746
|
+
const { results } = await assertUniformDurableJournal({
|
|
747
|
+
paths: {
|
|
748
|
+
refined: () => runRefineChain(refined.deps, SUBJECT),
|
|
749
|
+
cached: () => runRefineChain(cached.deps, SUBJECT),
|
|
750
|
+
not_found: () => runRefineChain(notFound.deps, SUBJECT),
|
|
751
|
+
skipped: () => runRefineChain(skipped.deps, SUBJECT),
|
|
752
|
+
},
|
|
753
|
+
expectedJournal: ['memoize:["journeyRefine:run-1:u1:u1"]'],
|
|
754
|
+
});
|
|
755
|
+
|
|
756
|
+
assert.equal(results.refined?.status, "refined");
|
|
757
|
+
assert.equal(results.cached?.status, "cached");
|
|
758
|
+
assert.equal(results.not_found?.status, "not_found");
|
|
759
|
+
assert.equal(results.skipped?.status, "skipped");
|
|
760
|
+
assert.equal(refined.emits.length, 1);
|
|
761
|
+
assert.equal(cached.emits.length, 0);
|
|
762
|
+
assert.equal(notFound.emits.length, 0);
|
|
763
|
+
assert.equal(skipped.emits.length, 0);
|
|
764
|
+
});
|