@hogsend/engine 0.54.0 → 0.56.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.54.0",
3
+ "version": "0.56.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,18 +53,18 @@
53
53
  "svix": "^1.95.1",
54
54
  "winston": "^3.19.0",
55
55
  "zod": "^4.4.3",
56
- "@hogsend/attribution": "^0.54.0",
57
- "@hogsend/core": "^0.54.0",
58
- "@hogsend/db": "^0.54.0",
59
- "@hogsend/email": "^0.54.0",
60
- "@hogsend/plugin-posthog": "^0.54.0",
61
- "@hogsend/plugin-resend": "^0.54.0",
62
- "@hogsend/sms": "^0.54.0"
56
+ "@hogsend/attribution": "^0.56.0",
57
+ "@hogsend/core": "^0.56.0",
58
+ "@hogsend/db": "^0.56.0",
59
+ "@hogsend/email": "^0.56.0",
60
+ "@hogsend/plugin-posthog": "^0.56.0",
61
+ "@hogsend/plugin-resend": "^0.56.0",
62
+ "@hogsend/sms": "^0.56.0"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-apollo": "^0.54.0",
66
- "@hogsend/plugin-postmark": "^0.54.0",
67
- "@hogsend/plugin-twilio": "^0.54.0"
65
+ "@hogsend/plugin-apollo": "^0.56.0",
66
+ "@hogsend/plugin-postmark": "^0.56.0",
67
+ "@hogsend/plugin-twilio": "^0.56.0"
68
68
  },
