Merge pull request #475 from shamanic-technologies/main

chore: sync hotfix v0.39.90 to staging

Author: KevinLourd

.vt-a.log

@@ -0,0 +1,9 @@
+
+ RUN  v4.1.12 /Users/kevinlourd/conductor/worktrees/factory-p3-next-apollo-service
+
+
+ Test Files  80 passed | 3 skipped (83)
+      Tests  852 passed | 32 skipped (884)
+   Start at  21:47:33
+   Duration  34.60s (transform 1.36s, setup 450ms, import 9.29s, tests 18.05s, environment 4ms)
+

.vt-s.log

@@ -0,0 +1,9 @@
+
+ RUN  v4.1.12 /Users/kevinlourd/conductor/worktrees/factory-p3-next-apollo-service
+
+
+ Test Files  1 passed (1)
+      Tests  4 passed (4)
+   Start at  21:45:58
+   Duration  357ms (transform 96ms, setup 23ms, import 22ms, tests 230ms, environment 0ms)
+

CLAUDE.md

@@ -662,6 +662,9 @@ pre-serve verification moved here from human-service. `/enrich`, `/match` and
   receive the verdict and its cost. Do not make it opt-in per caller; the
   owner's rule is that no revealed email leaves unverified.
 
+### The waterfall DECISION can run as a stored script (FACTORY-P3 next outcomes, email_found)
+`src/lib/email-verify-script.ts`. No workflow step calls the waterfall, so it is a SERVICE switch held by workflow-service (`GET /internal/scripts/switches/service?outcome=email_found&callerService=apollo`, read at most once a minute; unreadable = last state, never read = our code). After the 30-day reuse (a held FINAL verdict asks nothing; a held step-1 catch_all/unknown is handed to the decision as `held`), the decision runs either HERE (`stepOne` + `secondOpinion` on its own `email-verification` run, child of the caller's run: Monitoring's service path) or, switched and with a caller run + user, as the stored script (`POST /internal/scripts/run`, `recordedBy: "apollo"`, parent = the caller's run). The script reaches us only through two DOORS that serve a verification IN FLIGHT here (`x-caller-run-id` + address, `registerInFlight`): `POST /internal/email-verifier-calls {verifier, email}` (our exact verifier call: hold, run under the SCRIPT's run, bronze row naming the CALLER's run (`VerificationContext.callRunParentId` moves only the run parent), email_checked, Apify-out timer, BounceBan resume/poll) and `GET /internal/email-verifier-calls/apify`. A refusal a door meets (billing, key, BounceBan pending, every verifier failed) is kept on the in-flight entry and re-thrown to the caller as the SAME `EmailVerificationError` (routes answer as before). EVERY decision, both paths, is recorded with its calls in the script's words (`email_verification_decisions`, migration 0048, fail-soft), served `GET /internal/email-verification-decisions/recorded?after=<seq>` (service key, 60 s settle) to workflow-service's case recorder. Guards: `email-verify-script.test.ts`, decision-run assertions in `email-verification*.test.ts` / `apify-credit-alert.test.ts`.
+
 ## Reveal domain gate — no Apollo credit on a domain that cannot verify `valid`
 
 `POST /enrich` (Apollo path, cache miss) judges the employer's MAIL DOMAIN

drizzle/0048_email_verification_decisions.sql

@@ -0,0 +1,24 @@
+-- FACTORY-P3 next outcomes (email_found): every verification DECISION (which verifier was asked, in which order, what
+-- each answered, what was decided) on either path: our own waterfall (`service`) or the stored script while switched
+-- (`script`). Bronze, append-only. Read only by GET /internal/email-verification-decisions/recorded (workflow-service's
+-- case recorder). Personal data.
+CREATE TABLE IF NOT EXISTS "email_verification_decisions" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "seq" bigserial NOT NULL,
+  "email" text NOT NULL,
+  "org_id" uuid NOT NULL,
+  "caller_run_id" text,
+  "run_id" text,
+  "source" text,
+  "path" text NOT NULL,
+  "held" jsonb,
+  "calls" jsonb NOT NULL,
+  "result" jsonb,
+  "error" text,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "email_verification_decisions_path_check" CHECK ("path" IN ('service', 'script'))
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "idx_email_verification_decisions_seq" ON "email_verification_decisions" ("seq");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_email_verification_decisions_created" ON "email_verification_decisions" ("created_at");

drizzle/meta/_journal.json

@@ -337,6 +337,13 @@
       "when": 1781481600000,
       "tag": "0047_box_load_apollo_waste",
       "breakpoints": true
+    },
+    {
+      "idx": 48,
+      "version": "7",
+      "when": 1781568000000,
+      "tag": "0048_email_verification_decisions",
+      "breakpoints": true
     }
   ]
 }

openapi.json

@@ -9502,6 +9502,264 @@
         }
       }
     },
