@hogsend/engine 0.52.0 → 0.52.1

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.52.0",
3
+ "version": "0.52.1",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,17 +53,17 @@
53
53
  "svix": "^1.95.1",
54
54
  "winston": "^3.19.0",
55
55
  "zod": "^4.4.3",
56
- "@hogsend/attribution": "^0.52.0",
57
- "@hogsend/core": "^0.52.0",
58
- "@hogsend/db": "^0.52.0",
59
- "@hogsend/email": "^0.52.0",
60
- "@hogsend/plugin-posthog": "^0.52.0",
61
- "@hogsend/plugin-resend": "^0.52.0",
62
- "@hogsend/sms": "^0.52.0"
56
+ "@hogsend/attribution": "^0.52.1",
57
+ "@hogsend/core": "^0.52.1",
58
+ "@hogsend/db": "^0.52.1",
59
+ "@hogsend/email": "^0.52.1",
60
+ "@hogsend/plugin-posthog": "^0.52.1",
61
+ "@hogsend/plugin-resend": "^0.52.1",
62
+ "@hogsend/sms": "^0.52.1"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-postmark": "^0.52.0",
66
- "@hogsend/plugin-twilio": "^0.52.0"
65
+ "@hogsend/plugin-postmark": "^0.52.1",
66
+ "@hogsend/plugin-twilio": "^0.52.1"
67
67
  },
