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

package/src/ipc/routes/__tests__/contacts-mirror-ipc-routes.test.ts

@@ -0,0 +1,322 @@
+/**
+ * The gateway-facing contact identity-mirror methods are IPC-only: registered
+ * on the assistant IPC server by operationId, and absent from the shared HTTP
+ * route set / `get_route_schema`. They write info-only mirror state on top of
+ * the `contact-store` primitives; the gateway DB stays the ACL source of truth.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+const upsertContactChannelCalls: unknown[] = [];
+const upsertContactCalls: unknown[] = [];
+const deleteContactCalls: unknown[] = [];
+
+// Spread the real modules so unrelated consumers (contact-routes) keep their
+// exports; override only the primitives the handlers delegate to.
+const realContactsWrite = await import("../../../contacts/contacts-write.js");
+const realContactStore = await import("../../../contacts/contact-store.js");
+
+mock.module("../../../contacts/contacts-write.js", () => ({
+  ...realContactsWrite,
+  upsertContactChannel: (params: unknown) => {
+    upsertContactChannelCalls.push(params);
+    return null;
+  },
+}));
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...realContactStore,
+  upsertContact: (params: unknown) => {
+    upsertContactCalls.push(params);
+    return { created: true };
+  },
+  deleteContact: (id: unknown) => {
+    deleteContactCalls.push(id);
+  },
+}));
+
+// The transactional method wraps ops in getDb().transaction(); run the callback
+// inline so op dispatch is observable against the mocked primitives above.
+// Spread the real module so unrelated exports stay intact if suites ever share
+// a process.
+const realDbConnection = await import(
+  "../../../persistence/db-connection.js"
+);
+mock.module("../../../persistence/db-connection.js", () => ({
+  ...realDbConnection,
+  getDb: () => ({ transaction: (fn: () => void) => fn() }),
+}));
+
+const {
+  CONTACTS_MIRROR_IPC_METHODS,
+  handleContactsMirrorUpsertChannel,
+  handleContactsMirrorUpsertContact,
+  handleContactsMirrorDeleteContact,
+  handleContactsMirrorApply,
+} = await import("../contacts-mirror-ipc-routes.js");
+
+const { ROUTES: contactRoutes } = await import(
+  "../../../runtime/routes/contact-routes.js"
+);
+const { routeDefinitionsToIpcMethods } = await import("../route-adapter.js");
+
+const MIRROR_OPERATION_IDS = [
+  "contacts_mirror_upsert_channel",
+  "contacts_mirror_upsert_contact",
+  "contacts_mirror_delete_contact",
+  "contacts_mirror_apply",
+] as const;
+
+describe("contact identity-mirror IPC-only methods", () => {
+  test("are reachable on the IPC surface by operationId", () => {
+    for (const operationId of MIRROR_OPERATION_IDS) {
+      expect(typeof CONTACTS_MIRROR_IPC_METHODS[operationId]).toBe("function");
+    }
+  });
+
+  test("are NOT in the shared contact ROUTES array", () => {
+    const sharedIds = new Set(contactRoutes.map((r) => r.operationId));
+    for (const operationId of MIRROR_OPERATION_IDS) {
+      expect(sharedIds.has(operationId)).toBe(false);
+    }
+  });
+
+  test("are NOT in the gateway-facing get_route_schema", async () => {
+    const ipcMethods = routeDefinitionsToIpcMethods(contactRoutes);
+    const meta = ipcMethods.find((r) => r.operationId === "get_route_schema");
+    expect(meta).toBeDefined();
+    const schema = (await meta!.handler({})) as { operationId: string }[];
+    const schemaIds = new Set(schema.map((e) => e.operationId));
+    for (const operationId of MIRROR_OPERATION_IDS) {
+      expect(schemaIds.has(operationId)).toBe(false);
+    }
+  });
+});
+
+describe("contacts_mirror_upsert_channel", () => {
+  test("maps the wire body onto the info-only channel upsert primitive", () => {
+    upsertContactChannelCalls.length = 0;
+    const result = handleContactsMirrorUpsertChannel({
+      body: {
+        contactId: "co-1",
+        channelId: "ch-1",
+        type: "telegram",
+        address: "tg-123",
+        externalChatId: "chat-9",
+        displayName: "Sam",
+        contactType: "assistant",
+        notes: "bot provenance",
+        refreshDisplayName: true,
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(upsertContactChannelCalls).toHaveLength(1);
+    expect(upsertContactChannelCalls[0]).toEqual({
+      sourceChannel: "telegram",
+      externalUserId: "tg-123",
+      externalChatId: "chat-9",
+      displayName: "Sam",
+      contactId: "co-1",
+      channelId: "ch-1",
+      contactType: "assistant",
+      notes: "bot provenance",
+      refreshDisplayName: true,
+      // The mirror never seeds a persona file: a mirror-created contact keeps
+      // user_file NULL (faithful replica of the gateway's raw INSERT).
+      userFileOnCreate: null,
+    });
+  });
+
+  test("threads channelId + refreshDisplayName through and forces userFileOnCreate null", () => {
+    upsertContactChannelCalls.length = 0;
+    handleContactsMirrorUpsertChannel({
+      body: {
+        contactId: "co-seed",
+        channelId: "gw-ch-42",
+        type: "slack",
+        address: "U777",
+        displayName: "Renamed User",
+        refreshDisplayName: true,
+      },
+    });
+
+    const call = upsertContactChannelCalls[0] as Record<string, unknown>;
+    // Gateway-minted channel id is reused verbatim (id-alignment).
+    expect(call.channelId).toBe("gw-ch-42");
+    // Inbound seed refreshes the display name rather than preserving it.
+    expect(call.refreshDisplayName).toBe(true);
+    // Mirror-created contact keeps user_file NULL.
+    expect(call.userFileOnCreate).toBe(null);
+  });
+
+  test("defaults refreshDisplayName/channelId to undefined for the invite-binding path", () => {
+    upsertContactChannelCalls.length = 0;
+    handleContactsMirrorUpsertChannel({
+      body: {
+        contactId: "co-invite",
+        type: "telegram",
+        address: "tg-999",
+        displayName: "Redeemer Raw Name",
+      },
+    });
+
+    const call = upsertContactChannelCalls[0] as Record<string, unknown>;
+    // No refresh flag → the primitive preserves the curated contact name.
+    expect(call.refreshDisplayName).toBeUndefined();
+    expect(call.channelId).toBeUndefined();
+    // userFileOnCreate is still forced null even on the invite path.
+    expect(call.userFileOnCreate).toBe(null);
+  });
+
+  test("threads reassignConflictingChannels through to the primitive (seed=false, invite=true)", () => {
+    upsertContactChannelCalls.length = 0;
+    handleContactsMirrorUpsertChannel({
+      body: {
+        contactId: "co-seed",
+        type: "slack",
+        address: "USEED",
+        reassignConflictingChannels: false,
+      },
+    });
+    handleContactsMirrorUpsertChannel({
+      body: {
+        contactId: "co-invite",
+        type: "slack",
+        address: "UINV",
+        reassignConflictingChannels: true,
+      },
+    });
+
+    const seedCall = upsertContactChannelCalls[0] as Record<string, unknown>;
+    const inviteCall = upsertContactChannelCalls[1] as Record<string, unknown>;
+    expect(seedCall.reassignConflictingChannels).toBe(false);
+    expect(inviteCall.reassignConflictingChannels).toBe(true);
+  });
+
+  test("leaves reassignConflictingChannels undefined when the wire omits it (primitive defaults)", () => {
+    upsertContactChannelCalls.length = 0;
+    handleContactsMirrorUpsertChannel({
+      body: { contactId: "co-x", type: "slack", address: "UX" },
+    });
+    const call = upsertContactChannelCalls[0] as Record<string, unknown>;
+    expect(call.reassignConflictingChannels).toBeUndefined();
+  });
+
+  test("omits externalChatId when absent (COALESCE-preserving seed update)", () => {
+    upsertContactChannelCalls.length = 0;
+    handleContactsMirrorUpsertChannel({
+      body: { contactId: "co-2", type: "slack", address: "U123" },
+    });
+
+    const call = upsertContactChannelCalls[0] as { externalChatId?: unknown };
+    expect(call.externalChatId).toBeUndefined();
+  });
+
+  test("rejects a body missing the channel type/address", () => {
+    expect(() =>
+      handleContactsMirrorUpsertChannel({ body: { address: "U123" } }),
+    ).toThrow();
+  });
+});
+
+describe("contacts_mirror_upsert_contact", () => {
+  test("upserts an identity/display contact row without seeding a persona file", () => {
+    upsertContactCalls.length = 0;
+    const result = handleContactsMirrorUpsertContact({
+      body: {
+        contactId: "co-guardian",
+        displayName: "Guardian",
+        contactType: "human",
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(upsertContactCalls).toHaveLength(1);
+    expect(upsertContactCalls[0]).toEqual({
+      id: "co-guardian",
+      displayName: "Guardian",
+      contactType: "human",
+      notes: undefined,
+      userFile: null,
+    });
+  });
+
+  test("rejects a body missing contactId/displayName", () => {
+    expect(() =>
+      handleContactsMirrorUpsertContact({ body: { contactId: "co-1" } }),
+    ).toThrow();
+  });
+});
+
+describe("contacts_mirror_delete_contact", () => {
+  test("deletes the mirror contact row by id", () => {
+    deleteContactCalls.length = 0;
+    const result = handleContactsMirrorDeleteContact({
+      body: { contactId: "co-gone" },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(deleteContactCalls).toEqual(["co-gone"]);
+  });
+
+  test("rejects a body missing contactId", () => {
+    expect(() =>
+      handleContactsMirrorDeleteContact({ body: {} }),
+    ).toThrow();
+  });
+});
+
+describe("contacts_mirror_apply", () => {
+  test("dispatches each op to its matching single-row primitive, in order", () => {
+    upsertContactCalls.length = 0;
+    upsertContactChannelCalls.length = 0;
+    deleteContactCalls.length = 0;
+
+    const result = handleContactsMirrorApply({
+      body: {
+        ops: [
+          { op: "upsert_contact", contactId: "co-1", displayName: "One" },
+          {
+            op: "upsert_channel",
+            contactId: "co-1",
+            type: "telegram",
+            address: "tg-1",
+            isPrimary: true,
+          },
+          { op: "delete_contact", contactId: "co-old" },
+        ],
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+    // Each op reuses the exact single-row primitive semantics.
+    expect(upsertContactCalls).toHaveLength(1);
+    expect(upsertContactCalls[0]).toEqual({
+      id: "co-1",
+      displayName: "One",
+      contactType: undefined,
+      notes: undefined,
+      userFile: null,
+    });
+    expect(upsertContactChannelCalls).toHaveLength(1);
+    const chCall = upsertContactChannelCalls[0] as Record<string, unknown>;
+    expect(chCall.contactId).toBe("co-1");
+    // isPrimary threads through so the guardian mirror keeps its primary flag.
+    expect(chCall.isPrimary).toBe(true);
+    expect(chCall.userFileOnCreate).toBe(null);
+    expect(deleteContactCalls).toEqual(["co-old"]);
+  });
+
+  test("rejects an unknown op discriminator", () => {
+    expect(() =>
+      handleContactsMirrorApply({
+        body: { ops: [{ op: "nope", contactId: "co-1" }] },
+      }),
+    ).toThrow();
+  });
+
+  test("rejects an empty ops array", () => {
+    expect(() => handleContactsMirrorApply({ body: { ops: [] } })).toThrow();
+  });
+});

package/src/ipc/routes/__tests__/invite-ipc-routes.test.ts

@@ -1,7 +1,7 @@
 /**
- * The three gateway-facing invite methods are IPC-only: registered on the
- * assistant IPC server by operationId, and absent from the shared HTTP route
- * set / `get_route_schema`. Relocating them out of `ROUTES` (per the
+ * The gateway-facing invite methods are IPC-only: registered on the
+ * assistant IPC server by operationId, and absent from the shared HTTP
+ * route set / `get_route_schema`. Relocating them out of `ROUTES` (per the
  * documented IPC-only pattern) is what structurally guarantees they can never
  * reach the gateway's HTTP IPC proxy route schema.
  */
