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

package/src/runtime/local-actor-identity.ts

@@ -13,7 +13,11 @@
 
 import type { ChannelId } from "../channels/types.js";
 import { isHttpAuthDisabled } from "../config/env.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+  peekCachedGuardianDelivery,
+} from "../contacts/guardian-delivery-reader.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { getLogger } from "../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
@@ -45,14 +49,57 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
 }
 
 /**
- * Look up the local vellum guardian's principalId from the contacts table.
+ * Resolve the local vellum guardian's principalId from the gateway.
+ *
+ * The gateway owns guardian binding; this reads it through the cached
+ * `getGuardianDelivery` reader (PR-3 TTL + single-flight) so hot paths don't
+ * storm the IPC.
  *
  * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
- * install before bootstrap). Callers should treat that case as
- * "not yet available" and either fall back or proceed without a principalId.
+ * install before bootstrap, or the gateway is unreachable). Callers should
+ * treat that case as "not yet available" and proceed without a principalId.
+ */
+export async function findLocalGuardianPrincipalId(): Promise<
+  string | undefined
+> {
+  const list = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!list) return undefined;
+  return guardianForChannel(list, "vellum")?.principalId ?? undefined;
+}
+
+/**
+ * Eagerly warm the gateway guardian-delivery cache for the vellum channel.
+ *
+ * The SSE eager-subscribe path resolves the actor principal synchronously via
+ * {@link findLocalGuardianPrincipalIdFromStore}, which reads only the IO-free
+ * cache snapshot. On a cold cache (auth-disabled / local startup, before any
+ * async `getGuardianDelivery` has run) it returns undefined, so the FIRST SSE
+ * registration would carry no `actorPrincipalId` and host-proxy same-user
+ * targeting would regress until a later reconnect warms the cache.
+ *
+ * Called during daemon startup (after the gateway IPC is reachable) so the
+ * cache is populated before clients register. Best-effort: a cold gateway
+ * leaves the cache empty (failures aren't cached), and the async hot paths
+ * warm it on their next read.
  */
-export function findLocalGuardianPrincipalId(): string | undefined {
-  return findGuardianForChannel("vellum")?.contact.principalId ?? undefined;
+export async function warmLocalGuardianPrincipalCache(): Promise<void> {
+  await findLocalGuardianPrincipalId();
+}
+
+/**
+ * Synchronous read of the vellum guardian's principalId for paths that cannot
+ * await {@link findLocalGuardianPrincipalId} — namely the SSE eager-subscribe
+ * path (`events-routes`), which registers before the stream is created.
+ *
+ * Reads the same gateway-owned binding as the async path via a sync, IO-free
+ * snapshot of the guardian-delivery cache (kept fresh by the async hot paths
+ * and event-driven invalidation), so SSE registers the SAME principal the
+ * send/result routes resolve.
+ */
+export function findLocalGuardianPrincipalIdFromStore(): string | undefined {
+  const cached = peekCachedGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!cached) return undefined;
+  return guardianForChannel(cached, "vellum")?.principalId ?? undefined;
 }
 
 /**
@@ -76,12 +123,35 @@ export function findLocalGuardianPrincipalId(): string | undefined {
  * yet (e.g. fresh install before bootstrap); callers must treat this the
  * same as a missing principal.
  */
