@hogsend/engine 0.53.0 → 0.54.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/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/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- 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 +67 -0
- package/src/lib/enrichment-providers-from-env.ts +85 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -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/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
|
@@ -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
|
+
}
|