@@ -21,12 +21,27 @@ mock.module("../../../security/secure-keys.js", () => ({
   deleteSecureKeyAsync: async () => {},
 }));
 
+// Wiring-only: the real composition (guardian-name resolution, contact
+// lookups) needs a migrated DB and is unit-tested in invite-routes-http.
+// A passthrough keeps this suite asserting envelope + payload retention.
+mock.module("../../../runtime/invite-service.js", () => ({
+  composeInvitePresentation: async (params: {
+    invite: Record<string, unknown>;
+  }) => params.invite,
+}));
+
 import { ROUTES as contactRoutes } from "../../../runtime/routes/contact-routes.js";
 import { INVITE_IPC_METHODS } from "../invite-ipc-routes.js";
 import { routeDefinitionsToIpcMethods } from "../route-adapter.js";
 
 const INVITE_IPC_OPERATION_IDS = [
-  "invites_mint",
+  "invite_redeemed",
+  "invites_compose_presentation",
+] as const;
+
+// Redemption is gateway-native: the daemon must expose NO redeem IPC methods
+// (the daemon redeem route relays to the gateway's `invites_redeem` instead).
+const REMOVED_REDEEM_OPERATION_IDS = [
   "invites_redeem_voice",
   "invites_redeem_token",
 ] as const;