-export function resolveActorPrincipalIdForLocalGuardian(
+export async function resolveActorPrincipalIdForLocalGuardian(
+  rawHeader: string | undefined,
+): Promise<string | undefined> {
+  if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) return rawHeader;
+
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
+  if (guardianPrincipalId) return guardianPrincipalId;
+
+  log.warn(
+    "dev-bypass actor principal received but no vellum guardian binding found; returning undefined",
+  );
+  return undefined;
+}
+
+/**
+ * Synchronous variant of {@link resolveActorPrincipalIdForLocalGuardian} for
+ * the SSE eager-subscribe path, which registers before the response stream is
+ * created and cannot await. Resolves the guardian from the IO-free gateway
+ * cache snapshot first (same source the async path reads), falling back to the
+ * local store when the cache is cold — so SSE registers the SAME principal the
+ * send/result routes resolve and host-proxy targeting matches the same-user
+ * client even when the local contact row is stale.
+ */
+export function resolveActorPrincipalIdForLocalGuardianSync(
   rawHeader: string | undefined,
 ): string | undefined {
   if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) return rawHeader;
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = findLocalGuardianPrincipalIdFromStore();
   if (guardianPrincipalId) return guardianPrincipalId;
 
   log.warn(
@@ -102,12 +172,12 @@ export function resolveActorPrincipalIdForLocalGuardian(
  * bootstrap), falls back to a minimal guardian context so the local
  * user is not incorrectly denied.
  */
-export function resolveLocalTrustContext(
+export async function resolveLocalTrustContext(
   sourceChannel: ChannelId = "vellum",
-): TrustContext {
+): Promise<TrustContext> {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
   if (guardianPrincipalId) {
     const trustCtx = resolveTrustContext({
       assistantId,
@@ -139,10 +209,12 @@ export function resolveLocalTrustContext(
  * downstream code to resolve guardian context using the same
  * `authContext.actorPrincipalId` path as HTTP sessions.
  */
-export function resolveLocalAuthContext(conversationId: string): AuthContext {
+export async function resolveLocalAuthContext(
+  conversationId: string,
+): Promise<AuthContext> {
   const authContext = buildLocalAuthContext(conversationId);
 
-  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId();
   if (guardianPrincipalId) {
     return { ...authContext, actorPrincipalId: guardianPrincipalId };
   }

package/src/runtime/local-principal-trust.ts

@@ -0,0 +1,52 @@
+/**
+ * Derives a local principal's {@link TrustContext} from the gateway guardian
+ * binding. Fails closed to unknown on a missing or null read.
+ */
+
+import type { ChannelId } from "../channels/types.js";
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
+import type { TrustContext } from "../daemon/trust-context.js";
+import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+
+export interface ResolveLocalPrincipalTrustInput {
+  actorPrincipalId: string;
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+}
+
+/** Guardian match → guardian ctx; miss or null read → unknown (fail closed). */
+export async function resolveLocalPrincipalTrustContext(
+  input: ResolveLocalPrincipalTrustInput,
+): Promise<TrustContext> {
+  const unknownContext: TrustContext = {
+    sourceChannel: input.sourceChannel,
+    trustClass: "unknown",
+    requesterExternalUserId: input.actorPrincipalId,
+    requesterChatId: input.conversationExternalId,
+  };
+
+  // Fail closed: a null read means the gateway is unreachable — never grant
+  // guardian on a miss.
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!guardians) return unknownContext;
+
+  const guardian = guardians.find(
+    (g) => g.principalId === input.actorPrincipalId,
+  );
+  if (!guardian) return unknownContext;
+
+  return {
+    sourceChannel: input.sourceChannel,
+    trustClass: "guardian",
+    guardianChatId: guardian.externalChatId ?? input.conversationExternalId,
+    guardianExternalUserId:
+      canonicalizeInboundIdentity(input.sourceChannel, guardian.address) ??
+      undefined,
+    guardianPrincipalId: guardian.principalId ?? undefined,
+    // Mirror toTrustContext: with no username the requester identifier is the
+    // canonical sender id, which for a vellum principal is actorPrincipalId.
+    requesterIdentifier: input.actorPrincipalId,
+    requesterExternalUserId: input.actorPrincipalId,
+    requesterChatId: input.conversationExternalId,
+  };
+}

package/src/runtime/pending-interactions.ts

@@ -229,6 +229,15 @@ export function getByConversation(
  * /v1/host-browser-result, /v1/host-app-control-result, or
  * /v1/host-transfer-result after completing the operation, get a 404, and the
  * proxy timer would fire with a spurious timeout error.
+ *
+ * `question` interactions are also skipped: a new message supersedes an open
+ * ask_question by steering to it (see the enqueue path in
+ * conversation-routes.ts), which aborts the parked turn and settles the
+ * question via its abort signal. Clearing the entry here instead would drop it
+ * without settling the prompt's Promise (questions carry no `rpcResolve`
+ * fallback like secrets do) and would strip the steer of the entry it needs to
+ * fire — which can co-occur with a confirmation, since one model response can
+ * open both tools concurrently.
  */
 export function removeByConversation(
   conversationId: string,
@@ -244,7 +253,8 @@ export function removeByConversation(
       interaction.kind !== "host_browser" &&
       interaction.kind !== "host_app_control" &&
       interaction.kind !== "host_transfer" &&
-      interaction.kind !== "acp_confirmation"
+      interaction.kind !== "acp_confirmation" &&
+      interaction.kind !== "question"
     ) {
       // resolve() clears the stored timer and detaches abort listeners.
       resolve(requestId, state);

package/src/runtime/routes/__tests__/channel-verification-revoke.test.ts

@@ -10,6 +10,7 @@
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import type { GuardianDelivery } from "@vellumai/gateway-client";
 import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
 
 type IpcCall = { method: string; params?: Record<string, unknown> };
@@ -73,8 +74,16 @@ mock.module("../../channel-verification-service.js", () => ({
   getGuardianBinding: mock(() => guardianBinding),
 }));
 
-// Contact-store lookup that resolves the guardian's channel to downgrade.
-let contactChannel: { id: string; status: string } | null = null;
+// Contact-store lookup that resolves the guardian's channel to downgrade. The
+// channel carries the type/address/externalChatId the gateway delivery is
+// matched against (see deliveryForChannel).
+let contactChannel: {
+  id: string;
+  status: string;
+  type: string;
+  address: string;
+  externalChatId: string;
+} | null = null;
 const actualContactStore = await import("../../../contacts/contact-store.js");
 mock.module("../../../contacts/contact-store.js", () => ({
   ...actualContactStore,
@@ -83,6 +92,20 @@ mock.module("../../../contacts/contact-store.js", () => ({
   ),
 }));
 
+// Gateway delivery (ACL source of truth). The revoke gate relays only when the
+// matching delivery is live (active/pending/unverified); already-revoked or a
+// missing delivery short-circuits the relay.
+let guardianDeliveries: GuardianDelivery[] | null = null;
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: mock(async (input?: { channelTypes?: string[] }) => {
+    if (guardianDeliveries == null) return null;
+    if (!input?.channelTypes) return guardianDeliveries;
+    return guardianDeliveries.filter((g) =>
+      input.channelTypes!.includes(g.channelType),
+    );
+  }),
+}));
+
 // Guard: the contact-channel ACL write moves to the gateway relay and must
 // never run locally. The assistant-owned guardian-binding teardown
 // (revokeGuardianBinding) still runs locally — assert it is invoked.
@@ -122,7 +145,24 @@ describe("verification revoke relay", () => {
       guardianExternalUserId: "guardian-user",
       guardianDeliveryChatId: "chat-1",
     };
-    contactChannel = { id: "ch1", status: "active" };
+    contactChannel = {
+      id: "ch1",
+      status: "active",
+      type: "telegram",
+      address: "guardian-user",
+      externalChatId: "chat-1",
+    };
+    // Gateway delivery is live by default, so the revoke relay fires.
+    guardianDeliveries = [
+      {
+        channelType: "telegram",
+        contactId: "c1",
+        address: "guardian-user",
+        externalChatId: "chat-1",
+        status: "active",
+        verifiedAt: 1700000000,
+      },
+    ];
     ipcCallPersistentMock.mockClear();
     cancelOutboundMock.mockClear();
     revokePendingSessionsMock.mockClear();
@@ -263,8 +303,19 @@ describe("verification revoke relay", () => {
     expect(result.bound).toBe(false);
   });
 
-  test("skips the relay when the resolved channel is already revoked", async () => {
-    contactChannel = { id: "ch1", status: "revoked" };
+  test("skips the relay when the gateway delivery is already revoked", async () => {
+    // The gateway (source of truth) already shows the channel revoked, so the
+    // redundant relay is skipped even though session/binding teardown runs.
+    guardianDeliveries = [
+      {
+        channelType: "telegram",
+        contactId: "c1",
+        address: "guardian-user",
+        externalChatId: "chat-1",
+        status: "revoked",
+        verifiedAt: 1700000000,
+      },
+    ];
 
     await revokeHandler({ body: { channel: "telegram" } });
 

package/src/runtime/routes/__tests__/channel-verification-routes.test.ts

@@ -24,7 +24,7 @@ mock.module("../../../daemon/handlers/config-channels.js", () => ({
     verifyTrustedContactCalls.push([contactChannelId, assistantId]);
     return verifyTrustedContactImpl(contactChannelId, assistantId);
   },
-  createInboundChallenge: () => ({ success: true }),
+  createInboundChallenge: async () => ({ success: true }),
   getVerificationStatus: () => ({ success: true }),
   revokeVerificationForChannel: () => ({ success: true }),
 }));

package/src/runtime/routes/__tests__/contact-routes.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Unit tests for the contacts read API.
+ *
+ * `handleListContacts`, `handleGetContact`, and the `search_contacts`
+ * no-filter case relay to the gateway rich read (`contacts_list_rich` /
+ * `contacts_get_rich`), which is the source of truth for the ACL fields
+ * (`role`/`status`/`policy`/`verifiedAt`/`interactionCount`/`lastInteraction`).
+ * These tests assert the serialized response shape is gateway-sourced and
+ * unchanged for the web client, that no read path falls back to the assistant
+ * DB, and that a relay failure fails closed (surfaces an error) instead of
+ * reading local ACL.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
+import { z } from "zod";
+
+let ipcCalls: { method: string; params?: Record<string, unknown> }[] = [];
+let ipcResult: unknown = {};
+let ipcError: Error | undefined;
+
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcError) throw ipcError;
+    return ipcResult;
+  },
+);
+
+const actualGatewayClient = await import("../../../ipc/gateway-client.js");
+
+mock.module("../../../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+// Guard: fail loudly if any read path falls back to the assistant DB for ACL
+// fields. The relay read paths must source role/status/stats from the gateway.
+const actualContactStore = await import("../../../contacts/contact-store.js");
+
+const contactStoreReadGuard = mock(() => {
+  throw new Error(
+    "assistant contact-store read must not happen on the gateway relay path",
+  );
+});
+
+// Filtered/native reads (search) legitimately go to the assistant DB. Drive
+// them deterministically so the daemon-native response shape can be asserted.
+let searchContactsResult: unknown[] = [];
+const searchContactsMock = mock(() => searchContactsResult);
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...actualContactStore,
+  getContact: contactStoreReadGuard,
+  listContacts: contactStoreReadGuard,
+  getAssistantContactMetadata: contactStoreReadGuard,
+  searchContacts: searchContactsMock,
+}));
+
+const { handleListContacts, handleGetContact, ROUTES } =
+  await import("../contact-routes.js");
+
+// Daemon-native contact: INFO is hydrated locally; channel-level ACL fields
+// (status/policy/verification) are gateway-owned and absent on native reads.
+// Contact-level `role` is stored locally (NOT NULL) and always returned.
+const nativeContact = {
+  id: "ct_2",
+  displayName: "Bob",
+  notes: null,
+  role: "contact",
+  contactType: "human",
+  lastInteraction: 4200,
+  interactionCount: 4,
+  createdAt: 1000,
+  updatedAt: 1500,
+  userFile: "bob.md",
+  channels: [
+    {
+      id: "ch_2",
+      contactId: "ct_2",
+      type: "phone",
+      address: "+15550200",
+      isPrimary: true,
+      externalChatId: null,
+      inviteId: null,
+      lastSeenAt: 4100,
+      interactionCount: 4,
+      lastInteraction: 4200,
+      updatedAt: 1500,
+      createdAt: 1000,
+    },
+  ],
+};
+
+const gatewayChannel = {
+  id: "ch_1",
+  contactId: "ct_1",
+  type: "sms",
+  address: "+15550100",
+  isPrimary: true,
+  externalUserId: null,
+  status: "active",
+  policy: "allow",
+  verifiedAt: 1700,
+  verifiedVia: "invite",
+  lastSeenAt: 1800,
+  interactionCount: 7,
+  lastInteraction: 1900,
+  revokedReason: null,
+  blockedReason: null,
+};
+
+const gatewayContact = {
+  id: "ct_1",
+  displayName: "Alice",
+  role: "guardian",
+  notes: "a note",
+  contactType: "human",
+  lastInteraction: 1900,
+  interactionCount: 7,
+  createdAt: 1000,
+  updatedAt: 1500,
+  channels: [gatewayChannel],
+};
+
+describe("contacts read API relays from the gateway", () => {
+  beforeEach(() => {
+    ipcCalls = [];
+    ipcResult = {};
+    ipcError = undefined;
+    ipcCallPersistentMock.mockClear();
+    contactStoreReadGuard.mockClear();
+    searchContactsResult = [];
+    searchContactsMock.mockClear();
+  });
+
+  test("list relays to contacts_list_rich and serializes the gateway ACL fields", async () => {
+    ipcResult = { ok: true, contacts: [gatewayContact] };
+
+    const result = await handleListContacts({ limit: "50" });
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_list_rich", params: { limit: 50 } },
+    ]);
+    expect(result.ok).toBe(true);
+    expect(result.contacts).toHaveLength(1);
+
+    const [contact] = result.contacts;
+    // ACL fields are gateway-sourced and reach the web client unchanged.
+    expect((contact as { role?: string }).role).toBe("guardian");
+    expect(contact.interactionCount).toBe(7);
+    expect(contact.lastInteraction).toBe(1900);
+    const channel = contact.channels[0] as Record<string, unknown>;
+    expect(channel.status).toBe("active");
+    expect(channel.policy).toBe("allow");
+    expect(channel.verifiedAt).toBe(1700);
+    expect(channel.interactionCount).toBe(7);
+    expect(channel.lastInteraction).toBe(1900);
+    // Channel compat echoes address into externalUserId for older clients.
+    expect(channel.externalUserId).toBe("+15550100");
+
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("list forwards the role filter to the gateway", async () => {
+    ipcResult = { ok: true, contacts: [] };
+
+    await handleListContacts({ limit: "10", role: "guardian" });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: "contacts_list_rich",
+        params: { limit: 10, role: "guardian" },
+      },
+    ]);
+  });
+
+  test("list fails closed when the gateway relay is unavailable", async () => {
+    ipcError = new IpcCallError("gateway down", {
+      statusCode: 503,
+      errorCode: "UNAVAILABLE",
+    });
+
+    await expect(handleListContacts({ limit: "50" })).rejects.toMatchObject({
+      message: "gateway down",
+      statusCode: 503,
+    });
+    // No assistant-DB fallback read.
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get relays to contacts_get_rich and serializes the gateway ACL fields", async () => {
+    ipcResult = { ok: true, contact: gatewayContact };
+
+    const result = await handleGetContact("ct_1");
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_get_rich", params: { contactId: "ct_1" } },
+    ]);
+    expect(result.ok).toBe(true);
+    expect(result.contact.role).toBe("guardian");
+    expect(result.contact.interactionCount).toBe(7);
+    const channel = result.contact.channels[0] as Record<string, unknown>;
+    expect(channel.status).toBe("active");
+    expect(channel.externalUserId).toBe("+15550100");
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get surfaces a clean gateway not-found as a 404", async () => {
+    ipcResult = { ok: true };
+
+    await expect(handleGetContact("missing")).rejects.toMatchObject({
+      statusCode: 404,
+    });
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get fails closed on a relay failure (no assistant-DB fallback)", async () => {
+    ipcError = new IpcCallError("gateway down", {
+      statusCode: 503,
+      errorCode: "UNAVAILABLE",
+    });
+
+    await expect(handleGetContact("ct_1")).rejects.toMatchObject({
+      message: "gateway down",
+      statusCode: 503,
+    });
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("search no-filter relays to the gateway list read", async () => {
+    ipcResult = { ok: true, contacts: [gatewayContact] };
+
+    const route = ROUTES.find((r) => r.operationId === "search_contacts");
+    expect(route).toBeDefined();
+
+    const contacts = (await route!.handler({ body: {} })) as Array<{
+      role: string;
+      interactionCount: number;
+      channels: { status: string }[];
+    }>;
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_list_rich", params: { limit: 50 } },
+    ]);
+    expect(contacts[0].role).toBe("guardian");
+    expect(contacts[0].interactionCount).toBe(7);
+    expect(contacts[0].channels[0].status).toBe("active");
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+});
+
+describe("filtered/native contact reads stay daemon-native", () => {
+  const listRoute = ROUTES.find((r) => r.operationId === "listContacts")!;
+  const listResponseSchema = listRoute.responseBody as z.ZodTypeAny;
+  const searchRoute = ROUTES.find((r) => r.operationId === "search_contacts")!;
+  const searchResponseSchema = searchRoute.responseBody as z.ZodTypeAny;
+
+  beforeEach(() => {
+    ipcCalls = [];
+    ipcResult = {};
+    ipcError = undefined;
+    ipcCallPersistentMock.mockClear();
+    contactStoreReadGuard.mockClear();
+    searchContactsResult = [];
+    searchContactsMock.mockClear();
+  });
+
+  test("query-filtered list serves daemon-native INFO and validates against the response schema", async () => {
+    searchContactsResult = [nativeContact];
+
+    const result = await handleListContacts({ query: "Bob", limit: "10" });
+
+    // No gateway relay for a true search.
+    expect(ipcCalls).toEqual([]);
+    expect(searchContactsMock).toHaveBeenCalled();
+
+    const [contact] = result.contacts;
+    // INFO telemetry is present (re-hydrated locally, not dropped).
+    expect(contact.interactionCount).toBe(4);
+    expect(contact.lastInteraction).toBe(4200);
+    const channel = contact.channels[0] as Record<string, unknown>;
+    expect(channel.interactionCount).toBe(4);
+    expect(channel.lastSeenAt).toBe(4100);
+    expect(channel.externalUserId).toBe("+15550200");
+    // Contact-level `role` is locally stored (NOT NULL) and always present.
+    expect((contact as { role: string }).role).toBe("contact");
+    // Channel-level ACL fields (status/policy) are gateway-owned and absent.
+    expect("status" in channel).toBe(false);
+    expect(() => listResponseSchema.parse(result)).not.toThrow();
+  });
+
+  test("POST search with a filter validates against the response schema", async () => {
+    searchContactsResult = [nativeContact];
+
+    const contacts = (await searchRoute.handler({
+      body: { query: "Bob" },
+    })) as unknown[];
+
+    expect(ipcCalls).toEqual([]);
+    expect(searchContactsMock).toHaveBeenCalled();
+    expect(() => searchResponseSchema.parse(contacts)).not.toThrow();
+  });
+});