@warpgogol/werkstatt-shared 0.2.0

package/src/integration/port.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0168: the Integration Port. Vendor-agnostic contracts for delivering a captured
+lead to outbound channels (Telegram, email, WhatsApp) and upserting it into a CRM (Pipedrive),
+mirroring the growth (RFC-0027) and content-source (RFC-0141) port/adapter pattern. Pure — takes
+secrets as parameters; never imports astro:env (the section handler reads secrets and passes them).</purpose>
+<non-goals>
+  <item>Do not import vendor SDKs or astro:env here — adapters use fetch + injected secrets.</item>
+  <item>Do not log or return secrets.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0168: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { LifecycleEventPayload } from "./lifecycle.ts";
+
+/** Secrets bag (env name → value). Adapters read only their declared requiredSecrets. */
+export type IntegrationSecrets = Record<string, string | undefined>;
+
+export interface LeadMessage {
+  message: string;
+  formId: string;
+  locale: string;
+  /** ISO-8601 submission time. */
+  submittedAt: string;
+  contact?: { email?: string; phone?: string };
+}
+
+export interface Lead {
+  name?: string;
+  email?: string;
+  phone?: string;
+  note: string;
+  source: string;
+}
+
+export interface IntegrationChannelAdapter {
+  readonly id: string;
+  /** Env secret names required for this adapter to be active. */
+  readonly requiredSecrets: readonly string[];
+  /** Deliver the message. Throws on transport failure. */
+  deliver(message: LeadMessage, secrets: IntegrationSecrets): Promise<void>;
+}
+
+export interface CrmAdapter {
+  readonly id: string;
+  readonly requiredSecrets: readonly string[];
+  /** Upsert a lead. Returns the CRM id, or null. Throws on transport failure. */
+  upsertLead(lead: Lead, secrets: IntegrationSecrets): Promise<{ id: string } | null>;
+}
+
+// ---------------------------------------------------------------------------
+// RFC-0176: source-agnostic destination hub
+// ---------------------------------------------------------------------------
+
+/**
+ * Closed catalog of destination kinds the hub can route to (RFC-0176). The hub
+ * runs on the client's site with the client's tokens; "channel"/"crm" from
+ * RFC-0168 are subsumed here (a channel is a message/email destination).
+ */
+export const DESTINATION_KINDS = ["crm", "calendar", "email", "scheduler"] as const;
+export type DestinationKind = (typeof DESTINATION_KINDS)[number];
+
+/**
+ * How a configured destination is executed (RFC-0176):
+ *  - `gogol-adapter` (default): an adapter runs on the client's site with the
+ *    client's tokens — the studio's code routes, but on the client's deploy.
+ *  - `vendor-native` (optional): an upstream vendor's own flow executes it; the
+ *    studio holds no secret and runs no code for it (declared for validation +
+ *    the RFC-0177 processor disclosure only).
+ */
+export const EXECUTION_MODES = ["gogol-adapter", "vendor-native"] as const;
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+
+/**
+ * Normalized event produced by any IntegrationSource (the send-message form, the
+ * chat widget, future sources). Generalizes LeadMessage/Lead. `eventId` is the
+ * idempotency key the queue consumer dedups on (RFC-0176).
+ */
+export interface IntegrationEvent {
+  /** Idempotency key (source-provided) — dedup on redelivery. */
+  eventId: string;
+  kind: "lead" | "message" | "appointment";
+  /** Source id, e.g. "send-message" | "uchat" | "stripe". */
+  source: string;
+  locale: string;
+  /** ISO-8601 occurrence time. */
+  occurredAt: string;
+  contact?: { name?: string; email?: string; phone?: string };
+  payload: Record<string, unknown>;
+  /** RFC-0191: optional typed lifecycle payload for Stripe billing events. */
+  lifecycle?: LifecycleEventPayload;
+}
+
+/**
+ * A destination executed on the client's site (client tokens) — only for mode
+ * `gogol-adapter`. `vendor-native` destinations have no executed adapter.
+ */
+export interface DestinationAdapter {
+  readonly kind: DestinationKind;
+  readonly vendor: string;
+  readonly requiredSecrets: readonly string[];
+  /** Route the event to the destination. Returns its id, or null. Throws on transport failure. */
+  route(event: IntegrationEvent, secrets: IntegrationSecrets): Promise<{ id: string } | null>;
+}
+
+/** Map a normalized event onto the RFC-0168 LeadMessage shape (for channel fan-out). */
+export function eventToLeadMessage(event: IntegrationEvent): LeadMessage {
+  const message =
+    typeof event.payload.message === "string"
+      ? event.payload.message
+      : typeof event.payload.note === "string"
+        ? (event.payload.note as string)
+        : "";
+  const email = event.contact?.email;
+  const phone = event.contact?.phone;
+  return {
+    message,
+    formId: event.source,
+    locale: event.locale,
+    submittedAt: event.occurredAt,
+    ...(email || phone
+      ? { contact: { ...(email ? { email } : {}), ...(phone ? { phone } : {}) } }
+      : {}),
+  };
+}
+
+/** Map a normalized `lead`-kind event onto the RFC-0168 Lead shape (back-compat). */
+export function eventToLead(event: IntegrationEvent): Lead {
+  const note =
+    typeof event.payload.note === "string"
+      ? event.payload.note
+      : ((event.payload.message as string) ?? "");
+  return {
+    name: event.contact?.name,
+    email: event.contact?.email,
+    phone: event.contact?.phone,
+    note,
+    source: event.source,
+  };
+}