@@ -38,6 +53,12 @@ describe("invite IPC-only methods", () => {
     }
   });
 
+  test("expose no daemon-local redeem methods (redemption is gateway-native)", () => {
+    for (const operationId of REMOVED_REDEEM_OPERATION_IDS) {
+      expect(INVITE_IPC_METHODS[operationId]).toBeUndefined();
+    }
+  });
+
   test("are NOT in the shared contact ROUTES array", () => {
     const sharedIds = new Set(contactRoutes.map((r) => r.operationId));
     for (const operationId of INVITE_IPC_OPERATION_IDS) {
@@ -56,3 +77,38 @@ describe("invite IPC-only methods", () => {
     }
   });
 });
+
+// Wiring-only coverage: composition behavior itself is unit-tested against
+// the real `composeInvitePresentation` in `invite-routes-http.test.ts`, and
+// the gateway HTTP merge is covered in the gateway proxy suite. Asserting
+// only merge-retention here keeps this file independent of the
+// `invite-service` module mocks other suites install in a shared bun process.
+describe("invites_compose_presentation", () => {
+  test("returns an { invite } envelope preserving the one-time mint payload", async () => {
+    const result = (await INVITE_IPC_METHODS.invites_compose_presentation({
+      body: {
+        contactId: "ct-1",
+        invite: {
+          id: "inv-1",
+          sourceChannel: "phone",
+          friendName: "Sam Example",
+          voiceCode: "123456",
+        },
+      },
+    })) as { invite: Record<string, unknown> };
+
+    expect(result.invite.id).toBe("inv-1");
+    expect(result.invite.voiceCode).toBe("123456");
+    expect(result.invite.friendName).toBe("Sam Example");
+  });
+
+  test("rejects a payload without an invite object", async () => {
+    await expect(
+      Promise.resolve(
+        INVITE_IPC_METHODS.invites_compose_presentation({
+          body: { contactId: "ct-1" },
+        }),
+      ),
+    ).rejects.toThrow();
+  });
+});

