@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,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 =
|
|
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
|
+
});
|