+    "/internal/email-verifier-calls": {
+      "post": {
+        "summary": "One verifier call for the stored verification script (its door; service key)",
+        "description": "FACTORY-P3 next outcomes (email_found). Serves ONLY a verification in flight in this service (`x-caller-run-id` = the run that asked this service, + the address): our own verifier call (ContactOut, BounceVerify, TryKitt, MillionVerifier, or BounceBan with its resume and polling) on the script's run (`x-run-id`), with its billing hold, run, bronze row (naming the caller's run) and email_checked declaration. 409 when nothing is in flight; 502 = refused (billing, key), the refusal reaching the caller as our own error.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-api-key",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-org-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-user-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-run-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-caller-run-id",
+            "in": "header"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "verifier": {
+                    "type": "string",
+                    "enum": [
+                      "contactout",
+                      "bounceverify",
+                      "trykitt",
+                      "millionverifier",
+                      "bounceban"
+                    ]
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "verifier",
+                  "email"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The call's bronze row (error = the verifier did not answer)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "verificationId": {
+                      "type": "string"
+                    },
+                    "verifier": {
+                      "type": "string"
+                    },
+                    "verdict": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "error": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "verificationId",
+                    "verifier",
+                    "verdict",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Missing header or field"
+          },
+          "409": {
+            "description": "No verification of this address in flight for that run"
+          },
+          "502": {
+            "description": "Refused (billing, key)"
+          }
+        }
+      }
+    },
+    "/internal/email-verifier-calls/apify": {
+      "get": {
+        "summary": "Whether BounceVerify is asked now (Apify not out of usage), for the stored verification script",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "email",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-api-key",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-org-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-user-id",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-caller-run-id",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Availability",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "available": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "available"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "No verification in flight"
+          }
+        }
+      }
+    },
+    "/internal/email-verification-decisions/recorded": {
+      "get": {
+        "summary": "Every verification decision with each vendor call and what was decided (service key; personal data)",
+        "description": "FACTORY-P3 next outcomes (email_found). Oldest first by `seq`, a row served 60 s after it was written. `path` = `service` (our waterfall on its own `email-verification` run) or `script` (the stored script while switched). `calls` = each vendor call in the stored script's words (`apollo.email.verify` {verifier, email} -> the bronze row; `apollo.apify.available`), `held` = the step-1 verdict reused (then only BounceBan runs), `result` = what was decided. Read by workflow-service's case recorder.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "after",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "1..1000, default 200"
+            },
+            "required": false,
+            "description": "1..1000, default 200",
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "x-api-key",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "One page",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "decisions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "nullable": true
+                        }
+                      }
+                    },
+                    "nextAfter": {
+                      "type": "integer"
+                    },
+                    "hasMore": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "decisions",
+                    "nextAfter",
+                    "hasMore"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/internal/email-verifications/history": {
       "get": {
         "summary": "Every email verification ever made, as a resumable feed",

src/db/schema.ts

@@ -466,6 +466,30 @@ export const emailVerifications = pgTable(
   ]
 );
 
+// FACTORY-P3 next outcomes (email_found, migration 0048): every verification DECISION with each vendor call in the
+// stored script's words (`calls`: name, args, answer) and what was decided, on either path (`service` = our waterfall
+// on its own `email-verification` run, `script` = the stored script while switched). Read only by
+// GET /internal/email-verification-decisions/recorded. Personal data: never logged.
+export const emailVerificationDecisions = pgTable(
+  "email_verification_decisions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    seq: bigserial("seq", { mode: "number" }).notNull(),
+    email: text("email").notNull(),
+    orgId: uuid("org_id").notNull(),
+    callerRunId: text("caller_run_id"),
+    runId: text("run_id"),
+    source: text("source"),
+    path: text("path").notNull(),
+    held: jsonb("held"),
+    calls: jsonb("calls").notNull(),
+    result: jsonb("result"),
+    error: text("error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [uniqueIndex("idx_email_verification_decisions_seq").on(table.seq), index("idx_email_verification_decisions_created").on(table.createdAt)]
+);
+
 // ─── QuickEnrich (free candidate source) ────────────────────────────────────
 // Bronze: every QuickEnrich search call through treg, verbatim.
 export const quickenrichSearches = pgTable(

src/index.ts

@@ -17,6 +17,7 @@ import transferBrandRoutes from "./routes/transfer-brand.js";
 import phoneRevealRoutes from "./routes/phone-reveal.js";
 import emailFinderRoutes from "./routes/email-finder.js";
 import emailVerificationRoutes from "./routes/email-verifications.js";
+import emailVerifierCallRoutes from "./routes/email-verifier-calls.js";
 import verificationHistoryRoutes from "./routes/verification-history.js";
 import acquisitionCostRoutes from "./routes/acquisition-costs.js";
 import webhookRoutes from "./routes/webhook.js";
@@ -71,6 +72,7 @@ app.use(matchRoutes);
 app.use(phoneRevealRoutes);
 app.use(emailFinderRoutes);
 app.use(emailVerificationRoutes);
+app.use(emailVerifierCallRoutes); // FACTORY-P3 next outcomes: the stored verification script's doors + recorded decisions
 app.use(verificationHistoryRoutes);
 app.use(acquisitionCostRoutes);
 app.use(transferBrandRoutes);