@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.
@@ -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
+ }