@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 +11 -11
- package/src/buckets/check-membership.ts +58 -3
- package/src/lib/bucket-emit.test.ts +145 -0
- package/src/lib/bucket-emit.ts +29 -3
- package/src/lib/email-providers-from-env.ts +15 -16
- package/src/lib/enrichment-ledger.ts +1 -1
- package/src/lib/enrichment-providers-from-env.test.ts +5 -44
- package/src/lib/enrichment-providers-from-env.ts +8 -41
- package/src/lib/ingestion.ts +16 -0
- package/src/lib/load-optional-plugin.test.ts +133 -0
- package/src/lib/load-optional-plugin.ts +142 -0
- package/src/lib/outbound.ts +3 -3
- package/src/lib/refine-chain.test.ts +83 -25
- package/src/lib/refine-chain.ts +124 -23
- package/src/lib/refine-traits.test.ts +74 -41
- package/src/lib/refine-traits.ts +107 -52
- package/src/lib/refine.ts +28 -27
- package/src/lib/sms-providers-from-env.ts +11 -11
- package/src/workflows/bucket-backfill.ts +14 -0
- package/src/workflows/bucket-reconcile.ts +74 -15
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import { mkdtemp, rm, writeFile } from "node:fs/promises";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
import test from "node:test";
|
|
6
|
+
import { pathToFileURL } from "node:url";
|
|
7
|
+
import {
|
|
8
|
+
loadOptionalPlugin,
|
|
9
|
+
type PluginLoadOutcome,
|
|
10
|
+
} from "./load-optional-plugin.js";
|
|
11
|
+
|
|
12
|
+
function collect() {
|
|
13
|
+
const seen: Array<{ message: string; outcome: PluginLoadOutcome }> = [];
|
|
14
|
+
return {
|
|
15
|
+
seen,
|
|
16
|
+
onFailure: (message: string, outcome: PluginLoadOutcome) =>
|
|
17
|
+
seen.push({ message, outcome }),
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
test("resolvable specifier → returns the named export, logs nothing", async () => {
|
|
22
|
+
// The control. Proves a null below comes from the specifier, not a broken
|
|
23
|
+
// loader.
|
|
24
|
+
const { seen, onFailure } = collect();
|
|
25
|
+
const factory = await loadOptionalPlugin<typeof import("node:path")["join"]>({
|
|
26
|
+
specifier: "node:path",
|
|
27
|
+
exportName: "join",
|
|
28
|
+
enabledBy: "TEST is set",
|
|
29
|
+
onFailure,
|
|
30
|
+
});
|
|
31
|
+
assert.equal(typeof factory, "function");
|
|
32
|
+
assert.equal(seen.length, 0);
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
test("absent package → not-installed, names the install command", async () => {
|
|
36
|
+
// An INJECTED unresolvable specifier, never a real @hogsend plugin: those are
|
|
37
|
+
// engine optionalDependencies, so an absence-based test would silently invert
|
|
38
|
+
// its own meaning the moment the package resolves.
|
|
39
|
+
const { seen, onFailure } = collect();
|
|
40
|
+
const factory = await loadOptionalPlugin({
|
|
41
|
+
specifier: "@hogsend/plugin-test-does-not-exist",
|
|
42
|
+
exportName: "createTestProvider",
|
|
43
|
+
enabledBy: "TEST_TOKEN is set",
|
|
44
|
+
onFailure,
|
|
45
|
+
});
|
|
46
|
+
assert.equal(factory, null);
|
|
47
|
+
assert.equal(seen.length, 1);
|
|
48
|
+
assert.equal(seen[0]?.outcome, "not-installed");
|
|
49
|
+
assert.match(
|
|
50
|
+
seen[0]?.message ?? "",
|
|
51
|
+
/pnpm add @hogsend\/plugin-test-does-not-exist/,
|
|
52
|
+
);
|
|
53
|
+
// The reason it was attempted at all must be in the message — otherwise the
|
|
54
|
+
// operator cannot tell which credential switched this on.
|
|
55
|
+
assert.match(seen[0]?.message ?? "", /TEST_TOKEN is set/);
|
|
56
|
+
// The direct-dependency nuance is the entire point: an engine
|
|
57
|
+
// optionalDependency is installed but never linked at the consumer's top
|
|
58
|
+
// level, so a bundled app cannot resolve it.
|
|
59
|
+
assert.match(seen[0]?.message ?? "", /DIRECT dependency/);
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
test("present but broken → load-failed, and does NOT say 'not installed'", async () => {
|
|
63
|
+
// The regression that motivated this module. The old loader reported every
|
|
64
|
+
// failure as "is not installed", so an operator whose package WAS installed
|
|
65
|
+
// (but shipped raw .ts that Node cannot type-strip under node_modules) was
|
|
66
|
+
// told to reinstall it — advice that could never work. A load failure must
|
|
67
|
+
// never be described as an absence.
|
|
68
|
+
const { seen, onFailure } = collect();
|
|
69
|
+
const factory = await loadOptionalPlugin({
|
|
70
|
+
// Resolves, then throws on evaluation.
|
|
71
|
+
specifier: "data:text/javascript,throw new Error('boom on evaluate')",
|
|
72
|
+
exportName: "createTestProvider",
|
|
73
|
+
enabledBy: "TEST_TOKEN is set",
|
|
74
|
+
onFailure,
|
|
75
|
+
});
|
|
76
|
+
assert.equal(factory, null);
|
|
77
|
+
assert.equal(seen[0]?.outcome, "load-failed");
|
|
78
|
+
assert.doesNotMatch(seen[0]?.message ?? "", /is not installed/);
|
|
79
|
+
assert.match(seen[0]?.message ?? "", /boom on evaluate/);
|
|
80
|
+
assert.match(seen[0]?.message ?? "", /packaging bug/);
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
test("a MISSING TRANSITIVE dep is not reported as the plugin being absent", async () => {
|
|
84
|
+
// The case that forces classification to inspect the message, not just the
|
|
85
|
+
// code. "plugin-twilio is installed but `twilio` is not" throws the SAME
|
|
86
|
+
// ERR_MODULE_NOT_FOUND as "plugin-twilio is not installed"; keying on the
|
|
87
|
+
// code alone would tell the operator to reinstall a package that is already
|
|
88
|
+
// there while the real gap goes unnamed.
|
|
89
|
+
//
|
|
90
|
+
// This needs a real file on disk. A `data:` URL cannot resolve bare
|
|
91
|
+
// specifiers at all (ERR_UNSUPPORTED_RESOLVE_REQUEST), and a `node:`-prefixed
|
|
92
|
+
// miss throws ERR_UNKNOWN_BUILTIN_MODULE — neither reaches this branch, so
|
|
93
|
+
// either would pass while testing nothing.
|
|
94
|
+
const dir = await mkdtemp(join(tmpdir(), "hogsend-plugin-load-"));
|
|
95
|
+
try {
|
|
96
|
+
const file = join(dir, "broken.mjs");
|
|
97
|
+
await writeFile(
|
|
98
|
+
file,
|
|
99
|
+
'import "totally-not-a-real-package-xyz";\nexport const createTestProvider = () => {};\n',
|
|
100
|
+
);
|
|
101
|
+
const { seen, onFailure } = collect();
|
|
102
|
+
const factory = await loadOptionalPlugin({
|
|
103
|
+
specifier: pathToFileURL(file).href,
|
|
104
|
+
exportName: "createTestProvider",
|
|
105
|
+
enabledBy: "TEST_TOKEN is set",
|
|
106
|
+
onFailure,
|
|
107
|
+
});
|
|
108
|
+
assert.equal(factory, null);
|
|
109
|
+
assert.equal(seen[0]?.outcome, "load-failed");
|
|
110
|
+
assert.doesNotMatch(seen[0]?.message ?? "", /is not installed/);
|
|
111
|
+
// The missing package must be named, or the operator learns nothing.
|
|
112
|
+
assert.match(seen[0]?.message ?? "", /totally-not-a-real-package-xyz/);
|
|
113
|
+
} finally {
|
|
114
|
+
await rm(dir, { recursive: true, force: true });
|
|
115
|
+
}
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
test("resolvable but missing the named export → missing-export, flags version skew", async () => {
|
|
119
|
+
const { seen, onFailure } = collect();
|
|
120
|
+
const factory = await loadOptionalPlugin({
|
|
121
|
+
specifier: "node:path",
|
|
122
|
+
exportName: "createApolloProvider",
|
|
123
|
+
enabledBy: "APOLLO_API_KEY is set",
|
|
124
|
+
onFailure,
|
|
125
|
+
});
|
|
126
|
+
assert.equal(factory, null);
|
|
127
|
+
assert.equal(seen[0]?.outcome, "missing-export");
|
|
128
|
+
assert.match(
|
|
129
|
+
seen[0]?.message ?? "",
|
|
130
|
+
/does not export "createApolloProvider"/,
|
|
131
|
+
);
|
|
132
|
+
assert.match(seen[0]?.message ?? "", /version/);
|
|
133
|
+
});
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared loader for the engine's OPT-IN plugin packages (`@hogsend/plugin-apollo`,
|
|
3
|
+
* `-postmark`, `-twilio`). Each is an engine `optionalDependency`, never a hard
|
|
4
|
+
* one: a static import would make the package mandatory at engine load and break
|
|
5
|
+
* `npm install @hogsend/engine` for every consumer without it.
|
|
6
|
+
*
|
|
7
|
+
* So each preset loads its package lazily, ONCE, behind a guarded dynamic import
|
|
8
|
+
* gated on the relevant credential. The specifier is assembled at runtime (not a
|
|
9
|
+
* literal) so `tsc` never resolves the module's types for a consumer that does
|
|
10
|
+
* not have the opt-in package.
|
|
11
|
+
*
|
|
12
|
+
* ## Why the failure message matters so much
|
|
13
|
+
*
|
|
14
|
+
* All three presets previously swallowed the failure — SMS silently, enrichment
|
|
15
|
+
* behind a message that said "is not installed" for EVERY failure mode. That
|
|
16
|
+
* message was actively wrong in the most common real case (installed, but the
|
|
17
|
+
* package shipped raw `.ts` that Node cannot type-strip inside node_modules), so
|
|
18
|
+
* an operator following it reinstalled a package they already had. The whole
|
|
19
|
+
* point of this module is that the two failure modes are DIFFERENT problems with
|
|
20
|
+
* different fixes, and conflating them sends people to fix the wrong thing.
|
|
21
|
+
*
|
|
22
|
+
* `not-installed` is a configuration problem the operator can fix.
|
|
23
|
+
* `load-failed` is OUR bug and should be reported, not worked around.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
export type PluginLoadOutcome =
|
|
27
|
+
| "not-installed"
|
|
28
|
+
| "load-failed"
|
|
29
|
+
| "missing-export";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Distinguish "the package itself is absent" from "the package is present but
|
|
33
|
+
* blew up while loading".
|
|
34
|
+
*
|
|
35
|
+
* Both surface as `ERR_MODULE_NOT_FOUND` in the general case — a plugin whose
|
|
36
|
+
* own npm dependency is missing throws exactly the same code. So a bare code
|
|
37
|
+
* check would mislabel "plugin-twilio is installed but `twilio` isn't" as
|
|
38
|
+
* "plugin-twilio is not installed" and send the operator to reinstall the wrong
|
|
39
|
+
* package. Requiring the message to name the specifier keeps the two apart.
|
|
40
|
+
*/
|
|
41
|
+
function classify(error: unknown, specifier: string): PluginLoadOutcome {
|
|
42
|
+
const err = error as { code?: string; message?: string } | undefined;
|
|
43
|
+
const notFound =
|
|
44
|
+
err?.code === "ERR_MODULE_NOT_FOUND" || err?.code === "MODULE_NOT_FOUND";
|
|
45
|
+
return notFound && (err?.message ?? "").includes(specifier)
|
|
46
|
+
? "not-installed"
|
|
47
|
+
: "load-failed";
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function describe(error: unknown): string {
|
|
51
|
+
const err = error as { code?: string; message?: string } | undefined;
|
|
52
|
+
const code = err?.code ? `${err.code}: ` : "";
|
|
53
|
+
return `${code}${(err?.message ?? String(error)).split("\n")[0]}`;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function messageFor(opts: {
|
|
57
|
+
specifier: string;
|
|
58
|
+
exportName: string;
|
|
59
|
+
enabledBy: string;
|
|
60
|
+
outcome: PluginLoadOutcome;
|
|
61
|
+
error?: unknown;
|
|
62
|
+
}): string {
|
|
63
|
+
const { specifier, exportName, enabledBy, outcome, error } = opts;
|
|
64
|
+
const skipped = `${enabledBy}, but its env preset is skipped`;
|
|
65
|
+
|
|
66
|
+
if (outcome === "not-installed") {
|
|
67
|
+
return (
|
|
68
|
+
`${skipped}: "${specifier}" is not installed. ` +
|
|
69
|
+
`Add it as a DIRECT dependency of your app: pnpm add ${specifier}. ` +
|
|
70
|
+
`Note that the engine listing it under optionalDependencies is NOT enough — ` +
|
|
71
|
+
`your app bundles the engine, so this import resolves against YOUR ` +
|
|
72
|
+
`node_modules, where an engine-only optional dependency is never linked.`
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (outcome === "missing-export") {
|
|
77
|
+
return (
|
|
78
|
+
`${skipped}: "${specifier}" loaded but does not export "${exportName}". ` +
|
|
79
|
+
`This usually means the package version does not match @hogsend/engine — ` +
|
|
80
|
+
`align them on the same engine line (pnpm add ${specifier}@<engine version>).`
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
return (
|
|
85
|
+
`${skipped}: "${specifier}" IS installed but failed to load — ` +
|
|
86
|
+
`${describe(error)}. This is a packaging bug in Hogsend rather than ` +
|
|
87
|
+
`anything wrong with your configuration; please report it. ` +
|
|
88
|
+
`Reinstalling the package will not help.`
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Resolve a named factory export from an optional plugin package.
|
|
94
|
+
*
|
|
95
|
+
* Returns the factory, or `null` when the package cannot be loaded — in which
|
|
96
|
+
* case `onFailure` fires (once, since every call site runs at module scope, once
|
|
97
|
+
* per process) and NOTHING throws. A credential set without a working plugin
|
|
98
|
+
* degrades gracefully; if the provider was EXPLICITLY selected the container
|
|
99
|
+
* still throws its own clear "not registered" error at boot.
|
|
100
|
+
*
|
|
101
|
+
* Deliberately testable against an INJECTED specifier so the guard can be
|
|
102
|
+
* exercised without depending on a real package being absent — once these
|
|
103
|
+
* packages are engine optionalDependencies, an absence-based test would silently
|
|
104
|
+
* assert the opposite of what it means.
|
|
105
|
+
*/
|
|
106
|
+
export async function loadOptionalPlugin<T>(opts: {
|
|
107
|
+
specifier: string;
|
|
108
|
+
exportName: string;
|
|
109
|
+
/** What switched this on, e.g. `"APOLLO_API_KEY is set"`. Named in the message. */
|
|
110
|
+
enabledBy: string;
|
|
111
|
+
onFailure?: (message: string, outcome: PluginLoadOutcome) => void;
|
|
112
|
+
}): Promise<T | null> {
|
|
113
|
+
const { specifier, exportName, enabledBy, onFailure } = opts;
|
|
114
|
+
|
|
115
|
+
let mod: Record<string, unknown>;
|
|
116
|
+
try {
|
|
117
|
+
mod = (await import(specifier)) as Record<string, unknown>;
|
|
118
|
+
} catch (error) {
|
|
119
|
+
const outcome = classify(error, specifier);
|
|
120
|
+
onFailure?.(
|
|
121
|
+
messageFor({ specifier, exportName, enabledBy, outcome, error }),
|
|
122
|
+
outcome,
|
|
123
|
+
);
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
const factory = mod[exportName];
|
|
128
|
+
if (typeof factory !== "function") {
|
|
129
|
+
onFailure?.(
|
|
130
|
+
messageFor({
|
|
131
|
+
specifier,
|
|
132
|
+
exportName,
|
|
133
|
+
enabledBy,
|
|
134
|
+
outcome: "missing-export",
|
|
135
|
+
}),
|
|
136
|
+
"missing-export",
|
|
137
|
+
);
|
|
138
|
+
return null;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
return factory as T;
|
|
142
|
+
}
|
package/src/lib/outbound.ts
CHANGED
|
@@ -113,8 +113,8 @@ export interface OutboundPayloads {
|
|
|
113
113
|
* ONLY on a genuine `status: "refined"` — never on `cached`, `not_found` or
|
|
114
114
|
* `skipped`, because a cache hit is a spend decision, not a change.
|
|
115
115
|
*
|
|
116
|
-
* `traits` carries the
|
|
117
|
-
* "
|
|
116
|
+
* `traits` carries the canonical trait KEY NAMES only — `["title",
|
|
117
|
+
* "company_domain"]` — never their values. That is deliberate: the
|
|
118
118
|
* payload says WHAT CHANGED, and a subscriber that wants the values reads
|
|
119
119
|
* the contact (`GET /v1/contacts`). So vendor-licensed person data never
|
|
120
120
|
* leaves the building inside a webhook body, and the envelope stays a fixed
|
|
@@ -132,7 +132,7 @@ export interface OutboundPayloads {
|
|
|
132
132
|
provider: string;
|
|
133
133
|
/** Mapped trait key NAMES, sorted. Values are deliberately absent. */
|
|
134
134
|
traits: string[];
|
|
135
|
-
/** ISO — the lookup instant (the same value as `
|
|
135
|
+
/** ISO — the lookup instant (the same value as `enrichment.at`). */
|
|
136
136
|
at: string;
|
|
137
137
|
};
|
|
138
138
|
"email.sent": {
|
|
@@ -93,6 +93,10 @@ interface Harness {
|
|
|
93
93
|
ingests: number;
|
|
94
94
|
/** Every outbound `contact.refined` emit, in order. */
|
|
95
95
|
emits: RefineEmitInput[];
|
|
96
|
+
/** The `contactProperties` each `ingest` received, in order. */
|
|
97
|
+
ingested: Record<string, unknown>[];
|
|
98
|
+
/** The `touchProperties` each `ingest` received, in order. */
|
|
99
|
+
touched: (string[] | undefined)[];
|
|
96
100
|
}
|
|
97
101
|
|
|
98
102
|
function harness(overrides: {
|
|
@@ -116,6 +120,8 @@ function harness(overrides: {
|
|
|
116
120
|
ledgerWrites: 0,
|
|
117
121
|
ingests: 0,
|
|
118
122
|
emits: [] as RefineEmitInput[],
|
|
123
|
+
ingested: [] as Record<string, unknown>[],
|
|
124
|
+
touched: [] as (string[] | undefined)[],
|
|
119
125
|
};
|
|
120
126
|
|
|
121
127
|
const deps: RefineChainDeps = {
|
|
@@ -135,15 +141,16 @@ function harness(overrides: {
|
|
|
135
141
|
contactId: "c1",
|
|
136
142
|
userId: "u1",
|
|
137
143
|
email: "a@acme.com",
|
|
138
|
-
refinedProperties: { refined_title: "old" },
|
|
139
144
|
},
|
|
140
145
|
findLedgerRow: async () => overrides.ledgerRow ?? null,
|
|
141
146
|
countLookupsSince: async () => overrides.usedThisMonth ?? 0,
|
|
142
147
|
writeLedgerRow: async () => {
|
|
143
148
|
state.ledgerWrites += 1;
|
|
144
149
|
},
|
|
145
|
-
ingest: async () => {
|
|
150
|
+
ingest: async (input) => {
|
|
146
151
|
state.ingests += 1;
|
|
152
|
+
state.ingested.push(input.contactProperties);
|
|
153
|
+
state.touched.push(input.touchProperties);
|
|
147
154
|
if (overrides.ingest) await overrides.ingest();
|
|
148
155
|
},
|
|
149
156
|
emitRefined: (input) => {
|
|
@@ -163,6 +170,12 @@ function harness(overrides: {
|
|
|
163
170
|
get emits() {
|
|
164
171
|
return state.emits;
|
|
165
172
|
},
|
|
173
|
+
get ingested() {
|
|
174
|
+
return state.ingested;
|
|
175
|
+
},
|
|
176
|
+
get touched() {
|
|
177
|
+
return state.touched;
|
|
178
|
+
},
|
|
166
179
|
};
|
|
167
180
|
}
|
|
168
181
|
|
|
@@ -470,7 +483,7 @@ test("D2: a cache hit lands the STORED patch on a contact that never received it
|
|
|
470
483
|
// The shared-domain case: contact B hits the row contact A paid for. The
|
|
471
484
|
// ledger has no contact dimension, so "already paid for" says nothing about
|
|
472
485
|
// whether THIS contact has the traits.
|
|
473
|
-
const stored = {
|
|
486
|
+
const stored = { title: "CTO", company_employees: 250 };
|
|
474
487
|
const h = harness({
|
|
475
488
|
ledgerRow: unexpired("found", stored),
|
|
476
489
|
target: { contactId: "c2", userId: "u2", domain: "acme.com" },
|
|
@@ -491,14 +504,14 @@ test("D2: a cache hit re-runs the ingest even when the contact already holds the
|
|
|
491
504
|
// buckets: only the ingest path re-runs `checkBucketMembership`, and a
|
|
492
505
|
// contact can carry the traits with no membership (exactly what a failed
|
|
493
506
|
// ingest leaves behind). So the cached verdict always re-lands.
|
|
494
|
-
const stored = {
|
|
507
|
+
const stored = { title: "CTO", company_employees: 250 };
|
|
495
508
|
const h = harness({
|
|
496
509
|
ledgerRow: unexpired("found", stored),
|
|
497
510
|
target: {
|
|
498
511
|
contactId: "c1",
|
|
499
512
|
userId: "u1",
|
|
500
513
|
domain: "acme.com",
|
|
501
|
-
|
|
514
|
+
existingProperties: { ...stored },
|
|
502
515
|
},
|
|
503
516
|
});
|
|
504
517
|
|
|
@@ -506,23 +519,74 @@ test("D2: a cache hit re-runs the ingest even when the contact already holds the
|
|
|
506
519
|
|
|
507
520
|
assert.deepEqual(result, { status: "cached", properties: stored });
|
|
508
521
|
assert.equal(h.ingests, 1);
|
|
522
|
+
// The contact already held every fact, so the WRITE patch is empty (nothing
|
|
523
|
+
// first-party is clobbered) — but the ingest still runs and TOUCHES both keys,
|
|
524
|
+
// so bucket membership re-evaluates against live contact state.
|
|
525
|
+
assert.deepEqual(h.ingested, [{}]);
|
|
526
|
+
assert.deepEqual([...(h.touched[0] ?? [])].sort(), [
|
|
527
|
+
"company_employees",
|
|
528
|
+
"title",
|
|
529
|
+
]);
|
|
509
530
|
assert.equal(h.providerCalls(), 0);
|
|
510
531
|
assert.equal(h.ledgerWrites, 0);
|
|
511
532
|
});
|
|
512
533
|
|
|
513
|
-
test("D2: a legacy row with no stored patch
|
|
534
|
+
test("D2: a legacy row with no stored patch returns cached with an empty patch", async () => {
|
|
514
535
|
const h = harness({ ledgerRow: unexpired("found", null) });
|
|
515
536
|
|
|
516
537
|
const result = await runRefineChain(h.deps, SUBJECT);
|
|
517
538
|
|
|
518
539
|
assert.deepEqual(result, {
|
|
519
540
|
status: "cached",
|
|
520
|
-
properties: {
|
|
541
|
+
properties: {},
|
|
521
542
|
});
|
|
522
543
|
assert.equal(h.ingests, 0);
|
|
523
544
|
assert.equal(h.providerCalls(), 0);
|
|
524
545
|
});
|
|
525
546
|
|
|
547
|
+
// ---------------------------------------------------------------------------
|
|
548
|
+
// Fill-if-absent — a paid answer fills gaps, never overwrites first-party data
|
|
549
|
+
// ---------------------------------------------------------------------------
|
|
550
|
+
|
|
551
|
+
test("fill-if-absent: a fresh lookup fills gaps but never overwrites a first-party value", async () => {
|
|
552
|
+
// FOUND carries title / seniority / company / company_employees. This contact
|
|
553
|
+
// already has a first-party `title` and `company`, so the paid answer must
|
|
554
|
+
// leave those two alone and only fill what was missing.
|
|
555
|
+
const h = harness({
|
|
556
|
+
target: {
|
|
557
|
+
contactId: "c1",
|
|
558
|
+
userId: "u1",
|
|
559
|
+
email: "a@acme.com",
|
|
560
|
+
existingProperties: { title: "First-party VP", company: "First Co" },
|
|
561
|
+
},
|
|
562
|
+
});
|
|
563
|
+
|
|
564
|
+
const result = await runRefineChain(h.deps, SUBJECT);
|
|
565
|
+
|
|
566
|
+
assert.equal(result.status, "refined");
|
|
567
|
+
// The vendor's FULL answer is still reported on the result...
|
|
568
|
+
assert.equal(result.properties?.title, "CTO");
|
|
569
|
+
// ...but the WRITE patch OMITS the already-held title + company entirely (so
|
|
570
|
+
// the additive merge leaves the live first-party value untouched — atomic, no
|
|
571
|
+
// stale write-back) and carries the vendor's value only for the gaps.
|
|
572
|
+
const landed = h.ingested[0] ?? {};
|
|
573
|
+
assert.equal("title" in landed, false);
|
|
574
|
+
assert.equal("company" in landed, false);
|
|
575
|
+
assert.equal(landed.seniority, "c_suite");
|
|
576
|
+
assert.equal(landed.company_employees, 250);
|
|
577
|
+
assert.ok(landed.enrichment, "provenance always lands");
|
|
578
|
+
// ...yet every returned fact is TOUCHED, so a fit bucket on the already-held
|
|
579
|
+
// title/company still re-evaluates against live contact state.
|
|
580
|
+
assert.deepEqual([...(h.touched[0] ?? [])].sort(), [
|
|
581
|
+
"company",
|
|
582
|
+
"company_employees",
|
|
583
|
+
"seniority",
|
|
584
|
+
"title",
|
|
585
|
+
]);
|
|
586
|
+
// The outbound reports only the facts that actually CHANGED on this contact.
|
|
587
|
+
assert.deepEqual(h.emits[0]?.traitKeys, ["company_employees", "seniority"]);
|
|
588
|
+
});
|
|
589
|
+
|
|
526
590
|
// ---------------------------------------------------------------------------
|
|
527
591
|
// D4b — a failed ingest is a verdict, not an exception
|
|
528
592
|
// ---------------------------------------------------------------------------
|
|
@@ -543,7 +607,7 @@ test("D4b: a failed ingest does not throw out of the chain and does not report s
|
|
|
543
607
|
});
|
|
544
608
|
|
|
545
609
|
test("D4b: the retry after a failed ingest re-lands the stored patch for FREE", async () => {
|
|
546
|
-
const stored = {
|
|
610
|
+
const stored = { title: "CTO" };
|
|
547
611
|
const h = harness({ ledgerRow: unexpired("found", stored) });
|
|
548
612
|
|
|
549
613
|
const result = await runRefineChain(h.deps, SUBJECT);
|
|
@@ -558,16 +622,11 @@ test("D4b: the retry after a failed ingest re-lands the stored patch for FREE",
|
|
|
558
622
|
// ---------------------------------------------------------------------------
|
|
559
623
|
|
|
560
624
|
/**
|
|
561
|
-
* The sorted trait key names FOUND flattens to — NAMES, never values,
|
|
562
|
-
*
|
|
563
|
-
*
|
|
625
|
+
* The sorted canonical trait key names FOUND flattens to — NAMES, never values,
|
|
626
|
+
* and FACTS only: the nested `enrichment` provenance is already carried as the
|
|
627
|
+
* envelope's `at` / `provider`, so it is not a trait.
|
|
564
628
|
*/
|
|
565
|
-
const FOUND_TRAIT_KEYS = [
|
|
566
|
-
"refined_company_employees",
|
|
567
|
-
"refined_company_name",
|
|
568
|
-
"refined_seniority",
|
|
569
|
-
"refined_title",
|
|
570
|
-
];
|
|
629
|
+
const FOUND_TRAIT_KEYS = ["company", "company_employees", "seniority", "title"];
|
|
571
630
|
|
|
572
631
|
/** NOW as the dedupe key serializes it. */
|
|
573
632
|
const NOW_ISO = NOW.toISOString();
|
|
@@ -595,14 +654,13 @@ test("AC 1: a `refined` verdict emits contact.refined with the contact key, prov
|
|
|
595
654
|
assert.ok(!JSON.stringify(emitted.traitKeys).includes("CTO"));
|
|
596
655
|
assert.ok(!JSON.stringify(emitted.traitKeys).includes("Acme"));
|
|
597
656
|
// Provenance is NOT a trait — it rides as `provider` / `refinedAt` instead.
|
|
598
|
-
assert.ok(!emitted.traitKeys.includes("
|
|
599
|
-
assert.ok(!emitted.traitKeys.includes("refined_provider"));
|
|
657
|
+
assert.ok(!emitted.traitKeys.includes("enrichment"));
|
|
600
658
|
});
|
|
601
659
|
|
|
602
|
-
test("AC 1: a found-but-empty vendor answer reports NO traits rather than
|
|
603
|
-
// `flattenTraits` stamps
|
|
604
|
-
//
|
|
605
|
-
//
|
|
660
|
+
test("AC 1: a found-but-empty vendor answer reports NO traits rather than a metadata key", async () => {
|
|
661
|
+
// `flattenTraits` stamps the `enrichment` provenance unconditionally, so if it
|
|
662
|
+
// counted as a trait this payload would claim a change for an answer that told
|
|
663
|
+
// us nothing about the person.
|
|
606
664
|
const empty: EnrichmentProvider = {
|
|
607
665
|
meta: { id: "fake", name: "Fake" },
|
|
608
666
|
capabilities: { personLookup: true, companyLookup: true },
|
|
@@ -627,7 +685,7 @@ test("AC 1: a domain-keyed refinement emits with the domain lookup in its dedupe
|
|
|
627
685
|
|
|
628
686
|
test("AC 2: `cached`, `not_found` and `skipped` emit NOTHING — a cache hit is not an event", async () => {
|
|
629
687
|
const cached = harness({
|
|
630
|
-
ledgerRow: unexpired("found", {
|
|
688
|
+
ledgerRow: unexpired("found", { title: "CTO" }),
|
|
631
689
|
});
|
|
632
690
|
const notFoundCached = harness({ ledgerRow: unexpired("not_found") });
|
|
633
691
|
const notFoundLive = harness({ provider: fakeProvider("miss").provider });
|
|
@@ -728,7 +786,7 @@ test("AC 3: a re-drive never reaches the emit anyway — the LEDGER GATE returns
|
|
|
728
786
|
// wrote and returns `cached` (refine-chain.ts step 3), which has no emit at
|
|
729
787
|
// all — so a duplicate delivery needs a concurrent race, not a retry.
|
|
730
788
|
const redrive = harness({
|
|
731
|
-
ledgerRow: unexpired("found", {
|
|
789
|
+
ledgerRow: unexpired("found", { title: "CTO" }),
|
|
732
790
|
});
|
|
733
791
|
|
|
734
792
|
assert.equal((await runRefineChain(redrive.deps, SUBJECT)).status, "cached");
|