@hogsend/engine 0.41.0 → 0.42.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.
@@ -2,6 +2,10 @@ import { contacts, userEvents } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import { and, count, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
+ import {
6
+ eventNameEntrySchema,
7
+ listEventNameVocabulary,
8
+ } from "../../lib/event-names.js";
5
9
  import { ingestEvent } from "../../lib/ingestion.js";
6
10
 
7
11
  const eventSchema = z.object({
@@ -114,6 +118,41 @@ const getRoute = createRoute({
114
118
  },
115
119
  });
116
120
 
121
+ const namesRoute = createRoute({
122
+ method: "get",
123
+ path: "/names",
124
+ tags: ["Admin — Events"],
125
+ summary: "List event names (observed + declared)",
126
+ description:
127
+ "Best-effort event-name vocabulary for authoring triggers, waits, and " +
128
+ "exitOn rules. Event names are an OPEN vocabulary (no closed registry " +
129
+ "exists anywhere in the engine), so this merges: events actually " +
130
+ "observed in the event store (with occurrence counts, most recently " +
131
+ "seen first) and events referenced as code-journey or blueprint " +
132
+ "triggers. Any other event name is also valid — it just hasn't been " +
133
+ "seen yet.",
134
+ request: {
135
+ query: z.object({
136
+ // Case-insensitive substring filter on the event name.
137
+ search: z.string().min(1).optional(),
138
+ limit: z.coerce.number().int().min(1).max(200).default(100),
139
+ }),
140
+ },
141
+ responses: {
142
+ 200: {
143
+ content: {
144
+ "application/json": {
145
+ schema: z.object({
146
+ note: z.string(),
147
+ events: z.array(eventNameEntrySchema),
148
+ }),
149
+ },
150
+ },
151
+ description: "Merged observed + declared event-name vocabulary",
152
+ },
153
+ },
154
+ });
155
+
117
156
  const exitSchema = z.object({
118
157
  journeyId: z.string(),
119
158
  stateId: z.string(),
@@ -217,6 +256,22 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
217
256
  200,
218
257
  );
219
258
  })
259
+ // Registered before getRoute so the literal "names" is never captured as
260
+ // an {id}. Delegates to the shared vocabulary helper (lib/event-names.ts)
261
+ // — the same implementation the blueprint tools' `list_events` serves, so
262
+ // the HTTP surface and the in-process tool can never drift.
263
+ .openapi(namesRoute, async (c) => {
264
+ const { db, registry } = c.get("container");
265
+ const { search, limit } = c.req.valid("query");
266
+
267
+ const { note, events } = await listEventNameVocabulary({
268
+ db,
269
+ registry,
270
+ search,
271
+ limit,
272
+ });
273
+ return c.json({ note, events }, 200);
274
+ })
220
275
  .openapi(getRoute, async (c) => {
221
276
  const { db } = c.get("container");
222
277
  const { id } = c.req.valid("param");
@@ -5,9 +5,11 @@ import {
5
5
  BlueprintUnreachableNodeError,
6
6
  type DurationObject,
7
7
  evaluateCondition,
8
+ isReservedEventName,
8
9
  type JourneyEdge,
9
10
  type JourneyNode,
10
11
  type PropertyCondition,
12
+ RESERVED_EVENT_NAMESPACES,
11
13
  serializeBlueprintError,
12
14
  validateBlueprintGraph,
13
15
  } from "@hogsend/core";
@@ -310,6 +312,17 @@ export async function walkBlueprintGraph(
310
312
  "event",
311
313
  node.meta?.event,
312
314
  );
315
+ // Save-time validation rejects reserved namespaces since the check
316
+ // was added, but the graph column is jsonb — a row saved BEFORE the
317
+ // rule (or written out-of-band) must still never forge an
318
+ // engine-emitted event through the ingest pipeline.
319
+ if (isReservedEventName(event)) {
320
+ throw new BlueprintNodeExecutionError(
321
+ blueprintId,
322
+ node.id,
323
+ `trigger node event "${event}" uses a reserved namespace (${RESERVED_EVENT_NAMESPACES.join("/")})`,
324
+ );
325
+ }
313
326
  await ctx.trigger({
314
327
  event,
315
328
  userId: user.id,
@@ -358,37 +371,12 @@ export async function walkBlueprintGraph(
358
371
  // code journey's run() returning normally.
359
372
  return null;
360
373
 
361
- case "end-exited": {
362
- // Terminal: flip the row terminal the same way checkExits does, then
363
- // abort the run via the SAME control-flow signal a mid-wait exit
364
- // uses — the lifecycle catch maps it to { status: "exited" } without
365
- // a "failed" write or a journey:failed push. Idempotent on replay
366
- // (the guarded update no-ops once terminal).
367
- const [exited] = await db
368
- .update(journeyStates)
369
- .set({
370
- status: "exited",
371
- exitedAt: new Date(),
372
- updatedAt: new Date(),
373
- })
374
- .where(
375
- and(
376
- eq(journeyStates.id, user.stateId),
377
- notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
378
- ),
379
- )
380
- .returning({ id: journeyStates.id });
381
- if (exited) {
382
- logTransition({
383
- db,
384
- journeyStateId: user.stateId,
385
- from: null,
386
- to: "end-exited",
387
- action: "exited",
388
- });
389
- }
390
- throw new JourneyExitedError(user.stateId);
391
- }
374
+ case "end-exited":
375
+ // Terminal "exited": the SAME primitive a code journey (and promoted
376
+ // blueprint code) calls — a guarded flip to "exited" plus the
377
+ // JourneyExitedError the lifecycle maps to { status: "exited" } without
378
+ // a "failed" write or a journey:failed push. One mechanism, not two.
379
+ return ctx.exit();
392
380
 
393
381
  case "end-failed":
394
382
  // Terminal: matches a code journey's thrown error — the lifecycle
@@ -459,6 +447,75 @@ export async function walkBlueprintGraph(
459
447
  }
460
448
  }
461
449
 
450
+ /**
451
+ * A REPLAY (resume recovered by run id) that can no longer execute — the
452
+ * blueprint row vanished, or its stored graph now fails execution-time
453
+ * re-validation — must FAIL the recovered enrollment, not return `skipped`
454
+ * and leave a waiting/active row stranded non-terminal forever. Recovery is by
455
+ * the replay-stable Hatchet run id + journeyId, exactly as `executeJourneyRun`
456
+ * recovers an enrollment; a FRESH (never-enrolled) dispatch recovers nothing
457
+ * and the caller keeps returning `skipped` unchanged.
458
+ *
459
+ * Mirrors the failed path in `executeJourneyRun`: a guarded flip to "failed"
460
+ * (`notInArray(TERMINAL_STATUSES)`, so an already-terminal row is never
461
+ * clobbered) plus the same `journey:failed` side effects (structured
462
+ * errorMessage, failed transition, event push). Returns whether an existing
463
+ * enrollment was recovered for this run.
464
+ */
465
+ async function failRecoveredBlueprintEnrollment(opts: {
466
+ db: Database;
467
+ blueprintId: string;
468
+ workflowRunId: string;
469
+ userId: string;
470
+ message: string;
471
+ }): Promise<boolean> {
472
+ const { db, blueprintId, workflowRunId, userId, message } = opts;
473
+ if (!workflowRunId) return false;
474
+
475
+ const recovered = await db.query.journeyStates.findFirst({
476
+ where: and(
477
+ eq(journeyStates.hatchetRunId, workflowRunId),
478
+ eq(journeyStates.journeyId, blueprintId),
479
+ ),
480
+ });
481
+ if (!recovered) return false;
482
+
483
+ const [failed] = await db
484
+ .update(journeyStates)
485
+ .set({ status: "failed", errorMessage: message, updatedAt: new Date() })
486
+ .where(
487
+ and(
488
+ eq(journeyStates.id, recovered.id),
489
+ notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
490
+ ),
491
+ )
492
+ .returning({ id: journeyStates.id });
493
+ // Already terminal — nothing was stranded; the recovery still happened.
494
+ if (!failed) return true;
495
+
496
+ logger.error("blueprint replay failed the recovered enrollment", {
497
+ blueprintId,
498
+ stateId: recovered.id,
499
+ userId,
500
+ error: message,
501
+ });
502
+ logTransition({
503
+ db,
504
+ journeyStateId: recovered.id,
505
+ from: recovered.currentNodeId ?? null,
506
+ to: null,
507
+ action: "failed",
508
+ detail: { error: message },
509
+ });
510
+ await hatchet.events.push("journey:failed", {
511
+ journeyId: blueprintId,
512
+ stateId: recovered.id,
513
+ userId,
514
+ error: message,
515
+ });
516
+ return true;
517
+ }
518
+
462
519
  /**
463
520
  * The event payload `checkBlueprintTriggers` pushes for each matching enabled
464
521
  * blueprint — one push per (blueprint, user) enrollment attempt.
@@ -498,6 +555,11 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
498
555
  fn: async (input: BlueprintRunPayload, hatchetCtx) => {
499
556
  const db = getDb();
500
557
  const blueprintId = input.blueprintId as string;
558
+ // Recovery anchor: a REPLAY resumes under the SAME run id, so a blueprint
559
+ // that has since vanished / gone invalid must fail its recovered
560
+ // enrollment rather than strand it (see failRecoveredBlueprintEnrollment).
561
+ const workflowRunId = hatchetCtx.workflowRunId();
562
+ const userId = input.userId as string;
501
563
 
502
564
  const row = await db.query.journeyBlueprints.findFirst({
503
565
  where: eq(journeyBlueprints.id, blueprintId),
@@ -506,7 +568,21 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
506
568
  logger.warn("blueprint run skipped: blueprint not found", {
507
569
  blueprintId,
508
570
  });
509
- return { status: "skipped", reason: "blueprint_not_found" };
571
+ const failed = await failRecoveredBlueprintEnrollment({
572
+ db,
573
+ blueprintId,
574
+ workflowRunId,
575
+ userId,
576
+ message: JSON.stringify(
577
+ serializeBlueprintError(
578
+ blueprintId,
579
+ new Error("blueprint row not found at execution time"),
580
+ ),
581
+ ),
582
+ });
583
+ return failed
584
+ ? { status: "failed", reason: "blueprint_not_found" }
585
+ : { status: "skipped", reason: "blueprint_not_found" };
510
586
  }
511
587
 
512
588
  // Defense-in-depth (spec §6): a saved blueprint already passed
@@ -518,7 +594,21 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
518
594
  "blueprint run skipped: stored graph failed execution-time validation",
519
595
  { blueprintId, issues: validated.issues },
520
596
  );
521
- return { status: "skipped", reason: "invalid_blueprint_graph" };
597
+ const failed = await failRecoveredBlueprintEnrollment({
598
+ db,
599
+ blueprintId,
600
+ workflowRunId,
601
+ userId,
602
+ message: JSON.stringify(
603
+ serializeBlueprintError(
604
+ blueprintId,
605
+ new Error("stored graph failed execution-time re-validation"),
606
+ ),
607
+ ),
608
+ });
609
+ return failed
610
+ ? { status: "failed", reason: "invalid_blueprint_graph" }
611
+ : { status: "skipped", reason: "invalid_blueprint_graph" };
522
612
  }
523
613
 
524
614
  // Version pin (spec §12): the version this run enrolled under, recorded
@@ -551,6 +641,11 @@ export const journeyBlueprintInterpreter = hatchet.durableTask({
551
641
  } satisfies EventPayloadInput,
552
642
  hatchetCtx,
553
643
  extraContext: { __blueprintVersion: enrolledVersion },
644
+ // Serialize this enrollment insert against a concurrent graph edit
645
+ // (updateBlueprint takes the SAME advisory lock around its in-flight
646
+ // count + update) so the run cannot become active between that count and
647
+ // the graph write — the desync window the in-flight gate exists to close.
648
+ serializeEnrollment: true,
554
649
  // Structured errorMessage (spec §6.1): { blueprintId, nodeId, message }
555
650
  // as JSON in the SAME journeyStates.errorMessage field code journeys
556
651
  // use, so Studio's error display needs no blueprint-specific branching.