package/src/integration/qstash.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0181: EU-resident delivery substrate. buildQstashPublish constructs the HTTPS request that
+publishes an IntegrationEvent to Upstash QStash in the EU region (eu-central-1, Frankfurt) — with
+content dedup and a retry count — for reliable webhook delivery back to the site's own callback. The
+IdempotencyLedger (Upstash Redis EU) is the durable first-seen guard the callback consults before
+routing. Pure: buildQstashPublish does no I/O; the ledger is an injectable interface. Replaces the
+Cloudflare Queues/KV substrate (RFC-0179), which cannot be EU-pinned.</purpose>
+<non-goals>
+  <item>Do not log or embed secrets (UPSTASH_QSTASH_TOKEN, Redis token) — caller injects them.</item>
+  <item>Do not publish lead PII to the US region or a non-EU base URL.</item>
+  <item>Do not verify QStash webhook signatures here — the route uses @upstash/qstash Receiver.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0181: initial EU delivery substrate (QStash + Redis, eu-central-1).</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { IntegrationEvent } from "./port.ts";
+
+/** EU-region QStash base URL — the residency pin (Frankfurt, eu-central-1). RFC-0181. */
+export const QSTASH_EU_BASE = "https://qstash-eu-central-1.upstash.io" as const;
+
+/**
+ * Canonical server-secret NAMES for the EU delivery substrate (RFC-0181). Single
+ * source of truth for the env schema, the .env.example generator, and validators.
+ * Values are read via `astro:env/server`; never logged, returned, or committed.
+ *  - `UPSTASH_QSTASH_URL`            — the EU QStash base (must be the eu-central-1 endpoint).
+ *  - `UPSTASH_QSTASH_TOKEN`          — publish token (Bearer).
+ *  - `UPSTASH_QSTASH_CURRENT_SIGNING_KEY` / `…_NEXT_SIGNING_KEY` — webhook signature verification.
+ *  - `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` — the EU Redis idempotency ledger.
+ */
+export const UPSTASH_QSTASH_SECRETS = [
+  "UPSTASH_QSTASH_URL",
+  "UPSTASH_QSTASH_TOKEN",
+  "UPSTASH_QSTASH_CURRENT_SIGNING_KEY",
+  "UPSTASH_QSTASH_NEXT_SIGNING_KEY",
+] as const;
+
+export const UPSTASH_REDIS_SECRETS = [
+  "UPSTASH_REDIS_REST_URL",
+  "UPSTASH_REDIS_REST_TOKEN",
+] as const;
+
+/** Every EU-delivery secret name (QStash + Redis). RFC-0181. */
+export const UPSTASH_DELIVERY_SECRETS = [
+  ...UPSTASH_QSTASH_SECRETS,
+  ...UPSTASH_REDIS_SECRETS,
+] as const;
+
+export interface QstashPublishConfig {
+  /** UPSTASH_QSTASH_TOKEN — server secret. Never logged. */
+  token: string;
+  /** The site's own absolute callback URL (its /internal/integration-route). */
+  callbackUrl: string;
+  /** QStash retry count (exponential backoff). Default 3. */
+  retries?: number;
+  /** Base URL — defaults to the EU region. Overriding to a non-EU base breaks residency. */
+  baseUrl?: string;
+}
+
+/**
+ * Pure (RFC-0181): build the HTTPS request that publishes `event` to QStash EU
+ * for reliable webhook delivery to `config.callbackUrl`. QStash dedups on
+ * `Upstash-Deduplication-Id` (the eventId) and retries to the callback, then
+ * dead-letters. No I/O — the caller performs the fetch with this Request.
+ */
+export function buildQstashPublish(event: IntegrationEvent, config: QstashPublishConfig): Request {
+  const base = config.baseUrl ?? QSTASH_EU_BASE;
+  // QStash v2: POST /v2/publish/{destination-url}; the body is forwarded to the destination.
+  // Do NOT encode the callback URL — QStash expects the raw URL in the path segment.
+  // encodeURIComponent breaks scheme detection because %3A is not decoded back to :.
+  const url = `${base}/v2/publish/${config.callbackUrl}`;
+  return new Request(url, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      "content-type": "application/json",
+      "upstash-deduplication-id": event.eventId,
+      "upstash-retries": String(config.retries ?? 3),
+    },
+    body: JSON.stringify(event),
+  });
+}
+
+/**
+ * Durable idempotency ledger (RFC-0181) backed by Upstash Redis in the EU.
+ * `firstSeen` returns true exactly once per eventId (SET NX), so a QStash
+ * redelivery never double-writes into the client's CRM. Stores only the eventId
+ * key with a short TTL — never PII.
+ */
+export interface IdempotencyLedger {
+  firstSeen(eventId: string, ttlSeconds?: number): Promise<boolean>;
+}
+
+/** Minimal structural type for the Upstash Redis REST endpoint (no hard dep). */
+export interface RestRedisConfig {
+  /** UPSTASH_REDIS_REST_URL — must be the eu-central-1 endpoint for EU residency. */
+  url: string;
+  /** UPSTASH_REDIS_REST_TOKEN — server secret. Never logged. */
+  token: string;
+  /** Key prefix; defaults to the integration dedup namespace. */
+  prefix?: string;
+}
+
+/**
+ * Adapt an Upstash Redis REST endpoint to the IdempotencyLedger (RFC-0181). Uses
+ * `SET key 1 NX EX ttl`; a `{"result":"OK"}` means first-seen, `null` means the
+ * key already existed (a redelivery). Fails closed on a transport error by
+ * throwing, so the callback retries rather than risk a double-write.
+ */
+export function restRedisLedger(
+  config: RestRedisConfig,
+  fetchImpl: typeof fetch = fetch,
+): IdempotencyLedger {
+  const prefix = config.prefix ?? "gogol-int-dedup";
+  return {
+    async firstSeen(eventId: string, ttlSeconds = 86400): Promise<boolean> {
+      const key = `${prefix}:${eventId}`;
+      const command = ["SET", key, "1", "NX", "EX", String(ttlSeconds)];
+      const response = await fetchImpl(config.url, {
+        method: "POST",
+        headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
+        body: JSON.stringify(command),
+      });
+      if (!response.ok) {
+        throw new Error(`redis ledger SET failed: ${response.status}`);
+      }
+      const data = (await response.json()) as { result?: string | null };
+      return data.result === "OK";
+    },
+  };
+}

