@vellumai/assistant 0.10.3-staging.2 → 0.10.4-staging.1

package/src/runtime/assistant-stream-state.ts

@@ -31,20 +31,18 @@
  * sized generously enough that a typical refresh round-trip (~1-3s)
  * is well within window.
  *
- * Persisted-seq map: alongside the live counter and ring, this module
- * tracks, per conversation, the `seq` of the last event whose content is
- * durably committed to the message rows (`persistedSeqByConversation`).
- * The `/messages` snapshot returns this value so a client can align the
- * snapshot with the stream: "these rows reflect all of this
- * conversation's events through `seq = S`." It is recorded at each
- * persistence flush (assistant rows persist incrementally, debounced, so
- * the snapshot can lag the live counter) -- never the live counter
- * itself, which would over-claim events that have streamed but not yet
- * been written. The map is in-memory and clears on restart; because the
- * counter resumes above the persisted reservation, a value recorded by
- * a previous process could only ever be lower than any seq the new
- * process assigns -- never ambiguous against it. The map is LRU-bounded; an
- * evicted conversation reports no seq and the client cold-starts.
+ * Persisted seq: alongside the live counter and ring, the `seq` of the last
+ * event whose content is durably committed to a conversation's message rows
+ * is stored on the `conversations.seq` column (see `conversation-crud`). The
+ * `/messages` snapshot returns it so a client can align the snapshot with the
+ * stream: "these rows reflect all of this conversation's events through
+ * `seq = S`." It is written at each persistence flush (assistant rows persist
+ * incrementally, debounced, so the snapshot can lag the live counter) -- never
+ * the live counter itself, which would over-claim events that have streamed
+ * but not yet been written. Because it lives in the database it survives a
+ * restart; and because the counter resumes above the persisted reservation, a
+ * value written by a previous process could only ever be lower than any seq
+ * the new process assigns -- never ambiguous against it.
  */
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -66,16 +64,6 @@ const RING_COUNT_LIMIT = SSE_REPLAY_RING_COUNT_LIMIT;
 const RING_SIZE_LIMIT_BYTES = 256 * 1024;
 const RING_AGE_LIMIT_MS = SSE_REPLAY_RING_AGE_LIMIT_MS;
 
-/**
- * Cap on how many conversations retain a persisted-seq entry. Unlike the
- * ring (which the live stream needs only briefly), the persisted-seq map
- * grows with the number of conversations that have ever streamed in this
- * process. Bound it LRU so it can't grow without limit; an evicted
- * conversation simply reports no seq on its next `/messages` and the
- * client cold-starts, which is harmless.
- */
-const PERSISTED_SEQ_CONVERSATION_LIMIT = 1024;
-
 /**
  * How many seq values are reserved per persisted write. The counter can
  * hand out seqs up to the persisted ceiling without touching disk, so
@@ -141,13 +129,6 @@ interface AssistantStreamState {
   firstStampedSeq: number;
   ring: RingEntry[];
   totalSizeBytes: number;
-  /**
-   * Per-conversation `seq` of the last event durably committed to the
-   * message rows. Insertion order is maintained as an LRU recency list:
-   * the oldest key is evicted first once the map exceeds
-   * {@link PERSISTED_SEQ_CONVERSATION_LIMIT}.
-   */
-  persistedSeqByConversation: Map<string, number>;
 }
 
 // ── State ────────────────────────────────────────────────────────────
@@ -159,7 +140,6 @@ const state: AssistantStreamState = {
   firstStampedSeq: 0,
   ring: [],
   totalSizeBytes: 0,
-  persistedSeqByConversation: new Map(),
 };
 
 // ── Public API ───────────────────────────────────────────────────────
@@ -270,46 +250,6 @@ export function getCurrentSeq(): number {
   return state.nextSeq - 1;
 }
 
