@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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.41.0",
3
+ "version": "0.42.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -15,6 +15,7 @@
15
15
  "./worker": "./src/worker.ts",
16
16
  "./auth": "./src/lib/auth.ts",
17
17
  "./create-admin": "./src/lib/create-admin.ts",
18
+ "./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
18
19
  "./package.json": "./package.json"
19
20
  },
20
21
  "files": [
@@ -31,6 +32,8 @@
31
32
  "@openrouter/ai-sdk-provider": "^2.9.1",
32
33
  "@scalar/hono-api-reference": "^0.10.19",
33
34
  "@t3-oss/env-core": "^0.13.11",
35
+ "@types/papaparse": "^5.5.2",
36
+ "@types/qrcode": "^1.5.6",
34
37
  "acorn": "^8.17.0",
35
38
  "acorn-walk": "^8.3.5",
36
39
  "ai": "^6.0.209",
@@ -46,19 +49,17 @@
46
49
  "svix": "^1.95.1",
47
50
  "winston": "^3.19.0",
48
51
  "zod": "^4.4.3",
49
- "@hogsend/core": "^0.41.0",
50
- "@hogsend/db": "^0.41.0",
51
- "@hogsend/email": "^0.41.0",
52
- "@hogsend/plugin-posthog": "^0.41.0",
53
- "@hogsend/plugin-resend": "^0.41.0"
52
+ "@hogsend/core": "^0.42.0",
53
+ "@hogsend/db": "^0.42.0",
54
+ "@hogsend/email": "^0.42.0",
55
+ "@hogsend/plugin-posthog": "^0.42.0",
56
+ "@hogsend/plugin-resend": "^0.42.0"
54
57
  },
55
58
  "optionalDependencies": {
56
- "@hogsend/plugin-postmark": "^0.41.0"
59
+ "@hogsend/plugin-postmark": "^0.42.0"
57
60
  },
58
61
  "devDependencies": {
59
62
  "@types/node": "^22.15.3",
60
- "@types/papaparse": "^5.5.2",
61
- "@types/qrcode": "^1.5.6",
62
63
  "tsx": "^4.22.3",
63
64
  "@repo/typescript-config": "0.0.0"
64
65
  },