69
69
  "devDependencies": {
70
70
  "@types/node": "^22.15.3",
@@ -51,6 +51,16 @@ export async function checkBucketMembership(opts: {
51
51
  logger: Logger;
52
52
  userId: string;
53
53
  userEmail: string | null;
54
+ /**
55
+ * The subject contact's resolved row id (`contacts.id`) — `ingestEvent` has
56
+ * already resolved the contact before calling us, so it threads the id here
57
+ * and we carry it into every `emitBucketTransition` as the ENGINE-INTERNAL
58
+ * provenance pin. Without it, a transition for a contact whose canonical key
59
+ * is its `anonymous_id` re-ingests a bare `userId` and mints a phantom
60
+ * `external_id` twin (issue #608). Optional: a caller without a resolved
61
+ * contact degrades to the pin-less emit.
62
+ */
63
+ contactId?: string;
54
64
  event: string;
55
65
  /**
56
66
  * D2: the event payload — candidate-narrowing ONLY. It NO LONGER participates
@@ -62,6 +72,14 @@ export async function checkBucketMembership(opts: {
62
72
  * the very first event after a property change evaluates correctly (risk 7).
63
73
  */
64
74
  contactProperties?: Record<string, unknown>;
75
+ /**
76
+ * Extra property NAMES for candidate-narrowing ONLY — never overlaid on the
77
+ * contact row for value eval. A producer whose write patch omits a key it
78
+ * nonetheless changed (refinement's fill-if-absent drops already-held facts to
79
+ * avoid clobbering first-party data) lists those names here so their fit
80
+ * buckets are still re-checked against live contact state.
81
+ */
82
+ touchProperties?: string[];
65
83
  /** Optional override; defaults to the process bucket-registry singleton. */
66
84
  bucketRegistry?: ReturnType<typeof getBucketRegistrySingleton>;
67
85
  }): Promise<BucketTransition[]> {
@@ -71,9 +89,11 @@ export async function checkBucketMembership(opts: {
71
89
  hatchet,
72
90
  logger,
73
91
  userId,
92
+ contactId,
74
93
  event,
75
94
  eventProperties,
76
95
  contactProperties: contactPropertiesPatch,
96
+ touchProperties,
77
97
  } = opts;
78
98
  // The caller's email comes verbatim from the raw event payload — normalize
79
99
  // ONCE here so the membership row, the emitted bucket:* transition events,
@@ -107,6 +127,10 @@ export async function checkBucketMembership(opts: {
107
127
  for (const key of [
108
128
  ...Object.keys(eventProperties ?? {}),
109
129
  ...Object.keys(contactPropertiesPatch ?? {}),
130
+ // Names-only touches (e.g. refinement's fill-if-absent dropped facts) surface
131
+ // a fit bucket here so it is re-checked against live contact state below,
132
+ // even though the value is not in this ingest's write patch.
133
+ ...(touchProperties ?? []),
110
134
  ]) {
111
135
  for (const bucket of bucketRegistry.getByReferencedProperty(key)) {
112
136
  candidateMap.set(bucket.id, bucket);
@@ -209,6 +233,7 @@ export async function checkBucketMembership(opts: {
209
233
  bucket,
210
234
  userId,
211
235
  userEmail,
236
+ contactId,
212
237
  });
213
238
  if (transition) transitions.push(transition);
214
239
  } else if (wasMember && isMember) {
@@ -227,6 +252,7 @@ export async function checkBucketMembership(opts: {
227
252
  active,
228
253
  userId,
229
254
  userEmail,
255
+ contactId,
230
256
  });
231
257
  if (transition) transitions.push(transition);
232
258
  }
@@ -244,8 +270,19 @@ async function handleJoin(opts: {
244
270
  bucket: BucketMeta;
245
271
  userId: string;
246
272
  userEmail: string | null;
273
+ /** Provenance pin for the emit — see `checkBucketMembership` (issue #608). */
274
+ contactId?: string;
247
275
  }): Promise<BucketTransition | null> {
248
- const { db, registry, hatchet, logger, bucket, userId, userEmail } = opts;
276
+ const {
277
+ db,
278
+ registry,
279
+ hatchet,
280
+ logger,
281
+ bucket,
282
+ userId,
283
+ userEmail,
284
+ contactId,
285
+ } = opts;
249
286
 
250
287
  // entryCount ordinal = 1 + count of ALL prior memberships (active + left) for
251
288
  // this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
@@ -312,6 +349,10 @@ async function handleJoin(opts: {
312
349
  bucket,
313
350
  userId,
314
351
  userEmail,
352
+ // Pin the re-ingest to the already-resolved contact row so an
353
+ // anonymous-only contact's transition folds in instead of minting a
354
+ // phantom twin (issue #608).
355
+ contactId,
315
356
  epoch,
316
357
  source: "event",
317
358
  });
@@ -335,9 +376,20 @@ async function handleLeave(opts: {
335
376
  active: typeof bucketMemberships.$inferSelect;
336
377
  userId: string;
337
378
  userEmail: string | null;
379
+ /** Provenance pin for the emit — see `checkBucketMembership` (issue #608). */
380
+ contactId?: string;
338
381
  }): Promise<BucketTransition | null> {
339
- const { db, registry, hatchet, logger, bucket, active, userId, userEmail } =
340
- opts;
382
+ const {
383
+ db,
384
+ registry,
385
+ hatchet,
386
+ logger,
387
+ bucket,
388
+ active,
389
+ userId,
390
+ userEmail,
391
+ contactId,
392
+ } = opts;
341
393
 
342
394
  // minDwell DEFERS (never silently drops) the leave (Section 6.3). We set a
343
395
  // pending-leave deadline on expiresAt = enteredAt + minDwell so the reconcile
@@ -401,6 +453,9 @@ async function handleLeave(opts: {
401
453
  bucket,
402
454
  userId,
403
455
  userEmail,
456
+ // Same provenance pin as the join emit — a leave re-ingests through the
457
+ // identical path and would mint the same phantom twin (issue #608).
458
+ contactId,
404
459
  epoch: flipped.entryCount,
405
460
  source: "event",
406
461
  reason: "criteria",
@@ -0,0 +1,145 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
4
+ import type { BucketMeta } from "@hogsend/core";
5
+ import type { JourneyRegistry } from "@hogsend/core/registry";
6
+ import type { Database } from "@hogsend/db";
7
+ import type { IngestEvent, ingestEvent } from "./ingestion.js";
8
+ import type { Logger } from "./logger.js";
9
+
10
+ // bucket-emit's import chain reaches env.ts (validates required env vars at
11
+ // import time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at
12
+ // import time) — stub both BEFORE the dynamic import. Nothing is ever
13
+ // contacted: the ingest seam intercepts everything. The token is the same
14
+ // well-formed dummy JWT apps/api's vitest config injects.
15
+ process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
16
+ process.env.BETTER_AUTH_SECRET ??= "test-secret";
17
+ process.env.HATCHET_CLIENT_TOKEN ??=
18
+ "eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
19
+ const { emitBucketTransition } = await import("./bucket-emit.js");
20
+
21
+ // ---------------------------------------------------------------------------
22
+ // Issue #608 — the `contactId` provenance pin. `emitBucketTransition`
23
+ // re-ingests every transition; `userId` is the contact's CANONICAL key
24
+ // (`external_id ?? anonymous_id ?? id`), but the resolver treats a bare
25
+ // `userId` as an EXTERNAL key, so an anonymous-only contact gets a phantom
26
+ // `external_id` twin minted per transition unless the pin rides the re-ingest.
27
+ // These tests assert at the `ingest` seam (no live DB — the Section 14
28
+ // pattern): the pin must ride BOTH re-ingests (per-bucket alias AND generic),
29
+ // and its absence must degrade to exactly the pin-less call shape.
30
+ // ---------------------------------------------------------------------------
31
+
32
+ const noop = () => {};
33
+ const logger: Logger = {
34
+ debug: noop,
35
+ info: noop,
36
+ warn: noop,
37
+ error: noop,
38
+ } as unknown as Logger;
39
+
40
+ const bucket: BucketMeta = {
41
+ id: "power-users",
42
+ name: "Power users",
43
+ } as BucketMeta;
44
+
45
+ /** A registry stub with a journey bound to the generic `bucket:<kind>` form, so
46
+ * the SECOND (generic) re-ingest actually fires and can be asserted on. */
47
+ function genericBoundRegistry(): JourneyRegistry {
48
+ return {
49
+ getByTriggerEvent: (event: string) =>
50
+ event === "bucket:entered" || event === "bucket:left" ? [{}] : [],
51
+ } as unknown as JourneyRegistry;
52
+ }
53
+
54
+ /** Recording ingest stub — captures each re-ingested event. */
55
+ function recordingIngest() {
56
+ const events: IngestEvent[] = [];
57
+ const ingest: typeof ingestEvent = async (opts) => {
58
+ events.push(opts.event);
59
+ return { stored: true, exits: [], contactKey: opts.event.userId ?? "" };
60
+ };
61
+ return { events, ingest };
62
+ }
63
+
64
+ // db/hatchet are never touched by the stubbed ingest; emitOutbound is
65
+ // fire-and-forget (`void ...catch(logger.warn)`) so its rejection on the empty
66
+ // db stub is swallowed by design.
67
+ const db = {} as Database;
68
+ const hatchet = {} as HatchetClient;
69
+
70
+ const CONTACT_ID = "9f3a1c2e-0000-4000-8000-000000000608";
71
+
72
+ test("entered: the contactId pin rides BOTH re-ingests (alias + generic)", async () => {
73
+ const { events, ingest } = recordingIngest();
74
+
75
+ await emitBucketTransition({
76
+ db,
77
+ registry: genericBoundRegistry(),
78
+ hatchet,
79
+ logger,
80
+ kind: "entered",
81
+ bucket,
82
+ userId: "anon-608",
83
+ userEmail: null,
84
+ contactId: CONTACT_ID,
85
+ epoch: 1,
86
+ ingest,
87
+ });
88
+
89
+ assert.equal(events.length, 2);
90
+ const [alias, generic] = events;
91
+ assert.equal(alias?.event, "bucket:entered:power-users");
92
+ assert.equal(generic?.event, "bucket:entered");
93
+ // The pin on EACH leg — dropping it on either one leaves the phantom-twin
94
+ // mint half-alive (issue #608).
95
+ assert.equal(alias?.contactId, CONTACT_ID);
96
+ assert.equal(generic?.contactId, CONTACT_ID);
97
+ });
98
+
99
+ test("left: the contactId pin rides the leave re-ingest too", async () => {
100
+ const { events, ingest } = recordingIngest();
101
+
102
+ await emitBucketTransition({
103
+ db,
104
+ registry: genericBoundRegistry(),
105
+ hatchet,
106
+ logger,
107
+ kind: "left",
108
+ bucket,
109
+ userId: "anon-608",
110
+ userEmail: null,
111
+ contactId: CONTACT_ID,
112
+ epoch: 2,
113
+ reason: "criteria",
114
+ ingest,
115
+ });
116
+
117
+ assert.equal(events.length, 2);
118
+ for (const event of events) {
119
+ assert.equal(event.contactId, CONTACT_ID);
120
+ }
121
+ });
122
+
123
+ test("no contactId: degrades to exactly the pin-less re-ingest", async () => {
124
+ const { events, ingest } = recordingIngest();
125
+
126
+ await emitBucketTransition({
127
+ db,
128
+ registry: genericBoundRegistry(),
129
+ hatchet,
130
+ logger,
131
+ kind: "entered",
132
+ bucket,
133
+ userId: "anon-608",
134
+ userEmail: null,
135
+ epoch: 1,
136
+ ingest,
137
+ });
138
+
139
+ // A producer with no resolved contact row in scope (e.g. the fast-expiry
140
+ // timer) must NOT invent a pin — the resolver falls back to value keys.
141
+ assert.equal(events.length, 2);
142
+ for (const event of events) {
143
+ assert.equal(event.contactId, undefined);
144
+ }
145
+ });
@@ -40,6 +40,17 @@ export async function emitBucketTransition(opts: {
40
40
  bucket: BucketMeta;
41
41
  userId: string;
42
42
  userEmail: string | null;
43
+ /**
44
+ * The subject contact's resolved row id (`contacts.id`) — the ENGINE-INTERNAL
45
+ * provenance pin, threaded into BOTH re-ingests below. `userId` here is the
46
+ * contact's CANONICAL key (`external_id ?? anonymous_id ?? id`), but the
47
+ * resolver treats a bare `userId` as an EXTERNAL key and never probes
48
+ * `anonymous_id` — so without the pin an anonymous-only contact gets a
49
+ * phantom `external_id` twin minted on every transition (issue #608).
50
+ * OPTIONAL: a producer that has no resolved contact row in scope degrades to
51
+ * the pin-less resolve (exactly the pre-pin behaviour).
52
+ */
53
+ contactId?: string;
43
54
  epoch: number;
44
55
  source?: BucketTransitionSource;
45
56
  /** Carried on a `left` transition's properties → `ctx.reason`. */
@@ -52,6 +63,12 @@ export async function emitBucketTransition(opts: {
52
63
  * absorbed by the `userEvents` dedup. Surfaced as `dwellCount`.
53
64
  */
54
65
  dwellOrdinal?: number;
66
+ /**
67
+ * Testing seam — the re-ingest fn (defaults to the real `ingestEvent`), so a
68
+ * unit test can assert the provenance pin rides BOTH re-ingests without a
69
+ * live database (the Section 14 pattern `checkBucketMembership` uses).
70
+ */
71
+ ingest?: typeof ingestEvent;
55
72
  }): Promise<void> {
56
73
  const {
57
74
  db,
@@ -62,11 +79,13 @@ export async function emitBucketTransition(opts: {
62
79
  bucket,
63
80
  userId,
64
81
  userEmail,
82
+ contactId,
65
83
  epoch,
66
84
  source = "event",
67
85
  reason,
68
86
  dwellLabel,
69
87
  dwellOrdinal,
88
+ ingest = ingestEvent,
70
89
  } = opts;
71
90
 
72
91
  // The dwell transition emits a labelled event so two dwell reactions on one
@@ -114,8 +133,10 @@ export async function emitBucketTransition(opts: {
114
133
 
115
134
  // Per-bucket alias — the recommended, narrowly-routed binding. The
116
135
  // deterministic idempotencyKey rides the userEvents dedup short-circuit as
117
- // defense-in-depth (Section 6.3).
118
- await ingestEvent({
136
+ // defense-in-depth (Section 6.3). `contactId` pins the resolver to the known
137
+ // row so an anonymous canonical key folds back in instead of minting a
138
+ // phantom `external_id` twin (issue #608).
139
+ await ingest({
119
140
  db,
120
141
  registry,
121
142
  hatchet,
@@ -124,6 +145,7 @@ export async function emitBucketTransition(opts: {
124
145
  event: eventName,
125
146
  userId,
126
147
  userEmail: userEmail ?? "",
148
+ contactId,
127
149
  eventProperties: properties,
128
150
  source: "bucket",
129
151
  idempotencyKey,
@@ -134,7 +156,7 @@ export async function emitBucketTransition(opts: {
134
156
  // recursion-guarded generic event is not written for nothing (Section 8.5).
135
157
  const genericEvent = `bucket:${kind}`;
136
158
  if (registry.getByTriggerEvent(genericEvent).length > 0) {
137
- await ingestEvent({
159
+ await ingest({
138
160
  db,
139
161
  registry,
140
162
  hatchet,
@@ -143,6 +165,10 @@ export async function emitBucketTransition(opts: {
143
165
  event: genericEvent,
144
166
  userId,
145
167
  userEmail: userEmail ?? "",
168
+ // Same provenance pin as the alias emit above — dropping it on ONLY
169
+ // this leg would leave the twin-minting half-alive for generic-bound
170
+ // journeys (issue #608).
171
+ contactId,
146
172
  eventProperties: properties,
147
173
  source: "bucket",
148
174
  idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
@@ -1,13 +1,13 @@
1
1
  import type { EmailProvider } from "@hogsend/core";
2
2
  import { createResendProvider } from "@hogsend/plugin-resend";
3
3
  import type { env as envSchema } from "../env.js";
4
+ import { loadOptionalPlugin } from "./load-optional-plugin.js";
4
5
 
5
6
  /**
6
- * `@hogsend/plugin-postmark` is an OPT-IN, deferred-publish package: it is an
7
- * engine `optionalDependency`, NOT a hard one, and it is not on the npm registry
8
- * yet. So we MUST NOT statically import it — a static `import` would make the
9
- * package mandatory at engine load, and `npm install @hogsend/engine` would fail
10
- * with E404 on plugin-postmark for every consumer that doesn't have it.
7
+ * `@hogsend/plugin-postmark` is an OPT-IN package: an engine
8
+ * `optionalDependency`, NOT a hard one. So we MUST NOT statically import it — a
9
+ * static `import` would make the package mandatory at engine load for every
10
+ * consumer, including the ones that never send through Postmark.
11
11
  *
12
12
  * Instead we load it lazily, ONCE, behind a top-level guarded dynamic import:
13
13
  * the `import()` only fires when `POSTMARK_SERVER_TOKEN` is present (the same
@@ -34,17 +34,16 @@ const POSTMARK_PACKAGE = ["@hogsend", "plugin-postmark"].join("/");
34
34
 
35
35
  let createPostmarkProvider: CreatePostmarkProvider | null = null;
36
36
  if (process.env.POSTMARK_SERVER_TOKEN) {
37
- try {
38
- ({ createPostmarkProvider } = (await import(POSTMARK_PACKAGE)) as {
39
- createPostmarkProvider: CreatePostmarkProvider;
40
- });
41
- } catch {
42
- // The token is set but the opt-in package isn't installed. Leave the factory
43
- // null — `emailProvidersFromEnv` skips the preset, and if Postmark was the
44
- // resolved active provider the container throws a clear "not registered"
45
- // error directing the operator to install `@hogsend/plugin-postmark`.
46
- createPostmarkProvider = null;
47
- }
37
+ // Previously a bare `catch {}` that swallowed the failure silently. If
38
+ // Postmark was the resolved active provider the container still threw its
39
+ // "not registered" boot error, but a deploy that merely set the token fell
40
+ // back to Resend with nothing in the logs to say why.
41
+ createPostmarkProvider = await loadOptionalPlugin<CreatePostmarkProvider>({
42
+ specifier: POSTMARK_PACKAGE,
43
+ exportName: "createPostmarkProvider",
44
+ enabledBy: "POSTMARK_SERVER_TOKEN is set",
45
+ onFailure: (message) => console.warn(message),
46
+ });
48
47
  }
49
48
 
50
49
  /**
@@ -22,7 +22,7 @@ export interface EnrichmentLookupRow {
22
22
  refinedAt: Date;
23
23
  expiresAt: Date;
24
24
  raw: Record<string, unknown> | null;
25
- /** The normalized `refined_*` patch the paid answer produced. */
25
+ /** The normalized canonical trait patch the paid answer produced. */
26
26
  traits: Record<string, unknown> | null;
27
27
  spendWindow: Date | null;
28
28
  spendCount: number;
@@ -1,10 +1,7 @@
1
1
  import assert from "node:assert/strict";
2
2
  import test from "node:test";
3
3
  import type { env as envSchema } from "../env.js";
4
- import {
5
- enrichmentProvidersFromEnv,
6
- loadEnrichmentPluginFactory,
7
- } from "./enrichment-providers-from-env.js";
4
+ import { enrichmentProvidersFromEnv } from "./enrichment-providers-from-env.js";
8
5
 
9
6
  // This test process never sets APOLLO_API_KEY, so the module-scope guarded
10
7
  // dynamic import in enrichment-providers-from-env.ts must not have fired —
@@ -25,43 +22,7 @@ test("AC 7 (preset half): key set but factory unresolved → empty list, no thro
25
22
  assert.deepEqual(enrichmentProvidersFromEnv(envWithKey), []);
26
23
  });
27
24
 
28
- test("AC 7 (guard half): unresolvable specifier → null + logged once, no throw", async () => {
29
- // Deliberately an INJECTED unresolvable specifier — NOT @hogsend/plugin-apollo,
30
- // which a later PRD adds to optionalDependencies (an absence-based test would
31
- // then silently invert its meaning).
32
- const messages: string[] = [];
33
- const factory = await loadEnrichmentPluginFactory({
34
- specifier: "@hogsend/plugin-test-does-not-exist",
35
- exportName: "createTestProvider",
36
- onMissing: (message) => messages.push(message),
37
- });
38
- assert.equal(factory, null);
39
- assert.equal(messages.length, 1);
40
- assert.match(messages[0] ?? "", /@hogsend\/plugin-test-does-not-exist/);
41
- });
42
-
43
- test("AC 7 control: resolvable specifier → returns the named export", async () => {
44
- // Proves the null above comes from the unresolvable specifier, not a broken
45
- // loader — keeping the guard-half assertion honest.
46
- const messages: string[] = [];
47
- const factory = await loadEnrichmentPluginFactory<
48
- typeof import("node:path")["join"]
49
- >({
50
- specifier: "node:path",
51
- exportName: "join",
52
- onMissing: (message) => messages.push(message),
53
- });
54
- assert.equal(typeof factory, "function");
55
- assert.equal(messages.length, 0);
56
- });
57
-
58
- test("a resolvable specifier MISSING the named export → null + logged, no throw", async () => {
59
- const messages: string[] = [];
60
- const factory = await loadEnrichmentPluginFactory({
61
- specifier: "node:path",
62
- exportName: "createApolloProvider",
63
- onMissing: (message) => messages.push(message),
64
- });
65
- assert.equal(factory, null);
66
- assert.equal(messages.length, 1);
67
- });
25
+ // The guard itself now lives in `load-optional-plugin.ts` and is covered by
26
+ // `load-optional-plugin.test.ts` — including the classification this preset
27
+ // depends on (absent package vs installed-but-broken). Only the preset's own
28
+ // behaviour is asserted here.
@@ -1,5 +1,6 @@
1
1
  import type { EnrichmentProvider } from "@hogsend/core";
2
2
  import type { env as envSchema } from "../env.js";
3
+ import { loadOptionalPlugin } from "./load-optional-plugin.js";
3
4
 
4
5
  /**
5
6
  * `@hogsend/plugin-apollo` is an OPT-IN, deferred-publish package — an engine
@@ -18,49 +19,15 @@ type CreateApolloProvider = (cfg: { apiKey: string }) => EnrichmentProvider;
18
19
 
19
20
  const APOLLO_PACKAGE = ["@hogsend", "plugin-apollo"].join("/");
20
21
 
21
- /**
22
- * The guard around the dynamic import, extracted so it is testable against an
23
- * INJECTED unresolvable specifier (never against `@hogsend/plugin-apollo`
24
- * genuinely being absent — once that package lands in `optionalDependencies`,
25
- * an absence-based test would silently assert the opposite of what it means).
26
- *
27
- * Resolves to the named factory export, or null when the package cannot be
28
- * resolved / the export is missing — in which case `onMissing` fires (once,
29
- * since the module-scope call site runs once per process) and nothing throws:
30
- * a key set without the plugin installed degrades gracefully, and if the
31
- * provider was EXPLICITLY requested the container still throws its clear
32
- * "not registered" boot error.
33
- */
34
- export async function loadEnrichmentPluginFactory<T>(opts: {
35
- specifier: string;
36
- exportName: string;
37
- onMissing?: (message: string) => void;
38
- }): Promise<T | null> {
39
- try {
40
- const mod = (await import(opts.specifier)) as Record<string, unknown>;
41
- const factory = mod[opts.exportName];
42
- if (typeof factory !== "function") {
43
- throw new Error(`missing export "${opts.exportName}"`);
44
- }
45
- return factory as T;
46
- } catch {
47
- opts.onMissing?.(
48
- `enrichment plugin "${opts.specifier}" is not installed — its env preset is skipped. ` +
49
- `Install the package (pnpm add ${opts.specifier}) to enable it.`,
50
- );
51
- return null;
52
- }
53
- }
54
-
55
22
  let createApolloProvider: CreateApolloProvider | null = null;
56
23
  if (process.env.APOLLO_API_KEY) {
57
- createApolloProvider =
58
- await loadEnrichmentPluginFactory<CreateApolloProvider>({
59
- specifier: APOLLO_PACKAGE,
60
- exportName: "createApolloProvider",
61
- // Module scope ⇒ logs ONCE per process, and only when the key is set.
62
- onMissing: (message) => console.warn(message),
63
- });
24
+ createApolloProvider = await loadOptionalPlugin<CreateApolloProvider>({
25
+ specifier: APOLLO_PACKAGE,
26
+ exportName: "createApolloProvider",
27
+ enabledBy: "APOLLO_API_KEY is set",
28
+ // Module scope ⇒ logs ONCE per process, and only when the key is set.
29
+ onFailure: (message) => console.warn(message),
30
+ });
64
31
  }
65
32
 
66
33
  /**
@@ -71,6 +71,14 @@ export interface IngestEvent {
71
71
  eventProperties: Record<string, unknown>;
72
72
  /** D2: → `contacts.properties` merge ONLY. */
73
73
  contactProperties?: Record<string, unknown>;
74
+ /**
75
+ * Extra property NAMES to re-evaluate buckets for — candidate-narrowing ONLY,
76
+ * NOT written and NOT in value eval. Lets a producer whose write patch omits a
77
+ * key (e.g. refinement's fill-if-absent, which drops already-held facts so it
78
+ * never clobbers first-party data) still trigger a fit bucket that references
79
+ * that key. Off by default; only engine-internal callers set it.
80
+ */
81
+ touchProperties?: string[];
74
82
  /**
75
83
  * The groupType→groupKey association map for this event — persisted on
76
84
  * `user_events.groups`, drives group membership (each group row is ensured +
@@ -778,10 +786,18 @@ export async function ingestEvent(opts: {
778
786
  hatchet,
779
787
  logger,
780
788
  userId: resolvedKey,
789
+ // The resolved row id rides along as the ENGINE-INTERNAL provenance pin
790
+ // for the bucket transition re-ingests: `resolvedKey` may be the
791
+ // contact's `anonymous_id`, which a bare re-ingest would treat as an
792
+ // external key and mint a phantom twin for (issue #608).
793
+ contactId,
781
794
  userEmail: event.userEmail || null,
782
795
  event: event.event,
783
796
  eventProperties: event.eventProperties,
784
797
  contactProperties: event.contactProperties ?? {},
798
+ ...(event.touchProperties
799
+ ? { touchProperties: event.touchProperties }
800
+ : {}),
785
801
  });
786
802
  } catch (err) {
787
803
  logger.warn("Bucket membership check failed", {