-/**
- * Record that conversation `conversationId` has durably persisted all of
- * its events through `seq`. Called at each persistence flush with the
- * `seq` of the last event whose content the write committed.
- *
- * Monotonic: a lower `seq` never regresses a higher one (out-of-order
- * async commits are clamped). LRU-bounded by
- * {@link PERSISTED_SEQ_CONVERSATION_LIMIT}: re-recording refreshes
- * recency, and the oldest conversation is evicted once the cap is
- * exceeded. Non-positive or non-finite `seq` values are ignored.
- */
-export function recordPersistedSeq(conversationId: string, seq: number): void {
-  if (!Number.isFinite(seq) || seq <= 0) return;
-
-  const map = state.persistedSeqByConversation;
-  const prev = map.get(conversationId);
-  if (prev !== undefined) {
-    // Re-insert to move this key to the most-recently-used end.
-    map.delete(conversationId);
-    map.set(conversationId, Math.max(prev, seq));
-    return;
-  }
-
-  map.set(conversationId, seq);
-  if (map.size > PERSISTED_SEQ_CONVERSATION_LIMIT) {
-    const oldestKey = map.keys().next().value;
-    if (oldestKey !== undefined) map.delete(oldestKey);
-  }
-}
-
-/**
- * Highest `seq` durably persisted for `conversationId`, or `null` when
- * none has been recorded in this process (cold conversation, or evicted
- * from the LRU map). Returned by `/messages` so a client can align the
- * snapshot with the live stream.
- */
-export function getPersistedSeq(conversationId: string): number | null {
-  return state.persistedSeqByConversation.get(conversationId) ?? null;
-}
-
 /**
  * Reset all stream state. Test-only.
  */
@@ -323,7 +263,6 @@ export function _resetStreamStateForTesting(): void {
   state.firstStampedSeq = 0;
   state.ring = [];
   state.totalSizeBytes = 0;
-  state.persistedSeqByConversation.clear();
 }
 
 /**
@@ -337,7 +276,6 @@ export function _simulateRestartForTesting(): void {
   state.firstStampedSeq = 0;
   state.ring = [];
   state.totalSizeBytes = 0;
-  state.persistedSeqByConversation.clear();
 }
 
 /**

package/src/runtime/channel-reply-delivery.ts

@@ -12,10 +12,6 @@ import { getLogger } from "../util/logger.js";
 import type { ChannelDeliveryResult } from "./gateway-client.js";
 import { deliverChannelReply } from "./gateway-client.js";
 import type { RuntimeAttachmentMetadata } from "./http-types.js";
-import {
-  isSlackCallbackUrl,
-  textToSlackBlocks,
-} from "./slack-block-formatting.js";
 
 const log = getLogger("channel-reply-delivery");
 
@@ -167,8 +163,6 @@ export async function deliverRenderedReplyViaCallback(
     return;
   }
 
-  const isSlack = isSlackCallbackUrl(callbackUrl);
-
   // Only the first segment uses messageTs for in-place update;
   // subsequent segments are posted as new messages.
   let currentMessageTs = messageTs;
@@ -177,13 +171,14 @@ export async function deliverRenderedReplyViaCallback(
     const isLastSegment = i === deliverableSegments.length - 1;
     const isFirstSegment = i === startFromSegment;
     const segmentText = deliverableSegments[i];
-    const blocks = isSlack ? textToSlackBlocks(segmentText) : undefined;
     const result: ChannelDeliveryResult = await deliverChannelReply(
       callbackUrl,
       {
         chatId,
         text: segmentText,
-        blocks,
+        // Ask the channel to render richly; each channel's adapter decides how
+        // (Slack → Block Kit). Channels without rich rendering send plain text.
+        useBlocks: true,
         attachments: isLastSegment ? replyAttachments : undefined,
         assistantId,
         ephemeral,

package/src/runtime/guardian-vellum-migration.ts

@@ -9,7 +9,7 @@
 
 import type { ChannelId } from "../channels/types.js";
 import {
-  findGuardianForChannel,
+  findContactByAddress,
   updateContactPrincipalAndChannel,
 } from "../contacts/contact-store.js";
 import {
@@ -44,8 +44,7 @@ const log = getLogger("guardian-vellum-migration");
  * Returns true if healing occurred, false otherwise.
  *
  * The gateway binding supplies the authoritative principal; the local
- * assistant-mirror row is repaired whenever it diverges from the JWT
- * principal — even when the gateway binding already matches — because the
+ * assistant-mirror row is repaired to match the JWT principal because the
  * /v1/messages trust path still resolves against the local mirror in this
  * plan. A stale mirror must be repaired or valid guardians stay `unknown`.
  */