68
68
  "devDependencies": {
69
69
  "@types/node": "^22.15.3",
@@ -70,7 +70,7 @@ import {
70
70
  registerRecordLabel,
71
71
  } from "./journey-boundary.js";
72
72
  import { logTransition } from "./journey-log.js";
73
- import { readRecordedValue, recordOnce } from "./record-once.js";
73
+ import { recordOnce } from "./record-once.js";
74
74
 
75
75
  /** Journey statuses that are terminal — a journey in any of these must never be
76
76
  * resurrected back to "active" by a wait resuming. Exported so the durable task
@@ -383,28 +383,25 @@ export function createJourneyContext(
383
383
  // and the live CEL filter swap their user predicate for the group one).
384
384
  groupScope?: { type: string; key: string },
385
385
  ): Promise<WaitForEventResult> => {
386
- // Terminal mark (the digest pattern): the recorded outcome — NOT the
387
- // deadline — is what makes this wait replay-stable. `waitDeadline` is a
388
- // shared column cleared at resolution so the NEXT wait site can mint its
389
- // own, which means a replay-from-top of an ALREADY-RESOLVED wait re-derives
390
- // a shifted scan window in which the resolving row is typically invisible —
391
- // a re-armed wait could then flip to the timeout branch (duplicate-but-
392
- // different sends downstream: the exact divergence class this engine's
393
- // replay-safety design forbids). So the outcome is frozen set-once under
394
- // `__waits__` and a replay returns it verbatim before touching the
395
- // deadline. Registering the label makes an intra-run duplicate wait label
396
- // a loud authoring error instead of a silent stale-outcome replay.
386
+ // Replay stability (the digest pattern, applied to CONTROL FLOW): Hatchet's
387
+ // journal is positional AND param-checked for COMPLETED entries, so a
388
+ // replay-from-top must re-issue exactly the durable calls the original run
389
+ // made, with identical parameters — skipping the wait (an early-returned
390
+ // recorded outcome) or re-computing a sleep duration from the wall clock
391
+ // makes the next durable call land on the wrong journal slot and the whole
392
+ // run fails with a non-determinism error (#591). The rule here is therefore
393
+ // NEVER skip a durable call; instead FREEZE every non-journaled input the
394
+ // control flow branches on — each scan result (`<nodeId>:scan:<seq>`), each
395
+ // arm's remaining-ms (`<nodeId>:arm:<seq>`, which is also the sleep param),
396
+ // and the deadline itself (`<nodeId>:deadline`; the shared `waitDeadline`
397
+ // column is cleared at resolution so it can't be the replay truth) — so the
398
+ // replay walks the identical branch sequence, Hatchet answers each re-issued
399
+ // waitFor from the journal instantly, and `recordOnce` at the end returns
400
+ // the frozen outcome verbatim. Registering the label makes an intra-run
401
+ // duplicate wait label a loud authoring error instead of a silent
402
+ // stale-outcome replay.
397
403
  registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
398
404
  const outcomeKey = `${nodeId}:result`;
399
- const priorOutcome = await readRecordedValue({
400
- db,
401
- stateId,
402
- namespace: "__waits__",
403
- key: outcomeKey,
404
- });
405
- if (priorOutcome !== undefined) {
406
- return priorOutcome as WaitForEventResult;
407
- }
408
405
  const recordOutcome = (o: WaitForEventResult) =>
409
406
  recordOnce({
410
407
  db,
@@ -414,16 +411,28 @@ export function createJourneyContext(
414
411
  compute: () => o,
415
412
  });
416
413
 
417
- // Durable deadline: read-first / set-once.
414
+ // Durable deadline: read-first / set-once. The RECORDED copy is the replay
415
+ // truth; the `waitDeadline` column is still written for observability and
416
+ // as the pre-record source for runs armed by an engine without the record
417
+ // (mixed-version replay keeps the original deadline instead of extending).
418
418
  const stateRow = await db
419
419
  .select({ waitDeadline: journeyStates.waitDeadline })
420
420
  .from(journeyStates)
421
421
  .where(eq(journeyStates.id, stateId))
422
422
  .limit(1);
423
423
  const storedDeadline = stateRow[0]?.waitDeadline ?? null;
424
- const deadline = storedDeadline
425
- ? new Date(storedDeadline)
426
- : new Date(Date.now() + durationToMs(timeout));
424
+ const deadlineIso = await recordOnce<string>({
425
+ db,
426
+ stateId,
427
+ namespace: "__waits__",
428
+ key: `${nodeId}:deadline`,
429
+ compute: () =>
430
+ (storedDeadline
431
+ ? new Date(storedDeadline)
432
+ : new Date(Date.now() + durationToMs(timeout))
433
+ ).toISOString(),
434
+ });
435
+ const deadline = new Date(deadlineIso);
427
436
  if (!storedDeadline) {
428
437
  await db
429
438
  .update(journeyStates)
@@ -489,8 +498,23 @@ export function createJourneyContext(
489
498
  return null;
490
499
  };
491
500
 
501
+ // Every scan is frozen set-once in call order (misses included — a stored
502
+ // `null` is distinguishable from "not recorded"). On replay the scan
503
+ // sequence returns verbatim, so the loop takes the original branches even
504
+ // though the resolving row is NOW visible in the DB (or a once-visible row
505
+ // aged out of the window).
506
+ let scanSeq = 0;
507
+ const recordedScan = () =>
508
+ recordOnce<Awaited<ReturnType<typeof scanForMatch>>>({
509
+ db,
510
+ stateId,
511
+ namespace: "__waits__",
512
+ key: `${nodeId}:scan:${scanSeq++}`,
513
+ compute: scanForMatch,
514
+ });
515
+
492
516
  // Immediate hit (incl. the lookback window) — resolve without a state flip.
493
- const preHit = await scanForMatch();
517
+ const preHit = await recordedScan();
494
518
  if (preHit) {
495
519
  await clearDeadline();
496
520
  return recordOutcome({ timedOut: false, ...preHit });
@@ -499,8 +523,9 @@ export function createJourneyContext(
499
523
  await enterWait(nodeId, "wait");
500
524
 
501
525
  let outcome: WaitForEventResult;
526
+ let armSeq = 0;
502
527
  while (true) {
503
- const hit = await scanForMatch();
528
+ const hit = await recordedScan();
504
529
  if (hit) {
505
530
  outcome = { timedOut: false, ...hit };
506
531
  break;
@@ -518,7 +543,16 @@ export function createJourneyContext(
518
543
  throw new JourneyExitedError(stateId);
519
544
  }
520
545
 
521
- const remainingMs = deadline.getTime() - Date.now();
546
+ // Frozen per arm: both the conclude-without-arming decision AND the
547
+ // sleep-branch parameter must replay identically (a completed waitFor's
548
+ // journal entry is param-checked).
549
+ const remainingMs = await recordOnce<number>({
550
+ db,
551
+ stateId,
552
+ namespace: "__waits__",
553
+ key: `${nodeId}:arm:${armSeq++}`,
554
+ compute: () => deadline.getTime() - Date.now(),
555
+ });
522
556
  if (remainingMs <= 0) {
523
557
  outcome = { timedOut: true };
524
558
  break;
@@ -541,7 +575,7 @@ export function createJourneyContext(
541
575
  if (!("event" in fired)) {
542
576
  // Timeout branch — one final scan for an event landing exactly as the
543
577
  // sleep expired, then conclude.
544
- const last = await scanForMatch();
578
+ const last = await recordedScan();
545
579
  outcome = last ? { timedOut: false, ...last } : { timedOut: true };
546
580
  break;
547
581
  }
@@ -617,48 +651,65 @@ export function createJourneyContext(
617
651
  // can never re-push. A recent matching user_events row resolves the wait
618
652
  // immediately, payload included.
619
653
  if (lookback) {
620
- const since = new Date(
621
- (await refreshNow()).getTime() - durationToMs(lookback),
622
- );
623
- const recent = await db
624
- .select({
625
- properties: userEvents.properties,
626
- occurredAt: userEvents.occurredAt,
627
- })
628
- .from(userEvents)
629
- .where(
630
- and(
631
- eq(userEvents.userId, userId),
632
- eq(userEvents.event, event),
633
- gte(userEvents.occurredAt, since),
634
- ),
635
- )
636
- .orderBy(desc(userEvents.occurredAt))
637
- .limit(1);
638
- const row = recent[0];
639
- if (row) {
640
- const scalars = Object.fromEntries(
641
- Object.entries(row.properties ?? {}).filter(
642
- ([, v]) =>
643
- typeof v === "string" ||
644
- typeof v === "number" ||
645
- typeof v === "boolean" ||
646
- v === null,
647
- ),
648
- ) as NonNullable<WaitForEventResult["properties"]>;
649
- const occurredAt =
650
- row.occurredAt instanceof Date
651
- ? row.occurredAt.toISOString()
652
- : row.occurredAt
653
- ? String(row.occurredAt)
654
- : undefined;
655
- return {
656
- timedOut: false,
657
- properties: scalars,
658
- ...(occurredAt ? { occurredAt } : {}),
659
- // Lookback rows are user-scoped, so the actor IS the enrolled user.
660
- actorUserId: userId,
661
- };
654
+ // Recording under this node's key makes an intra-run duplicate wait
655
+ // label a loud error here too (same registry as the filtered leg).
656
+ registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
657
+ // Frozen set-once (miss included): whether the wait resolved via lookback
658
+ // is a control-flow branch in front of a durable call, so a replay must
659
+ // take the SAME side even though the window has shifted and the DB has
660
+ // moved on (the positional-journal rule — see the filtered leg above).
661
+ const lookbackHit = await recordOnce<WaitForEventResult | null>({
662
+ db,
663
+ stateId,
664
+ namespace: "__waits__",
665
+ key: `${nodeId}:lookback`,
666
+ compute: async () => {
667
+ const since = new Date(
668
+ (await refreshNow()).getTime() - durationToMs(lookback),
669
+ );
670
+ const recent = await db
671
+ .select({
672
+ properties: userEvents.properties,
673
+ occurredAt: userEvents.occurredAt,
674
+ })
675
+ .from(userEvents)
676
+ .where(
677
+ and(
678
+ eq(userEvents.userId, userId),
679
+ eq(userEvents.event, event),
680
+ gte(userEvents.occurredAt, since),
681
+ ),
682
+ )
683
+ .orderBy(desc(userEvents.occurredAt))
684
+ .limit(1);
685
+ const row = recent[0];
686
+ if (!row) return null;
687
+ const scalars = Object.fromEntries(
688
+ Object.entries(row.properties ?? {}).filter(
689
+ ([, v]) =>
690
+ typeof v === "string" ||
691
+ typeof v === "number" ||
692
+ typeof v === "boolean" ||
693
+ v === null,
694
+ ),
695
+ ) as NonNullable<WaitForEventResult["properties"]>;
696
+ const occurredAt =
697
+ row.occurredAt instanceof Date
698
+ ? row.occurredAt.toISOString()
699
+ : row.occurredAt
700
+ ? String(row.occurredAt)
701
+ : undefined;
702
+ return {
703
+ timedOut: false,
704
+ properties: scalars,
705
+ ...(occurredAt ? { occurredAt } : {}),
706
+ // Lookback rows are user-scoped, so the actor IS the enrolled user.
707
+ actorUserId: userId,
708
+ };
709
+ },
710
+ });
711
+ if (lookbackHit) {
712
+ return lookbackHit;
662
713
  }
663
714
  }
664
715