package/src/index.ts CHANGED
@@ -307,6 +307,8 @@ export {
307
307
  type EnableBlueprintResult,
308
308
  enableBlueprint,
309
309
  findBlueprintRow,
310
+ type PromoteBlueprintResult,
311
+ promoteBlueprint,
310
312
  type SerializedBlueprint,
311
313
  serializeBlueprint,
312
314
  type UpdateBlueprintPatch,
@@ -615,6 +617,12 @@ export {
615
617
  resetListRegistry,
616
618
  setListRegistry,
617
619
  } from "./lists/registry-singleton.js";
620
+ // --- Journey blueprints: shared authoring-guide text (tools + @hogsend/mcp) ---
621
+ export {
622
+ BLUEPRINT_AUTHORING_GUIDE,
623
+ GRAPH_FORMAT,
624
+ ISSUE_LOOP_HINT,
625
+ } from "./mcp/authoring-guide.js";
618
626
  // --- Journey blueprints: agent-facing authoring tools (spec §9, phase 4) ---
619
627
  export {
620
628
  type BlueprintToolDefinition,
@@ -624,6 +632,12 @@ export {
624
632
  type JourneyBlueprintTools,
625
633
  type JourneyBlueprintToolsOptions,
626
634
  } from "./mcp/blueprint-tools.js";
635
+ export {
636
+ createRateLimit,
637
+ type RateLimitOptions,
638
+ } from "./middleware/rate-limit.js";
639
+ // --- Middleware (consumer-mounted routes, e.g. the @hogsend/mcp hosted route) ---
640
+ export { requireAdmin } from "./middleware/require-admin.js";
627
641
  // --- Webhook sources ---
628
642
  export {
629
643
  type DefinedWebhookSource,
@@ -18,6 +18,7 @@ import {
18
18
  } from "@hogsend/db";
19
19
  import { and, eq, inArray, notInArray, sql } from "drizzle-orm";
20
20
  import { getAnalytics } from "../lib/analytics-singleton.js";
21
+ import { blueprintGraphLock } from "../lib/blueprint-lock.js";
21
22
  import { getDb } from "../lib/db.js";
22
23
  import {
23
24
  checkEmailPreferences,
@@ -122,24 +123,48 @@ export async function insertEnrollment(opts: {
122
123
  journeyId: string;
123
124
  context: Record<string, unknown>;
124
125
  hatchetRunId?: string;
126
+ /**
127
+ * Blueprint runs serialize this insert against a concurrent GRAPH EDIT via a
128
+ * transaction-scoped advisory lock — `updateBlueprint` takes the SAME lock
129
+ * ({@link blueprintGraphLock}) around its in-flight count + guarded update,
130
+ * so an enrollment cannot become active/waiting in the window between that
131
+ * count and update. Code journeys have no mutable graph, so they insert
132
+ * lock-free (the default).
133
+ */
134
+ serializeWithGraphLock?: boolean;
125
135
  }): Promise<JourneyStateRow | undefined> {
126
- const [row] = await opts.db
127
- .insert(journeyStates)
128
- .values({
129
- userId: opts.userId,
130
- userEmail: opts.userEmail,
131
- journeyId: opts.journeyId,
132
- currentNodeId: "start",
133
- status: "active",
134
- context: opts.context,
135
- hatchetRunId: opts.hatchetRunId,
136
- })
137
- .onConflictDoNothing({
138
- target: [journeyStates.userId, journeyStates.journeyId],
139
- where: sql`status IN ('active', 'waiting')`,
140
- })
141
- .returning();
142
- return row;
136
+ const values = {
137
+ userId: opts.userId,
138
+ userEmail: opts.userEmail,
139
+ journeyId: opts.journeyId,
140
+ currentNodeId: "start",
141
+ status: "active" as const,
142
+ context: opts.context,
143
+ hatchetRunId: opts.hatchetRunId,
144
+ };
145
+ const onConflict = {
146
+ target: [journeyStates.userId, journeyStates.journeyId],
147
+ where: sql`status IN ('active', 'waiting')`,
148
+ };
149
+
150
+ if (!opts.serializeWithGraphLock) {
151
+ const [row] = await opts.db
152
+ .insert(journeyStates)
153
+ .values(values)
154
+ .onConflictDoNothing(onConflict)
155
+ .returning();
156
+ return row;
157
+ }
158
+
159
+ return opts.db.transaction(async (tx) => {
160
+ await tx.execute(blueprintGraphLock(opts.journeyId));
161
+ const [row] = await tx
162
+ .insert(journeyStates)
163
+ .values(values)
164
+ .onConflictDoNothing(onConflict)
165
+ .returning();
166
+ return row;
167
+ });
143
168
  }
144
169
 
145
170
  export interface ExecuteJourneyRunOptions {
@@ -162,6 +187,13 @@ export interface ExecuteJourneyRunOptions {
162
187
  * interpreter pins `__blueprintVersion` here (spec §12).
163
188
  */
164
189
  extraContext?: Record<string, unknown>;
190
+ /**
191
+ * Serialize the enrollment insert against a concurrent blueprint graph edit
192
+ * with a transaction-scoped advisory lock (spec §12). Set by the blueprint
193
+ * interpreter — the blueprint id IS the journeyId, so the lock key matches
194
+ * `updateBlueprint`'s. Code journeys leave it unset (no mutable graph).
195
+ */
196
+ serializeEnrollment?: boolean;
165
197
  /**
166
198
  * Serialize a run failure into `journeyStates.errorMessage`. Defaults to the
167
199
  * error's message; the blueprint interpreter writes the structured
@@ -295,6 +327,7 @@ export async function executeJourneyRun(
295
327
  ? { ...properties, ...options.extraContext }
296
328
  : properties,
297
329
  hatchetRunId: workflowRunId,
330
+ serializeWithGraphLock: options.serializeEnrollment,
298
331
  });
299
332
  if (!state) {
300
333
  return { status: "skipped", reason: "already_active" };
@@ -1089,6 +1089,38 @@ export function createJourneyContext(
1089
1089
  });
1090
1090
  },
1091
1091
 
1092
+ async exit(reason?: string): Promise<never> {
1093
+ // Terminal "exited": a guarded flip (never clobber an already-terminal
1094
+ // row) plus the SAME JourneyExitedError control-flow signal a mid-wait
1095
+ // exitOn raises — the run lifecycle maps it to { status: "exited" } with
1096
+ // no "failed"/"completed" write and no journey:* event. This is the
1097
+ // single mechanism the blueprint interpreter's end-exited node drives too
1098
+ // (and the form promote-to-code emits), so there is one path, not two.
1099
+ const now = new Date();
1100
+ const [exited] = await db
1101
+ .update(journeyStates)
1102
+ .set({ status: "exited", exitedAt: now, updatedAt: now })
1103
+ .where(
1104
+ and(
1105
+ eq(journeyStates.id, stateId),
1106
+ notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
1107
+ ),
1108
+ )
1109
+ .returning({ id: journeyStates.id });
1110
+ if (exited) {
1111
+ // Fire-and-forget exit transition (best-effort; never affects the run).
1112
+ logTransition({
1113
+ db,
1114
+ journeyStateId: stateId,
1115
+ from: getJourneyBoundary()?.currentLabel ?? null,
1116
+ to: "end-exited",
1117
+ action: "exited",
1118
+ ...(reason ? { detail: { reason } } : {}),
1119
+ });
1120
+ }
1121
+ throw new JourneyExitedError(stateId);
1122
+ },
1123
+
1092
1124
  async now() {
1093
1125
  return refreshNow();
1094
1126
  },
@@ -0,0 +1,21 @@
1
+ import { type SQL, sql } from "drizzle-orm";
2
+
3
+ /**
4
+ * Transaction-scoped advisory lock serializing a blueprint's graph EDIT
5
+ * (`updateBlueprint`'s in-flight count + guarded update) against a new
6
+ * ENROLLMENT insert for the same blueprint (`insertEnrollment` for a blueprint
7
+ * run). Both sides take THIS lock inside their transaction, so the count and
8
+ * the insert cannot interleave: an enrollment either lands before the count
9
+ * (the edit then sees it and rejects with `in_flight`) or after the graph
10
+ * commits (a fresh run walking the NEW graph) — never mid-flight, which is the
11
+ * interleaving that would desync the positional Hatchet replay journal for a
12
+ * run suspended between the count and the update.
13
+ *
14
+ * `hashtext` folds the id into the int4 the single-arg `pg_advisory_xact_lock`
15
+ * overload casts to bigint (same pattern as `contacts.ts`/`boot-api-key.ts`);
16
+ * the `bp-graph:` prefix namespaces it away from the codebase's other advisory
17
+ * locks. Xact-scoped — released on commit/rollback, no manual unlock.
18
+ */
19
+ export function blueprintGraphLock(blueprintId: string): SQL {
20
+ return sql`SELECT pg_advisory_xact_lock(hashtext(${`bp-graph:${blueprintId}`}))`;
21
+ }