@@ -62,28 +61,31 @@ export async function healGuardianBindingDrift(
   if (!guardian) return false;
 
   const currentPrincipalId = guardian.principalId;
+  // Only repair auto-generated principals — never overwrite a real one.
   if (!currentPrincipalId?.startsWith("vellum-principal-")) return false;
+  // No-op when the principal already matches the JWT principal.
+  if (currentPrincipalId === incomingPrincipalId) return false;
 
-  // Resolve the assistant-mirror row whose principal drives local trust.
-  const guardianResult = findGuardianForChannel("vellum");
-  if (!guardianResult) return false;
-
-  const localPrincipalId = guardianResult.contact.principalId;
-  // Only repair auto-generated local principals — never overwrite a real one.
-  if (!localPrincipalId?.startsWith("vellum-principal-")) return false;
-  // No-op when the local mirror already matches the JWT principal.
-  if (localPrincipalId === incomingPrincipalId) return false;
+  // Resolve the assistant-mirror row to repair so local trust resolution
+  // converges on the JWT principal. The gateway delivery supplies the guardian
+  // identity (channel + address) but not the local channel UUID write target,
+  // so resolve that locally by the guardian's vellum-channel address.
+  const localContact = findContactByAddress("vellum", guardian.address);
+  const localChannel = localContact?.channels.find(
+    (c) => c.type === "vellum",
+  );
+  if (!localContact || !localChannel) return false;
 
   const updated = updateContactPrincipalAndChannel(
-    guardianResult.contact.id,
-    guardianResult.channel.id,
+    localContact.id,
+    localChannel.id,
     incomingPrincipalId,
   );
 
   if (!updated) {
     log.warn(
       {
-        oldPrincipalId: localPrincipalId,
+        oldPrincipalId: currentPrincipalId,
         newPrincipalId: incomingPrincipalId,
       },
       "Skipped guardian binding drift heal — address collision on contact_channels",
@@ -93,7 +95,7 @@ export async function healGuardianBindingDrift(
 
   log.info(
     {
-      oldPrincipalId: localPrincipalId,
+      oldPrincipalId: currentPrincipalId,
       newPrincipalId: incomingPrincipalId,
     },
     "Healed vellum guardian binding drift — updated local mirror principalId to match JWT actor",

package/src/runtime/invite-redemption-service.ts

@@ -13,8 +13,9 @@ import {
 } from "../calls/inbound-trust-reader.js";
 import type { ChannelId } from "../channels/types.js";
 import { findContactChannel, getContact } from "../contacts/contact-store.js";
+import { gatewayContactChannelState } from "../contacts/gateway-channel-read.js";
 import { activateMemberChannel } from "../contacts/member-write-relay.js";
-import type { ChannelStatus } from "../contacts/types.js";
+import type { ChannelStatus, ContactChannel } from "../contacts/types.js";
 import { ipcCallPersistent } from "../ipc/gateway-client.js";
 import {
   findActiveVoiceInvites,
@@ -33,19 +34,33 @@ const log = getLogger("invite-redemption-service");
 
 /**
  * Resolve the sender's existing member status for the already_member/blocked
- * gate from the gateway trust verdict. Falls back to the local channel status
- * when the verdict is absent or carries no resolvable member status (e.g. an
- * externalChatId-only match or a resolutionFailed verdict), so a locally
- * blocked contact can't bypass the gate.
+ * gate from the gateway trust verdict. Falls back to the gateway-sourced channel
+ * status when the verdict is absent or carries no resolvable member status (e.g.
+ * an externalChatId-only match or a resolutionFailed verdict), so a blocked
+ * contact can't bypass the gate.
  */
 export async function resolveMemberGateStatus(
   verdict: Awaited<ReturnType<typeof getInboundTrustVerdict>>,
-  localChannelStatus: ChannelStatus | null,
+  fallbackStatus: ChannelStatus | null,
 ): Promise<ChannelStatus | null> {
   const memberStatus = verdict
     ? verdictMemberFromVerdict(verdict)?.status
     : null;
-  return memberStatus ?? localChannelStatus;
+  return memberStatus ?? fallbackStatus;
+}
+
+/**
+ * Gateway-sourced status for an existing local channel, used as the gate-status
+ * fallback when the verdict resolves no member. The local row is only located by
+ * identity; its status is read from the gateway (ACL source of truth), never the
+ * local column.
+ */
+async function gatewayFallbackStatus(
+  channel: Pick<ContactChannel, "contactId" | "type" | "address"> | null,
+): Promise<ChannelStatus | null> {
+  if (!channel) return null;
+  const state = await gatewayContactChannelState(channel);
+  return (state?.status as ChannelStatus | undefined) ?? null;
 }
 
 // ---------------------------------------------------------------------------
@@ -245,7 +260,7 @@ export async function redeemInvite(params: {
       channelType: sourceChannel as ChannelId,
       actorExternalId: canonicalUserId,
     }),
-    existingChannel?.status ?? null,
+    await gatewayFallbackStatus(existingChannel),
   );
 
   if (existingChannel && gateStatus === "active" && !targetMismatch) {
@@ -481,7 +496,7 @@ export async function redeemVoiceInviteCode(params: {
 
   const gateStatus = await resolveMemberGateStatus(
     await getPhoneCallerVerdict(canonicalCallerId),
-    existingVoiceChannel?.status ?? null,
+    await gatewayFallbackStatus(existingVoiceChannel),
   );
 
   if (existingVoiceChannel && gateStatus === "active" && !targetMismatch) {
@@ -657,7 +672,7 @@ export async function redeemInviteByCode(params: {
       channelType: sourceChannel as ChannelId,
       actorExternalId: canonicalUserId,
     }),
-    existingChannel?.status ?? null,
+    await gatewayFallbackStatus(existingChannel),
   );
 
   if (existingChannel && gateStatus === "active" && !targetMismatch) {

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

@@ -0,0 +1,108 @@
+/**
+ * Tests for the local-actor-identity cache-warm path.
+ *
+ * The SSE eager-subscribe path resolves the local actor principal
+ * synchronously from the IO-free guardian-delivery cache snapshot. A cold
+ * cache returns undefined, so the daemon warms it at startup
+ * (`warmLocalGuardianPrincipalCache`) before clients register. These tests pin
+ * that the sync read is cold before the warm and resolves the gateway-owned
+ * principal after it.
+ */
+
+import { afterEach, 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>();
+
+mock.module("../ipc/gateway-client.js", () => ({
+  ipcCall: async (method: string, params?: Record<string, unknown>) => {
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+let httpAuthDisabled = false;
+mock.module("../config/env.js", () => ({
+  isHttpAuthDisabled: () => httpAuthDisabled,
+}));
+
+import { __resetGuardianDeliveryCacheForTest } from "../contacts/guardian-delivery-reader.js";
+import {
+  findLocalGuardianPrincipalIdFromStore,
+  resolveActorPrincipalIdForLocalGuardianSync,
+  warmLocalGuardianPrincipalCache,
+} from "./local-actor-identity.js";
+
+const METHOD = "resolve_guardian_delivery";
+
+const vellumGuardian: GuardianDelivery = {
+  channelType: "vellum",
+  contactId: "contact-1",
+  address: "self",
+  status: "active",
+  principalId: "principal-abc",
+};
+
+describe("warmLocalGuardianPrincipalCache", () => {
+  beforeEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+    ipcHandlers.clear();
+    httpAuthDisabled = false;
+  });
+
+  afterEach(() => {
+    __resetGuardianDeliveryCacheForTest();
+  });
+
+  test("sync read is cold before warming", () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+
+    // No warm yet — the cache snapshot is empty.
+    expect(findLocalGuardianPrincipalIdFromStore()).toBeUndefined();
+  });
+
+  test("warming populates the cache for the sync read", async () => {
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+
+    await warmLocalGuardianPrincipalCache();
+
+    expect(findLocalGuardianPrincipalIdFromStore()).toBe("principal-abc");
+  });
+
+  test("cold-start SSE registration resolves the principal after warm", async () => {
+    httpAuthDisabled = true;
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+
+    // Cold cache: dev-bypass header resolves to no principal.
+    expect(
+      resolveActorPrincipalIdForLocalGuardianSync("dev-bypass"),
+    ).toBeUndefined();
+
+    await warmLocalGuardianPrincipalCache();
+
+    // Warmed: the SSE sync path now resolves the gateway-owned principal.
+    expect(resolveActorPrincipalIdForLocalGuardianSync("dev-bypass")).toBe(
+      "principal-abc",
+    );
+  });
+
+  test("warm tolerates an unreachable gateway without caching a failure", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("gateway down");
+    });
+
+    await warmLocalGuardianPrincipalCache();
+
+    // Failure not cached; a later successful read warms the cache.
+    expect(findLocalGuardianPrincipalIdFromStore()).toBeUndefined();
+    ipcHandlers.set(METHOD, () => ({ guardians: [vellumGuardian] }));
+    await warmLocalGuardianPrincipalCache();
+    expect(findLocalGuardianPrincipalIdFromStore()).toBe("principal-abc");
+  });
+});

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

@@ -13,7 +13,6 @@
 
 import type { ChannelId } from "../channels/types.js";
 import { isHttpAuthDisabled } from "../config/env.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
 import {
   getGuardianDelivery,
   guardianForChannel,
@@ -54,24 +53,37 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
  *
  * 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. Falls back to the local contacts table for the bootstrap /
- * first-run window where the gateway has no guardian yet or is unreachable
- * (the reader returns `null`).
+ * storm the IPC.
  *
- * Returns `undefined` when no vellum guardian binding exists in either source
- * (e.g. fresh install before bootstrap). Callers should treat that case as
- * "not yet available" and either fall back or proceed without a principalId.
+ * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
+ * 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) {
-    const principalId = guardianForChannel(list, "vellum")?.principalId;
-    if (principalId) return principalId;
-  }
+  if (!list) return undefined;
+  return guardianForChannel(list, "vellum")?.principalId ?? undefined;
+}
 
-  return findLocalGuardianPrincipalIdFromStore();
+/**
+ * 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 async function warmLocalGuardianPrincipalCache(): Promise<void> {
+  await findLocalGuardianPrincipalId();
 }
 
 /**
@@ -82,17 +94,12 @@ export async function findLocalGuardianPrincipalId(): Promise<
  * 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. Falls back to the local store when the cache is
- * cold — the same fallback the async path lands on during bootstrap.
+ * send/result routes resolve.
  */
 export function findLocalGuardianPrincipalIdFromStore(): string | undefined {
   const cached = peekCachedGuardianDelivery({ channelTypes: ["vellum"] });
-  if (cached) {
-    const principalId = guardianForChannel(cached, "vellum")?.principalId;
-    if (principalId) return principalId;
-  }
-
-  return findGuardianForChannel("vellum")?.contact.principalId ?? undefined;
+  if (!cached) return undefined;
+  return guardianForChannel(cached, "vellum")?.principalId ?? undefined;
 }
 
 /**

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

@@ -14,6 +14,7 @@
 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 = {};
@@ -44,16 +45,53 @@ const contactStoreReadGuard = mock(() => {
   );
 });
 
+// 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"
-);
+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",
@@ -76,7 +114,7 @@ const gatewayChannel = {
 const gatewayContact = {
   id: "ct_1",
   displayName: "Alice",
-  role: "member",
+  role: "guardian",
   notes: "a note",
   contactType: "human",
   lastInteraction: 1900,
@@ -93,6 +131,8 @@ describe("contacts read API relays from the gateway", () => {
     ipcError = undefined;
     ipcCallPersistentMock.mockClear();
     contactStoreReadGuard.mockClear();
+    searchContactsResult = [];
+    searchContactsMock.mockClear();
   });
 
   test("list relays to contacts_list_rich and serializes the gateway ACL fields", async () => {
@@ -108,7 +148,7 @@ describe("contacts read API relays from the gateway", () => {
 
     const [contact] = result.contacts;
     // ACL fields are gateway-sourced and reach the web client unchanged.
-    expect(contact.role).toBe("member");
+    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>;
@@ -159,7 +199,7 @@ describe("contacts read API relays from the gateway", () => {
       { method: "contacts_get_rich", params: { contactId: "ct_1" } },
     ]);
     expect(result.ok).toBe(true);
-    expect(result.contact.role).toBe("member");
+    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");
@@ -204,9 +244,62 @@ describe("contacts read API relays from the gateway", () => {
     expect(ipcCalls).toEqual([
       { method: "contacts_list_rich", params: { limit: 50 } },
     ]);
-    expect(contacts[0].role).toBe("member");
+    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();
+  });
+});