package/src/ipc/routes/contacts-info-ipc-routes.ts

@@ -0,0 +1,239 @@
+/**
+ * IPC-only contact INFO-READ methods called by the gateway over the assistant
+ * IPC socket (`ipcCallAssistant`).
+ *
+ * These replace the gateway's raw `db_proxy` SELECTs against the assistant DB
+ * with typed, zod-validated reads of the assistant-owned informational fields
+ * (`notes`, `user_file`, `contact_type`, `assistant_contact_metadata`) and
+ * contact-channel identity. ACL data stays gateway-owned; these methods never
+ * touch it.
+ *
+ * Like the invite IPC methods, they have no HTTP surface: they are registered
+ * directly on the IPC server (see `assistant-server.ts`) and never enter the
+ * shared `ROUTES` array, so they can never reach the gateway's HTTP IPC proxy
+ * route schema.
+ */
+
+import { and, eq, inArray, like, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../../persistence/db-connection.js";
+import {
+  assistantContactMetadata,
+  contactChannels,
+  contacts,
+} from "../../persistence/schema/index.js";
+import type { RouteHandlerArgs } from "../../runtime/routes/types.js";
+
+/**
+ * Derive the daemon-owned assistant-metadata block. Gated on
+ * `contactType === "assistant"` so a stale metadata row on a human contact is
+ * never emitted (matches the daemon rich-read contract). A malformed JSON blob
+ * degrades to `null` metadata rather than throwing.
+ */
+function toAssistantMetadata(
+  contactType: string | null,
+  species: string | null,
+  metadataText: string | null,
+): { species: string; metadata: Record<string, unknown> | null } | null {
+  if (contactType !== "assistant" || species == null) return null;
+  let metadata: Record<string, unknown> | null = null;
+  if (metadataText) {
+    try {
+      metadata = JSON.parse(metadataText) as Record<string, unknown>;
+    } catch {
+      metadata = null;
+    }
+  }
+  return { species, metadata };
+}
+
+// ---------------------------------------------------------------------------
+// contacts_info_batch
+// ---------------------------------------------------------------------------
+
+const ContactsInfoBatchParamsSchema = z.object({
+  contactIds: z.array(z.string()),
+});
+
+/**
+ * Batch read of the assistant-owned info fields for a set of contact IDs.
+ * Replaces the info-joiner's raw SELECT. Contacts absent from the assistant DB
+ * are simply omitted; the caller treats a missing entry as "info unavailable".
+ */
+export function handleContactsInfoBatch({ body = {} }: RouteHandlerArgs) {
+  const { contactIds } = ContactsInfoBatchParamsSchema.parse(body);
+  if (contactIds.length === 0) return { infos: [] };
+
+  const db = getDb();
+  const rows = db
+    .select({
+      id: contacts.id,
+      notes: contacts.notes,
+      userFile: contacts.userFile,
+      contactType: contacts.contactType,
+      species: assistantContactMetadata.species,
+      metadata: assistantContactMetadata.metadata,
+    })
+    .from(contacts)
+    .leftJoin(
+      assistantContactMetadata,
+      eq(assistantContactMetadata.contactId, contacts.id),
+    )
+    .where(inArray(contacts.id, contactIds))
+    .all();
+
+  const infos = rows.map((row) => ({
+    contactId: row.id,
+    notes: row.notes ?? null,
+    userFile: row.userFile ?? null,
+    contactType: row.contactType ?? null,
+    assistantMetadata: toAssistantMetadata(
+      row.contactType,
+      row.species,
+      row.metadata,
+    ),
+  }));
+  return { infos };
+}
+
+// ---------------------------------------------------------------------------
+// contact_channel_identity_lookup
+// ---------------------------------------------------------------------------
+
+const ChannelIdentityLookupParamsSchema = z
+  .object({
+    channelId: z.string().optional(),
+    type: z.string().optional(),
+    address: z.string().optional(),
+  })
+  .refine(
+    (v) => v.channelId != null || (v.type != null && v.address != null),
+    { message: "Provide channelId, or both type and address" },
+  );
+
+const CHANNEL_IDENTITY_PROJECTION = {
+  id: contactChannels.id,
+  contactId: contactChannels.contactId,
+  type: contactChannels.type,
+  address: contactChannels.address,
+  externalChatId: contactChannels.externalChatId,
+  displayName: contacts.displayName,
+};
+
+/**
+ * Resolve a contact-channel identity by `channelId` OR by logical
+ * `(type, address)` (COLLATE NOCASE). Replaces the raw identity SELECTs in the
+ * verification helpers and the gateway channel resolver. Returns the channel's
+ * identity fields (no ACL/status).
+ */
+export function handleContactChannelIdentityLookup({
+  body = {},
+}: RouteHandlerArgs) {
+  const params = ChannelIdentityLookupParamsSchema.parse(body);
+  const db = getDb();
+
+  const where =
+    params.channelId != null
+      ? eq(contactChannels.id, params.channelId)
+      : and(
+          eq(contactChannels.type, params.type!),
+          sql`${contactChannels.address} = ${params.address!} COLLATE NOCASE`,
+        );
+
+  const row = db
+    .select(CHANNEL_IDENTITY_PROJECTION)
+    .from(contactChannels)
+    .innerJoin(contacts, eq(contacts.id, contactChannels.contactId))
+    .where(where)
+    .get();
+
+  return { channel: row ?? null };
+}
+
+// ---------------------------------------------------------------------------
+// contact_mirror_probe
+// ---------------------------------------------------------------------------
+
+const ContactMirrorProbeParamsSchema = z.object({ contactId: z.string() });
+
+/**
+ * Probe the assistant mirror for one contact: whether the row and any channels
+ * exist, the guardian-authored info fields, and whether an assistant-metadata
+ * row is present. Feeds the gateway orphan-veto and delete-target decisions.
+ */
+export function handleContactMirrorProbe({ body = {} }: RouteHandlerArgs) {
+  const { contactId } = ContactMirrorProbeParamsSchema.parse(body);
+  const db = getDb();
+
+  const contactRow = db
+    .select({
+      notes: contacts.notes,
+      userFile: contacts.userFile,
+      contactType: contacts.contactType,
+    })
+    .from(contacts)
+    .where(eq(contacts.id, contactId))
+    .get();
+
+  const channelRow = db
+    .select({ id: contactChannels.id })
+    .from(contactChannels)
+    .where(eq(contactChannels.contactId, contactId))
+    .limit(1)
+    .get();
+
+  const metadataRow = db
+    .select({ contactId: assistantContactMetadata.contactId })
+    .from(assistantContactMetadata)
+    .where(eq(assistantContactMetadata.contactId, contactId))
+    .limit(1)
+    .get();
+
+  return {
+    exists: contactRow != null,
+    hasChannels: channelRow != null,
+    notes: contactRow?.notes ?? null,
+    userFile: contactRow?.userFile ?? null,
+    contactType: contactRow?.contactType ?? null,
+    hasMetadata: metadataRow != null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// contact_user_file_slugs
+// ---------------------------------------------------------------------------
+
+const ContactUserFileSlugsParamsSchema = z.object({ prefix: z.string() });
+
+/**
+ * List the `user_file` slugs matching `prefix%`. Feeds the gateway's
+ * collision-suffixed slug allocation for a new contact.
+ */
+export function handleContactUserFileSlugs({ body = {} }: RouteHandlerArgs) {
+  const { prefix } = ContactUserFileSlugsParamsSchema.parse(body);
+  const db = getDb();
+  const rows = db
+    .select({ userFile: contacts.userFile })
+    .from(contacts)
+    .where(like(contacts.userFile, `${prefix}%`))
+    .all();
+  const userFiles = rows
+    .map((r) => r.userFile)
+    .filter((f): f is string => f != null);
+  return { userFiles };
+}
+
+/**
+ * IPC-only contact info-read methods, keyed by IPC operationId. Registered
+ * directly on the assistant IPC server (see `assistant-server.ts`).
+ */
+export const CONTACTS_INFO_IPC_METHODS: Record<
+  string,
+  (args: RouteHandlerArgs) => unknown
+> = {
+  contacts_info_batch: handleContactsInfoBatch,
+  contact_channel_identity_lookup: handleContactChannelIdentityLookup,
+  contact_mirror_probe: handleContactMirrorProbe,
+  contact_user_file_slugs: handleContactUserFileSlugs,
+};