@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/contacts/__tests__/guardian-delivery-reader.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Tests for the gateway-backed guardian delivery reader.
+ *
+ * Guardian binding is near-static, so the reader caches behind a minutes-scale
+ * TTL, clears event-driven on invalidation, and coalesces concurrent cold-cache
+ * reads single-flight. These tests pin the parse contract plus all three cache
+ * behaviors (TTL hit, invalidation, single-flight) and the failure-no-poison
+ * rule.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+// ── Controllable IPC mock ────────────────────────────────────────────────────
+
+type IpcHandler = (params?: Record<string, unknown>) => unknown;
+
+const ipcHandlers = new Map<string, IpcHandler>();
+const ipcCallLog: Array<{
+  method: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+}> = [];
+
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCall: async (
+    method: string,
+    params?: Record<string, unknown>,
+    timeoutMs?: number,
+  ) => {
+    ipcCallLog.push({ method, params, timeoutMs });
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+import { emitContactChange } from "../contact-events.js";
+import {
+  __resetGuardianDeliveryCacheForTest,
+  anyGuardian,
+  getGuardianDelivery,
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+  invalidateGuardianDeliveryCache,
+} from "../guardian-delivery-reader.js";
+
+const METHOD = "resolve_guardian_delivery";
+
+function countCalls(method: string): number {
+  return ipcCallLog.filter((c) => c.method === method).length;
+}
+
+const telegramGuardian: GuardianDelivery = {
+  channelType: "telegram",
+  contactId: "contact-123",
+  address: "@guardian",
+  status: "active",
+};
+
+const emailGuardian: GuardianDelivery = {
+  channelType: "email",
+  contactId: "contact-456",
+  address: "guardian@example.com",
+  status: "active",
+};
+
+describe("getGuardianDelivery", () => {
+  beforeEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+    ipcHandlers.clear();
+    ipcCallLog.length = 0;
+  });
+
+  test("returns the parsed guardian list", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+  });
+
+  test("bounds the IPC read with a short timeout", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+
+    await getGuardianDelivery();
+
+    const call = ipcCallLog.find((c) => c.method === METHOD);
+    expect(call?.timeoutMs).toBe(2_000);
+  });
+
+  test("returns null when IPC transport fails (undefined)", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("returns null when the IPC call throws", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("socket exploded");
+    });
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("returns null for a malformed response shape", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: "not-an-array" }));
+    expect(await getGuardianDelivery()).toBeNull();
+  });
+
+  test("two calls within the TTL issue only ONE IPC call (cache hit)", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("caches per channelTypes filter key", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    await getGuardianDelivery({ channelTypes: ["telegram"] });
+
+    // Distinct keys ("ALL" vs "telegram") miss each other → two IPC calls.
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("invalidateGuardianDeliveryCache() forces the next call to re-fetch", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    invalidateGuardianDeliveryCache();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a contact-change event clears the cache", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+
+    await getGuardianDelivery();
+    emitContactChange();
+    await getGuardianDelivery();
+
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a burst of concurrent cold-cache calls issues only ONE IPC call (single-flight)", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    const burst = Promise.all([
+      getGuardianDelivery(),
+      getGuardianDelivery(),
+      getGuardianDelivery(),
+    ]);
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    const results = await burst;
+
+    expect(countCalls(METHOD)).toBe(1);
+    expect(results).toEqual([
+      [telegramGuardian],
+      [telegramGuardian],
+      [telegramGuardian],
+    ]);
+  });
+
+  test("an invalidation DURING an in-flight fetch is not masked — the next call re-fetches", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    // Start a cold fetch, invalidate before it resolves, then resolve it.
+    const inFlight = getGuardianDelivery();
+    invalidateGuardianDeliveryCache();
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    expect(await inFlight).toEqual([telegramGuardian]);
+
+    // The pre-invalidation result must NOT have been cached: the next read
+    // issues a fresh IPC rather than serving the now-stale value.
+    ipcHandlers.set(METHOD, () => ({ guardians: [emailGuardian] }));
+    expect(await getGuardianDelivery()).toEqual([emailGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a failure does NOT poison the cache — the next call retries", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getGuardianDelivery()).toBeNull();
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("fresh read ignores a stale cached entry and re-fetches", async () => {
+    // Seed the cache with an empty list (the stale gateway-side view).
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    expect(await getGuardianDelivery()).toEqual([]);
+
+    // A cached read still serves the stale empty list (no new IPC)...
+    expect(await getGuardianDelivery()).toEqual([]);
+    expect(countCalls(METHOD)).toBe(1);
+
+    // ...but a fresh read bypasses the cache and sees the now-present guardian.
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(await getGuardianDeliveryFresh()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("fresh read updates the cache with the fresh result", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    await getGuardianDelivery();
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    await getGuardianDeliveryFresh();
+
+    // A subsequent cached read serves the refreshed value without a new IPC.
+    expect(await getGuardianDelivery()).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("getGuardianDeliveryFresh bypasses a stale cached empty list", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [] }));
+    expect(
+      await getGuardianDelivery({ channelTypes: ["telegram"] }),
+    ).toEqual([]);
+
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    expect(
+      await getGuardianDeliveryFresh({ channelTypes: ["telegram"] }),
+    ).toEqual([telegramGuardian]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("a burst of forceRefresh reads still coalesces single-flight", async () => {
+    let resolveIpc: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveIpc = resolve;
+        }),
+    );
+
+    const burst = Promise.all([
+      getGuardianDeliveryFresh(),
+      getGuardianDeliveryFresh(),
+      getGuardianDeliveryFresh(),
+    ]);
+    resolveIpc?.({ guardians: [telegramGuardian] });
+    await burst;
+
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("a fresh read does NOT coalesce with an in-flight non-force fetch (issues its own IPC)", async () => {
+    // A normal read starts a fetch that will resolve to the pre-write empty
+    // list and is still in flight when the fresh read arrives.
+    let resolveStale: ((value: unknown) => void) | undefined;
+    ipcHandlers.set(
+      METHOD,
+      () =>
+        new Promise((resolve) => {
+          resolveStale = resolve;
+        }),
+    );
+    const stale = getGuardianDelivery();
+
+    // The gateway-side write lands (not reflected in the in-flight fetch). The
+    // fresh read must NOT reuse the stale in-flight promise — it issues its own
+    // IPC observing the post-write guardian.
+    ipcHandlers.set(METHOD, () => ({ guardians: [telegramGuardian] }));
+    const fresh = await getGuardianDeliveryFresh();
+    expect(fresh).toEqual([telegramGuardian]);
+
+    // Release the stale fetch last; it must not have masked the fresh result.
+    resolveStale?.({ guardians: [] });
+    expect(await stale).toEqual([]);
+    expect(countCalls(METHOD)).toBe(2);
+  });
+});
+
+describe("selectors", () => {
+  test("guardianForChannel picks the first active match for the type", () => {
+    const inactive: GuardianDelivery = {
+      ...telegramGuardian,
+      contactId: "contact-999",
+      status: "revoked",
+    };
+    const list = [inactive, telegramGuardian, emailGuardian];
+
+    expect(guardianForChannel(list, "telegram")).toBe(telegramGuardian);
+    expect(guardianForChannel(list, "email")).toBe(emailGuardian);
+    expect(guardianForChannel(list, "phone")).toBeUndefined();
+  });
+
+  test("anyGuardian returns the first overall", () => {
+    expect(anyGuardian([emailGuardian, telegramGuardian])).toBe(emailGuardian);
+    expect(anyGuardian([])).toBeUndefined();
+  });
+});

package/src/contacts/__tests__/member-write-relay.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Tests for the gateway-first member-activation relay.
+ *
+ * activateMemberChannel writes the activated channel through the gateway
+ * (source of truth) via `ipcCallPersistent("upsert_verified_channel", ...)`
+ * first, then mirrors the activation to the assistant DB best-effort. A local
+ * mirror failure is swallowed so the gateway-owned outcome stands; a gateway
+ * refusal (verified:false) skips the local mirror entirely.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ContactWriteResult } from "../types.js";
+
+type IpcCall = { method: string; params?: Record<string, unknown> };
+
+let ipcCalls: IpcCall[] = [];
+let ipcVerified = true;
+let ipcThrows = false;
+
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcThrows) throw new Error("gateway unavailable");
+    return {
+      ok: true,
+      verified: ipcVerified,
+      channel: ipcVerified
+        ? {
+            id: "gw-ch1",
+            contactId: (params?.contactId as string) ?? "gw-c1",
+            type: (params?.type as string) ?? "telegram",
+            address: (params?.address as string) ?? "addr",
+            status: "active",
+            verifiedAt: 1,
+            verifiedVia: (params?.verifiedVia as string) ?? "invite",
+          }
+        : undefined,
+    };
+  },
+);
+const actualGatewayClient = await import("../../ipc/gateway-client.js");
+mock.module("../../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+// Local-mirror primitive.
+const localResult: ContactWriteResult = {
+  contact: { id: "c1" } as ContactWriteResult["contact"],
+  channel: { id: "ch1" } as ContactWriteResult["channel"],
+};
+let mirrorCallOrder = -1;
+const upsertContactChannelMock = mock(
+  (_params: Record<string, unknown>): ContactWriteResult | null => {
+    mirrorCallOrder = ipcCalls.length;
+    return localResult;
+  },
+);
+const actualContactsWrite = await import("../contacts-write.js");
+mock.module("../contacts-write.js", () => ({
+  ...actualContactsWrite,
+  upsertContactChannel: upsertContactChannelMock,
+}));
+
+const { activateMemberChannel } = await import("../member-write-relay.js");
+
+describe("activateMemberChannel gateway-first relay", () => {
+  beforeEach(() => {
+    ipcCalls = [];
+    ipcVerified = true;
+    ipcThrows = false;
+    mirrorCallOrder = -1;
+    ipcCallPersistentMock.mockClear();
+    upsertContactChannelMock.mockClear();
+    upsertContactChannelMock.mockImplementation(() => {
+      mirrorCallOrder = ipcCalls.length;
+      return localResult;
+    });
+  });
+
+  test("relays to the gateway before mirroring locally, threading the target contact", async () => {
+    const result = await activateMemberChannel({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+      displayName: "Mom",
+      contactId: "target-mom",
+      inviteId: "inv-1",
+      verifiedVia: "invite",
+    });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: "upsert_verified_channel",
+        params: {
+          type: "telegram",
+          address: "user-1",
+          externalChatId: "chat-1",
+          displayName: "Mom",
+          username: undefined,
+          verifiedVia: "invite",
+          contactId: "target-mom",
+          allowRevokedReactivation: true,
+        },
+      },
+    ]);
+    // The local mirror ran AFTER the gateway relay.
+    expect(mirrorCallOrder).toBe(1);
+    expect(upsertContactChannelMock).toHaveBeenCalledTimes(1);
+
+    // The local mirror persists identity/INFO only — no ACL columns. The
+    // gateway owns status/policy/verification.
+    const mirrorArgs = upsertContactChannelMock.mock.calls[0]![0] as Record<
+      string,
+      unknown
+    >;
+    expect(mirrorArgs).toEqual({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+      displayName: "Mom",
+      username: undefined,
+      inviteId: "inv-1",
+      contactId: "target-mom",
+    });
+    for (const aclKey of [
+      "status",
+      "policy",
+      "role",
+      "verifiedAt",
+      "verifiedVia",
+    ]) {
+      expect(aclKey in mirrorArgs).toBe(false);
+    }
+
+    expect(result).toEqual({
+      status: "activated",
+      memberId: "ch1",
+      member: localResult,
+    });
+  });
+
+  test("fails closed and skips the local mirror when the gateway relay throws", async () => {
+    ipcThrows = true;
+
+    const result = await activateMemberChannel({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+      contactId: "target-mom",
+    });
+
+    expect(ipcCalls).toHaveLength(1);
+    // Identity-only mirror would land at the schema-default unverified status, so
+    // a failed gateway write must not report success off it.
+    expect(upsertContactChannelMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ status: "refused" });
+  });
+
+  test("returns the gateway channel id when the gateway verifies but the local mirror throws", async () => {
+    upsertContactChannelMock.mockImplementation(() => {
+      throw new Error("local mirror exploded");
+    });
+
+    const result = await activateMemberChannel({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+    });
+
+    expect(ipcCalls).toHaveLength(1);
+    // Gateway activation stands: the gateway channel id is returned even though
+    // the best-effort local mirror produced no row.
+    expect(result).toEqual({
+      status: "activated",
+      memberId: "gw-ch1",
+      member: null,
+    });
+  });
+
+  test("refuses when the gateway throws even if the local mirror would have thrown", async () => {
+    ipcThrows = true;
+    upsertContactChannelMock.mockImplementation(() => {
+      throw new Error("local mirror exploded");
+    });
+
+    const result = await activateMemberChannel({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+    });
+
+    // Fail-closed: a thrown gateway write refuses before the mirror is touched.
+    expect(upsertContactChannelMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ status: "refused" });
+  });
+
+  test("refuses the activation when the gateway denies the actor (verified:false)", async () => {
+    ipcVerified = false;
+
+    const result = await activateMemberChannel({
+      sourceChannel: "telegram",
+      externalUserId: "user-1",
+      externalChatId: "chat-1",
+      contactId: "target-mom",
+    });
+
+    expect(ipcCalls).toHaveLength(1);
+    expect(upsertContactChannelMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ status: "refused" });
+  });
+
+  test("derives the address from externalChatId when no externalUserId is present", async () => {
+    await activateMemberChannel({
+      sourceChannel: "phone",
+      externalChatId: "+15551234567",
+    });
+
+    expect(ipcCalls[0]?.params).toMatchObject({
+      type: "phone",
+      address: "+15551234567",
+      externalChatId: "+15551234567",
+    });
+  });
+});