package/src/integration/sharding.ts

@@ -0,0 +1,133 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0179: deterministic placement of a site on the shared, sharded delivery backbone.
+resolveShard maps a stable siteId + region + tier onto a concrete queue / DLQ / dedup-namespace
+set, so the shared queues replace RFC-0176's per-client queue without a central registry — the
+mapping is recomputable from content alone. Pure: no I/O, no platform bindings.</purpose>
+<non-goals>
+  <item>Do not create or call Cloudflare resources — this is a pure naming/placement function.</item>
+  <item>Do not read system.md or any file — callers pass region/tier explicitly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0179: initial implementation.</item>
+  <item>RFC-0181: the Cloudflare-queue naming here is SUPERSEDED for the EU delivery path (Upstash QStash/Redis, see qstash.ts). Retained for the deferred WfP/CF-hosted topology; not used for EU lead delivery.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Closed catalog of delivery jurisdictions (RFC-0179). Drives residency sharding. */
+export const DELIVERY_REGIONS = ["eu", "us"] as const;
+export type DeliveryRegion = (typeof DELIVERY_REGIONS)[number];
+
+/** Execution tier on the shared backbone (RFC-0179). */
+export const DELIVERY_TIERS = ["shared", "dedicated"] as const;
+export type DeliveryTier = (typeof DELIVERY_TIERS)[number];
+
+/** Resolved placement of a site on the shared delivery backbone (RFC-0179). */
+export interface ShardAssignment {
+  siteId: string;
+  region: DeliveryRegion;
+  tier: DeliveryTier;
+  /** Shared-pool shard index, or -1 for a dedicated queue. */
+  shardIndex: number;
+  /** Queue name, e.g. "gogol-int-eu-shared-02" or "gogol-int-eu-ded-acme". */
+  queue: string;
+  /** Dead-letter queue name (queue + "-dlq"). */
+  dlq: string;
+  /** Region dedup KV namespace title, e.g. "gogol-int-dedup-eu". */
+  dedupNamespace: string;
+  /** Consumer Worker name bound to `queue` (one consumer per queue). */
+  consumer: string;
+}
+
+/** Options for resolveShard. `shardCount` is the size of the region's shared pool. */
+export interface ResolveShardOptions {
+  tier?: DeliveryTier;
+  /** Number of queues in the region's shared pool. Must be ≥ 1. Default 4. */
+  shardCount?: number;
+}
+
+/**
+ * Deterministic 32-bit FNV-1a hash of a string. Stable across runtimes (no
+ * dependency on Math.random or hash seeds), so a siteId always lands on the same
+ * shard — the property re-sharding safety and registry-free placement rely on.
+ */
+export function fnv1a(input: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    // hash *= 16777619, kept in 32-bit unsigned space.
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+/** Two-digit shard suffix ("00".."99"+) for stable, sortable queue names. */
+function shardSuffix(index: number): string {
+  return index < 10 ? `0${index}` : String(index);
+}
+
+/**
+ * Sanitize a siteId into a Cloudflare-safe resource-name segment: lowercase,
+ * alphanumeric + single dashes. Keeps names deterministic for dedicated queues.
+ */
+function safeSegment(siteId: string): string {
+  return siteId
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+/**
+ * Resolve a site's place on the shared, sharded delivery backbone (RFC-0179).
+ *
+ * - `shared` tier: the site is hashed into one of `shardCount` queues in the
+ *   region's shared pool — `gogol-int-{region}-shared-{NN}`. Blast radius is
+ *   bounded to 1/shardCount of the pool.
+ * - `dedicated` tier: the site gets its own queue `gogol-int-{region}-ded-{siteId}`
+ *   so a noisy/high-volume client cannot exhaust a shared pool's backlog.
+ *
+ * Dedup is a single region-scoped KV namespace in both tiers (keys are
+ * `{siteId}:{eventId}:{dest}`, unlimited per namespace).
+ *
+ * Pure + deterministic: the same inputs always yield the same assignment, so the
+ * placement is recomputable from content with no central registry.
+ */
+export function resolveShard(
+  siteId: string,
+  region: DeliveryRegion,
+  opts: ResolveShardOptions = {},
+): ShardAssignment {
+  if (!siteId) throw new Error("resolveShard: siteId is required");
+  const tier: DeliveryTier = opts.tier ?? "shared";
+  const shardCount = Math.max(1, opts.shardCount ?? 4);
+  const dedupNamespace = `gogol-int-dedup-${region}`;
+
+  if (tier === "dedicated") {
+    const queue = `gogol-int-${region}-ded-${safeSegment(siteId)}`;
+    return {
+      siteId,
+      region,
+      tier,
+      shardIndex: -1,
+      queue,
+      dlq: `${queue}-dlq`,
+      dedupNamespace,
+      consumer: `${queue}-consumer`,
+    };
+  }
+
+  const shardIndex = fnv1a(siteId) % shardCount;
+  const queue = `gogol-int-${region}-shared-${shardSuffix(shardIndex)}`;
+  return {
+    siteId,
+    region,
+    tier,
+    shardIndex,
+    queue,
+    dlq: `${queue}-dlq`,
+    dedupNamespace,
+    consumer: `${queue}-consumer`,
+  };
+}

package/src/integration/tests/deliver-event.test.ts

@@ -0,0 +1,52 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0181: verify the unified deliverEvent fan-out (channels + destinations) and the
+eventToLeadMessage mapping. With no secrets every sink is skipped (not failed), so a misconfigured
+site never spuriously retries. No network — adapters self-skip on absent secrets.</purpose>
+<responsibilities>
+  <item>eventToLeadMessage maps source/locale/occurredAt/contact + payload.message.</item>
+  <item>deliverEvent with no secrets skips all channels + the CRM destination (no failures).</item>
+</responsibilities>
+<non-goals><item>No network.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0181: initial deliverEvent test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { deliverEvent, eventToLeadMessage } from "../index.ts";
+import type { IntegrationEvent } from "../port.ts";
+
+const EVENT: IntegrationEvent = {
+  eventId: "evt-1",
+  kind: "lead",
+  source: "send-message",
+  locale: "de",
+  occurredAt: "2026-06-08T00:00:00.000Z",
+  contact: { email: "a@example.de" },
+  payload: { message: "Hallo" },
+};
+
+test("eventToLeadMessage maps the event onto a LeadMessage", () => {
+  const msg = eventToLeadMessage(EVENT);
+  expect(msg.message).toBe("Hallo");
+  expect(msg.formId).toBe("send-message");
+  expect(msg.locale).toBe("de");
+  expect(msg.submittedAt).toBe("2026-06-08T00:00:00.000Z");
+  expect(msg.contact?.email).toBe("a@example.de");
+});
+
+test("deliverEvent with no secrets skips every sink (no failures, no retry)", async () => {
+  const result = await deliverEvent(EVENT, {});
+  expect(result.channels.delivered.length).toBe(0);
+  expect(result.channels.failed.length).toBe(0);
+  expect(result.channels.skipped.includes("telegram")).toBeTruthy();
+  expect(result.channels.skipped.includes("whatsapp")).toBeTruthy();
+  expect(result.destinations.routed.length).toBe(0);
+  expect(result.destinations.failed.length).toBe(0);
+  expect(result.destinations.skipped.includes("crm:pipedrive")).toBeTruthy();
+});
+
+test("email is no longer a fetch channel adapter (Cloudflare Email Routing handles it)", async () => {
+  const result = await deliverEvent(EVENT, {});
+  expect(!result.channels.skipped.includes("email")).toBeTruthy();
+});

package/src/integration/tests/dispatch.test.ts

@@ -0,0 +1,88 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0179: verify the dynamic-dispatch seam. executeDispatch (tenant-side) runs ready
+destinations with local secrets; dispatchToTenant (consumer-side) posts into the tenant, never
+carries a destination token, and maps the reply to ack vs retry. fetch/dispatcher are stubbed.</purpose>
+<responsibilities>
+  <item>executeDispatch skips destinations when the tenant has no secrets (no network).</item>
+  <item>dispatchToTenant returns ok on a routed reply and retry on all-failed / non-2xx / throw.</item>
+  <item>dispatchToTenant sends the inbound secret header and never the destination token.</item>
+</responsibilities>
+<non-goals><item>No network — fetch + dispatcher are stubbed.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0179: initial dispatch-seam test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import {
+  dispatchToTenant,
+  executeDispatch,
+  type DispatchExecuteResult,
+  type DispatchNamespaceBinding,
+} from "../dispatch.ts";
+import type { IntegrationEvent } from "../port.ts";
+
+const EVENT: IntegrationEvent = {
+  eventId: "evt-1",
+  kind: "lead",
+  source: "uchat",
+  locale: "de",
+  occurredAt: new Date().toISOString(),
+  contact: { name: "A", email: "a@example.org" },
+  payload: { message: "hi" },
+};
+
+test("executeDispatch skips destinations when the tenant holds no secrets", async () => {
+  const result = await executeDispatch({ siteId: "warpgogol-com", event: EVENT }, {});
+  expect(result.routed.length).toBe(0);
+  expect(result.skipped.includes("crm:pipedrive")).toBeTruthy();
+});
+
+function stubDispatcher(
+  reply: DispatchExecuteResult,
+  status = 200,
+  capture?: (r: Request) => void,
+) {
+  const binding: DispatchNamespaceBinding = {
+    get() {
+      return {
+        async fetch(request: Request): Promise<Response> {
+          capture?.(request);
+          return new Response(JSON.stringify(reply), { status });
+        },
+      };
+    },
+  };
+  return binding;
+}
+
+test("dispatchToTenant acks on a routed reply and forwards only the inbound secret", async () => {
+  let seen: Request | undefined;
+  const dispatcher = stubDispatcher(
+    { routed: ["crm:pipedrive"], failed: [], skipped: [] },
+    200,
+    (r) => (seen = r),
+  );
+  const outcome = await dispatchToTenant(
+    dispatcher,
+    { siteId: "warpgogol-com", event: EVENT },
+    "inbound-secret",
+  );
+  expect(outcome.ok).toBe(true);
+  expect(seen?.headers.get("x-integration-secret")).toBe("inbound-secret");
+  const body = await seen!.text();
+  expect(!body.includes("PIPEDRIVE")).toBeTruthy();
+});
+
+test("dispatchToTenant retries when nothing routed but something failed", async () => {
+  const dispatcher = stubDispatcher({ routed: [], failed: ["crm:pipedrive"], skipped: [] });
+  const outcome = await dispatchToTenant(dispatcher, { siteId: "x", event: EVENT }, "s");
+  expect(outcome.ok).toBe(false);
+});
+
+test("dispatchToTenant retries on a non-2xx tenant response", async () => {
+  const dispatcher = stubDispatcher({ routed: [], failed: [], skipped: [] }, 503);
+  const outcome = await dispatchToTenant(dispatcher, { siteId: "x", event: EVENT }, "s");
+  expect(outcome.ok).toBe(false);
+  expect(outcome.transportError ?? "").toMatch(/503/);
+});

package/src/integration/tests/funnel-bridge.test.ts

@@ -0,0 +1,46 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0188 Phase 3: prove the canonical→generic stage bridge is total and lands only on
+valid generic stages, so the Pipedrive sync worker (STAGE_MAP) keeps working while the precise
+funnel_stage is preserved. Pure — no I/O.</purpose>
+<responsibilities>
+  <item>FUNNEL_STAGE_TO_BUFFER_STAGE covers every canonical stage and maps into BUFFER_DEAL_STAGES.</item>
+  <item>Terminal stages bridge to their generic equivalents; isFunnelStage guards the catalog.</item>
+</responsibilities>
+<non-goals><item>No DB — the bridge is a pure mapping.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0188 Phase 3: initial stage-bridge test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import {
+  BUFFER_DEAL_STAGES,
+  FUNNEL_STAGE_TO_BUFFER_STAGE,
+  bridgeFunnelStage,
+  isFunnelStage,
+} from "../crm-buffer.ts";
+import { VISITOR_FUNNEL_STAGES } from "../funnel.ts";
+
+test("the bridge maps every canonical funnel stage onto a valid generic stage", () => {
+  const generic = new Set<string>(BUFFER_DEAL_STAGES);
+  for (const stage of VISITOR_FUNNEL_STAGES) {
+    const mapped = FUNNEL_STAGE_TO_BUFFER_STAGE[stage];
+    expect(mapped).toBeTruthy();
+    expect(generic.has(mapped)).toBeTruthy();
+  }
+  // Totality: no extra keys beyond the canonical catalog.
+  expect(Object.keys(FUNNEL_STAGE_TO_BUFFER_STAGE).length).toBe(VISITOR_FUNNEL_STAGES.length);
+});
+
+test("terminal funnel stages bridge to their generic equivalents", () => {
+  expect(bridgeFunnelStage("won")).toBe("won");
+  expect(bridgeFunnelStage("lost")).toBe("lost");
+  expect(bridgeFunnelStage("offer_presented")).toBe("proposal");
+  expect(bridgeFunnelStage("new_session")).toBe("new");
+});
+
+test("isFunnelStage guards the canonical catalog", () => {
+  expect(isFunnelStage("offer_presented")).toBe(true);
+  expect(isFunnelStage("q_website_tier")).toBe(false); // legacy UChat string
+  expect(isFunnelStage("new")).toBe(false); // generic buffer stage, not a funnel stage
+});