@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/__tests__/contacts-relay-reads.test.ts

@@ -65,6 +65,8 @@ mock.module("../ipc/gateway-client.js", () => ({
 // Assistant-DB fallback stubs — assert these are NOT hit on the happy path,
 // and that they ARE hit on the IPC-failure fallback path.
 const localCalls: string[] = [];
+// Per-test override for the daemon-native searchContacts result. Null → default.
+let searchContactsResult: unknown[] | null = null;
 const realContactStore = await import("../contacts/contact-store.js");
 // Capture the args passed to the daemon-native listContacts so tests can assert
 // contactType is filtered in SQL (before the limit) rather than relayed.
@@ -106,16 +108,18 @@ mock.module("../contacts/contact-store.js", () => ({
   },
   searchContacts: () => {
     localCalls.push("searchContacts");
-    return [
-      {
-        id: "search-1",
-        displayName: "Search Contact",
-        role: "contact",
-        contactType: "human",
-        interactionCount: 0,
-        channels: [],
-      },
-    ];
+    return (
+      searchContactsResult ?? [
+        {
+          id: "search-1",
+          displayName: "Search Contact",
+          role: "contact",
+          contactType: "human",
+          interactionCount: 0,
+          channels: [],
+        },
+      ]
+    );
   },
 }));
 
@@ -187,8 +191,33 @@ beforeEach(() => {
   debugLogs.length = 0;
   listContactsArgs.length = 0;
   guardianIds = new Set();
+  searchContactsResult = null;
 });
 
+/**
+ * Pin the daemon-native gateway boundary: the query/filter is resolved LOCALLY,
+ * so the gateway is NEVER asked to RESOLVE it. The only permitted gateway IPC on
+ * these paths is the telemetry overlay (`hydrateTelemetryFromGateway`), and it
+ * must carry ONLY the already-resolved result-set `ids` — never the
+ * query/contactType/channelType/channelAddress/role/limit filter params. The
+ * exact `toEqual({ ids })` match guarantees no filter key leaked into the relay.
+ */
+function expectOnlyIdsScopedTelemetryHydration(expectedIds: string[]) {
+  expect(ipcCalls.map((c) => c.method)).toEqual(["contacts_list_rich"]);
+  expect(ipcCalls[0]?.params).toEqual({ ids: expectedIds });
+}
+
+/** Telemetry-overlay stub: gateway returns rich telemetry for the ids-scoped
+ * hydration read, keyed to the locally-resolved contact. */
+function telemetryHydrationStub(id: string, interactionCount: number): IpcStub {
+  return (method) => {
+    if (method === "contacts_list_rich") {
+      return { ok: true, contacts: [gatewayContact({ id, interactionCount })] };
+    }
+    return undefined;
+  };
+}
+
 describe("handleListContacts relay", () => {
   test("non-search read serves gateway contacts and does NOT read assistant DB", async () => {
     ipcStub = (method) => {
@@ -239,70 +268,206 @@ describe("handleListContacts relay", () => {
     expect(localCalls).toEqual([]);
   });
 
-  test("search params stay daemon-native and log the boundary note", async () => {
+  test("search params stay daemon-native; query stays local while ids-scoped gateway telemetry is overlaid", async () => {
+    // The query is resolved LOCALLY (searchContacts) and the boundary note is
+    // logged. The gateway is NOT asked to resolve the query — its only call is
+    // the ids-scoped telemetry overlay, which then hydrates interactionCount.
+    ipcStub = telemetryHydrationStub("search-1", 7);
+
     const result = await handleListContacts({ query: "alice" });
 
-    expect(ipcCalls).toEqual([]);
     expect(localCalls).toContain("searchContacts");
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
     expect(result.contacts[0].id).toBe("search-1");
+    expect(result.contacts[0].interactionCount).toBe(7);
     expect(debugLogs.some((m) => m.includes("daemon-native"))).toBe(true);
   });
 
-  test("contactType filter stays daemon-native and does NOT relay to the gateway", async () => {
+  test("contactType filter stays daemon-native; filter never relayed, only ids-scoped telemetry overlaid", async () => {
     // If contactType were relayed, the gateway would apply it AFTER its limit
-    // and could under-return. We serve it daemon-native instead (SQL filter
-    // before the limit). Assert no relay, local read, and the boundary note.
+    // and could under-return. We resolve it daemon-native instead (SQL filter
+    // BEFORE the limit). The gateway is consulted ONLY for the ids-scoped
+    // telemetry overlay — never to resolve the contactType filter.
+    ipcStub = telemetryHydrationStub("local-1", 3);
+
     const result = await handleListContacts({
       contactType: "assistant",
       limit: "50",
     });
 
-    expect(ipcCalls).toEqual([]);
     expect(localCalls).toEqual(["listContacts"]);
     // contactType + limit are pushed into the SQL-filtered daemon read (the
     // daemon-native listContacts filters contactType BEFORE applying limit).
     expect(listContactsArgs).toEqual([
       { limit: 50, contactType: "assistant" },
     ]);
+    expectOnlyIdsScopedTelemetryHydration(["local-1"]);
     expect(result.contacts[0].id).toBe("local-1");
     expect(result.contacts[0].contactType).toBe("assistant");
+    expect(result.contacts[0].interactionCount).toBe(3);
     expect(debugLogs.some((m) => m.includes("daemon-native"))).toBe(true);
   });
 
   test("contactType filters daemon-native; role is gateway-owned and no longer a local predicate", async () => {
     await handleListContacts({ contactType: "human", role: "guardian" });
 
-    expect(ipcCalls).toEqual([]);
     expect(listContactsArgs).toEqual([{ limit: 50, contactType: "human" }]);
+    // `role` is neither pushed to the local SQL read NOR relayed to the gateway
+    // as a filter — the sole gateway call is the ids-scoped telemetry overlay.
+    expectOnlyIdsScopedTelemetryHydration(["local-1"]);
   });
 });
 
 describe("search_contacts route relay boundary", () => {
-  test("real query stays daemon-native and logs the boundary note", async () => {
+  test("real query stays daemon-native; query stays local while ids-scoped telemetry is overlaid", async () => {
+    // Query resolved locally; boundary note logged. The gateway is only asked
+    // for the ids-scoped telemetry overlay, never to resolve the query.
+    ipcStub = telemetryHydrationStub("search-1", 5);
+
     const contacts = await searchContactsRoute({ query: "alice" });
 
-    expect(ipcCalls).toEqual([]);
     expect(localCalls).toContain("searchContacts");
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
     expect(contacts[0].id).toBe("search-1");
+    expect(
+      (contacts[0] as { interactionCount?: number | null }).interactionCount,
+    ).toBe(5);
     expect(debugLogs.some((m) => m.includes("daemon-native"))).toBe(true);
   });
 
-  test("real channelAddress stays daemon-native", async () => {
+  test("real channelAddress stays daemon-native; filter stays local, only ids-scoped telemetry overlaid", async () => {
+    ipcStub = telemetryHydrationStub("search-1", 5);
+
     const contacts = await searchContactsRoute({ channelAddress: "tg-001" });
 
-    expect(ipcCalls).toEqual([]);
     expect(localCalls).toContain("searchContacts");
+    // channelAddress never reaches the gateway — the sole call carries only ids.
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
     expect(contacts[0].id).toBe("search-1");
   });
 
-  test("real channelType stays daemon-native", async () => {
+  test("real channelType stays daemon-native; filter stays local, only ids-scoped telemetry overlaid", async () => {
+    ipcStub = telemetryHydrationStub("search-1", 5);
+
     const contacts = await searchContactsRoute({ channelType: "telegram" });
 
-    expect(ipcCalls).toEqual([]);
     expect(localCalls).toContain("searchContacts");
+    // channelType never reaches the gateway — the sole call carries only ids.
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
     expect(contacts[0].id).toBe("search-1");
   });
 
+  test("telemetry hydration is FAIL-SOFT: a throwing gateway read still returns locally-resolved contacts with default telemetry (0 counts, null timestamps)", async () => {
+    ipcStub = (method) => {
+      if (method === "contacts_list_rich") {
+        throw new Error("gateway telemetry down");
+      }
+      return undefined;
+    };
+
+    const contacts = await searchContactsRoute({ query: "alice" });
+
+    // The query is resolved locally; the throwing telemetry overlay degrades the
+    // interaction count to 0 (never null, so callers render a real number) and
+    // the timestamps to null, so the search STILL returns its local result.
+    expect(localCalls).toContain("searchContacts");
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
+    expect(contacts[0].id).toBe("search-1");
+    expect(
+      (contacts[0] as { interactionCount?: number | null }).interactionCount,
+    ).toBe(0);
+    expect(
+      (contacts[0] as { lastInteraction?: number | null }).lastInteraction,
+    ).toBeNull();
+  });
+
+  test("channel telemetry overlays via (type,address) fallback when the local channel id differs from the gateway id", async () => {
+    // Legacy/unaligned channel: the daemon-native read resolves a channel whose
+    // LOCAL uuid differs from the GATEWAY uuid for the same (type, address). The
+    // id lookup misses, so telemetry must land via the (type, lower(address))
+    // fallback rather than fail-softing to null.
+    searchContactsResult = [
+      {
+        id: "search-1",
+        displayName: "Search Contact",
+        role: "contact",
+        contactType: "human",
+        interactionCount: 0,
+        channels: [
+          {
+            id: "local-ch-uuid",
+            contactId: "search-1",
+            type: "telegram",
+            // Mixed-case to also pin the NOCASE (lowercase) address match.
+            address: "TG-001",
+            isPrimary: true,
+            externalUserId: null,
+            status: "active",
+            policy: "allow",
+            verifiedAt: null,
+            verifiedVia: null,
+            lastSeenAt: null,
+            interactionCount: 0,
+            lastInteraction: null,
+            revokedReason: null,
+            blockedReason: null,
+          },
+        ],
+      },
+    ];
+    ipcStub = (method) => {
+      if (method === "contacts_list_rich") {
+        return {
+          ok: true,
+          contacts: [
+            gatewayContact({
+              id: "search-1",
+              interactionCount: 9,
+              channels: [
+                {
+                  // DIFFERENT uuid than the local channel; same (type, address).
+                  id: "gateway-ch-uuid",
+                  contactId: "search-1",
+                  type: "telegram",
+                  address: "tg-001",
+                  isPrimary: true,
+                  externalUserId: null,
+                  status: "active",
+                  policy: "allow",
+                  verifiedAt: null,
+                  verifiedVia: null,
+                  lastSeenAt: 555,
+                  interactionCount: 9,
+                  lastInteraction: 777,
+                  revokedReason: null,
+                  blockedReason: null,
+                },
+              ],
+            }),
+          ],
+        };
+      }
+      return undefined;
+    };
+
+    const contacts = await searchContactsRoute({ query: "alice" });
+
+    expect(localCalls).toContain("searchContacts");
+    expectOnlyIdsScopedTelemetryHydration(["search-1"]);
+    const ch = (
+      contacts[0] as unknown as {
+        channels: {
+          lastSeenAt: number | null;
+          interactionCount: number | null;
+          lastInteraction: number | null;
+        }[];
+      }
+    ).channels[0];
+    expect(ch.interactionCount).toBe(9);
+    expect(ch.lastSeenAt).toBe(555);
+    expect(ch.lastInteraction).toBe(777);
+  });
+
   test("empty/whitespace query with no filters relays through the gateway", async () => {
     ipcStub = (method) => {
       if (method === "contacts_list_rich") {

package/src/__tests__/contacts-tools.test.ts

@@ -33,6 +33,11 @@ mock.module("../config/env.js", () => ({
   getGatewayPort: () => 0,
 }));
 
+// Per-test override for the search_contacts IPC result. When set, cliIpcCall
+// returns it verbatim instead of dispatching to the store — used to inject
+// gateway-shaped payloads (e.g. a null interactionCount telemetry fail-soft).
+let searchContactsOverride: unknown[] | null = null;
+
 // Skill tools call cliIpcCall instead of the gateway HTTP.
 // Mock the IPC client to dispatch contact reads/merge to the real store
 // (backed by the test DB) without needing a running IPC server.
@@ -42,6 +47,9 @@ mock.module("../ipc/cli-client.js", () => ({
     const body = (params?.body ?? params ?? {}) as Record<string, unknown>;
     const pathParams = (params?.pathParams ?? {}) as Record<string, string>;
     if (method === "search_contacts") {
+      if (searchContactsOverride !== null) {
+        return { ok: true, result: searchContactsOverride };
+      }
       return { ok: true, result: store.searchContacts(body) };
     }
     if (method === "getContact") {
@@ -172,7 +180,40 @@ function upsertFixture(params: {
 // ── contact_search ──────────────────────────────────────────────────
 
 describe("contact_search tool", () => {
-  beforeEach(clearContacts);
+  beforeEach(() => {
+    searchContactsOverride = null;
+    clearContacts();
+  });
+
+  test("renders a null interactionCount without a false '>0' guard or a 'null' print", async () => {
+    // Defensive: the daemon-native path now defaults interactionCount to 0, but
+    // the ContactRead contract still permits null, so the tool must stay robust
+    // to a null — neither printing "Interactions: null" nor treating null as > 0
+    // (which would emit a bogus interactions line).
+    searchContactsOverride = [
+      {
+        id: "c-blank-telemetry",
+        displayName: "Telemetry Absent",
+        role: "contact",
+        notes: null,
+        contactType: "human",
+        lastInteraction: null,
+        interactionCount: null,
+        createdAt: 1699000000,
+        updatedAt: 1700000000,
+        channels: [],
+      },
+    ];
+
+    const result = await executeContactSearch({ query: "Telemetry" }, ctx);
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Telemetry Absent");
+    // The interactions line is suppressed entirely (guard is false), so neither
+    // the label nor a stringified "null" leaks into the summary.
+    expect(result.content).not.toContain("Interactions");
+    expect(result.content).not.toContain("null");
+  });
 
   test("searches by display name", async () => {
     upsertFixture({ display_name: "Alice Smith" });

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

@@ -30,6 +30,22 @@ function resetContactTables(): void {
   sqlite.run("DELETE FROM contacts");
 }
 
+function channelOwnerById(channelId: string): string | undefined {
+  const row = getSqlite()
+    .query("SELECT contact_id AS contactId FROM contact_channels WHERE id = ?")
+    .get(channelId) as { contactId?: string } | undefined;
+  return row?.contactId;
+}
+
+function channelCount(type: string, address: string): number {
+  const row = getSqlite()
+    .query(
+      "SELECT COUNT(*) AS n FROM contact_channels WHERE type = ? AND address = ? COLLATE NOCASE",
+    )
+    .get(type, address) as { n: number };
+  return row.n;
+}
+
 function workspaceDir(): string {
   const dir = process.env.VELLUM_WORKSPACE_DIR;
   if (!dir) {
@@ -75,3 +91,168 @@ describe("guardian persona seeding and trust-cache invariants", () => {
     expect(existsSync(personaPath)).toBe(false);
   });
 });
+
+// The identity mirror must faithfully replicate gateway-owned identity rows:
+// same channel id, NULL user_file for mirror-created stubs, and a refreshable
+// display name on inbound seeds. It must NOT impose the primitive's
+// guardian-curation semantics (generated user_file, preserved name).
+describe("identity-mirror faithful-replica semantics", () => {
+  beforeEach(() => {
+    resetContactTables();
+  });
+
+  test("Finding A: userFileOnCreate:null leaves a mirror-created contact's user_file NULL", () => {
+    const result = upsertContactChannel({
+      sourceChannel: "telegram",
+      externalUserId: "SeedA",
+      externalChatId: "chat-seed-a",
+      displayName: "Seed A",
+      contactId: "co-seed-a",
+      channelId: "gw-ch-a",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+    });
+
+    expect(result).not.toBeNull();
+    // Mirror stub carries no persona-file pointer, so orphan-GC treats it as
+    // unauthored and can reclaim it after a guardian channel claim.
+    expect(result?.contact.userFile).toBeNull();
+  });
+
+  test("Finding B: an explicit (gateway-minted) channel id is reused verbatim", () => {
+    const result = upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UBEE",
+      externalChatId: "DBEE",
+      displayName: "Bee",
+      contactId: "co-bee",
+      channelId: "gw-channel-777",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+    });
+
+    expect(result?.channel.id).toBe("gw-channel-777");
+  });
+
+  test("Finding C: refreshDisplayName refreshes the mirror name on a follow-up seed", () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UCEE",
+      externalChatId: "DCEE",
+      displayName: "Old Name",
+      contactId: "co-cee",
+      channelId: "gw-ch-cee",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+    });
+
+    const refreshed = upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UCEE",
+      externalChatId: "DCEE",
+      displayName: "New Name",
+      contactId: "co-cee",
+      refreshDisplayName: true,
+    });
+
+    expect(refreshed?.contact.displayName).toBe("New Name");
+  });
+
+  test("Finding C: the invite-binding path (no refresh flag) preserves a curated name", () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UDEE",
+      externalChatId: "DDEE",
+      displayName: "Curated Name",
+      contactId: "co-dee",
+      channelId: "gw-ch-dee",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+    });
+
+    // Invite binding re-binds the channel with the raw platform name; the
+    // curated contact name must NOT be clobbered.
+    const bound = upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UDEE",
+      externalChatId: "DDEE",
+      displayName: "Raw Platform Name",
+      contactId: "co-dee",
+    });
+
+    expect(bound?.contact.displayName).toBe("Curated Name");
+  });
+});
+
+// The inbound-seed mirror must match the gateway insert's onConflictDoNothing:
+// when a first-seen race lands a second contact for the same (type,address), the
+// mirror must NOT reparent the channel to the second contact (that would leave
+// the mirror pointing at contact #2 while the gateway ACL row keeps contact #1).
+// Only the invite-binding path may reparent.
+describe("mirror channel-reparenting race semantics", () => {
+  beforeEach(() => {
+    resetContactTables();
+  });
+
+  test("SEED path (reassignConflictingChannels:false) does NOT reparent a conflicting channel", () => {
+    // Contact #1 wins the create race — gateway keeps this via onConflictDoNothing.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "URACE",
+      externalChatId: "DRACE",
+      displayName: "First",
+      contactId: "co-race-1",
+      channelId: "gw-ch-race-1",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+
+    // Contact #2: a second first-seen seed event with a fresh contact id for the
+    // SAME (type,address). Seed semantics: must leave the channel with contact #1.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "URACE",
+      externalChatId: "DRACE",
+      displayName: "Second",
+      contactId: "co-race-2",
+      channelId: "gw-ch-race-2",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+
+    // Original channel stays under contact #1; no duplicate channel was created.
+    expect(channelOwnerById("gw-ch-race-1")).toBe("co-race-1");
+    expect(channelOwnerById("gw-ch-race-2")).toBeUndefined();
+    expect(channelCount("slack", "URACE")).toBe(1);
+  });
+
+  test("INVITE-binding path (reassignConflictingChannels:true) DOES reparent", () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UBIND",
+      externalChatId: "DBIND",
+      displayName: "Seed Owner",
+      contactId: "co-bind-seed",
+      channelId: "gw-ch-bind",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+
+    // Invite binds the redeemer's existing channel to the invite's target
+    // contact — the legitimate reparent.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UBIND",
+      externalChatId: "DBIND",
+      displayName: "Target Contact",
+      contactId: "co-bind-target",
+      reassignConflictingChannels: true,
+    });
+
+    expect(channelOwnerById("gw-ch-bind")).toBe("co-bind-target");
+    expect(channelCount("slack", "UBIND")).toBe(1);
+  });
+});