@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/contacts/__tests__/mirror-reconciler.test.ts

@@ -0,0 +1,352 @@
+/**
+ * Tests for the pull-based contact-mirror reconciler.
+ *
+ * The reconciler converges the assistant identity mirror onto the gateway's
+ * identity snapshot: it must heal missing rows under the gateway's own ids,
+ * hand a divergent channel to the contact the gateway says owns it, and
+ * write NOTHING else. Assistant-authored data (notes, classification,
+ * curated names) and mirror-only rows (a2a peers) are exactly what a pull
+ * from the gateway cannot reconstruct, so preserving them is as load-bearing
+ * as the healing.
+ *
+ * The daemon DB is real; the gateway snapshot arrives through a mocked
+ * `ipcCallPersistent`.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ContactsIdentitySnapshotIpcResponse } from "@vellumai/gateway-client/gateway-ipc-contracts";
+
+let snapshot: ContactsIdentitySnapshotIpcResponse = { ok: true, contacts: [] };
+const ipcCallPersistentMock = mock(async (method: string) => {
+  if (method !== "contacts_identity_snapshot") {
+    throw new Error(`unexpected IPC method: ${method}`);
+  }
+  return snapshot;
+});
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+import { getSqlite } from "../../persistence/db-connection.js";
+import { initializeDb } from "../../persistence/db-init.js";
+import { deleteContact, upsertContact } from "../contact-store.js";
+import { upsertContactChannel } from "../contacts-write.js";
+import { runMirrorReconcile } from "../mirror-reconciler.js";
+await initializeDb();
+
+function resetContactTables(): void {
+  const sqlite = getSqlite();
+  sqlite.run("DELETE FROM contact_channels");
+  sqlite.run("DELETE FROM contacts");
+}
+
+function contactRow(
+  id: string,
+): { displayName: string; notes: string | null } | null {
+  return getSqlite()
+    .query(
+      "SELECT display_name AS displayName, notes FROM contacts WHERE id = ?",
+    )
+    .get(id) as { displayName: string; notes: string | null } | null;
+}
+
+function channelRow(
+  type: string,
+  address: string,
+): { id: string; contactId: string; externalChatId: string | null } | null {
+  return getSqlite()
+    .query(
+      "SELECT id, contact_id AS contactId, external_chat_id AS externalChatId FROM contact_channels WHERE type = ? AND address = ? COLLATE NOCASE",
+    )
+    .get(type, address) as {
+    id: string;
+    contactId: string;
+    externalChatId: string | null;
+  } | null;
+}
+
+function gatewayContact(opts: {
+  id: string;
+  displayName: string;
+  channels?: Array<{
+    id: string;
+    type: string;
+    address: string;
+    externalChatId?: string | null;
+    isPrimary?: boolean;
+  }>;
+}): ContactsIdentitySnapshotIpcResponse["contacts"][number] {
+  return {
+    id: opts.id,
+    displayName: opts.displayName,
+    channels: (opts.channels ?? []).map((ch) => ({
+      id: ch.id,
+      contactId: opts.id,
+      type: ch.type,
+      address: ch.address,
+      externalChatId: ch.externalChatId ?? null,
+      isPrimary: ch.isPrimary ?? false,
+    })),
+  };
+}
+
+beforeEach(() => {
+  resetContactTables();
+  snapshot = { ok: true, contacts: [] };
+  ipcCallPersistentMock.mockClear();
+});
+
+describe("healing toward the gateway snapshot", () => {
+  test("recreates a missing contact + channel under the gateway ids", async () => {
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-gw",
+          displayName: "Alice Example",
+          channels: [
+            {
+              id: "ch-gw",
+              type: "slack",
+              address: "U123",
+              externalChatId: "D123",
+            },
+          ],
+        }),
+      ],
+    };
+
+    await runMirrorReconcile();
+
+    expect(channelRow("slack", "U123")).toEqual({
+      id: "ch-gw",
+      contactId: "co-gw",
+      externalChatId: "D123",
+    });
+    expect(contactRow("co-gw")?.displayName).toBe("Alice Example");
+  });
+
+  test("hands a divergent channel to the contact the gateway says owns it", async () => {
+    // The mirror believes the channel belongs to a stale owner.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "U123",
+      displayName: "Stale Owner",
+      contactId: "co-stale",
+      channelId: "ch-stale",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-truth",
+          displayName: "Alice Example",
+          channels: [{ id: "ch-gw", type: "slack", address: "U123" }],
+        }),
+      ],
+    };
+
+    await runMirrorReconcile();
+
+    expect(channelRow("slack", "U123")?.contactId).toBe("co-truth");
+    // The heal adopts the gateway id in the same write.
+    expect(channelRow("slack", "U123")?.id).toBe("ch-gw");
+  });
+
+  test("adopts the gateway channel id onto a same-owner legacy row, then reaches a fixed point", async () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "U123",
+      displayName: "Alice Example",
+      contactId: "co-1",
+      channelId: "legacy-ch",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-1",
+          displayName: "Alice Example",
+          channels: [{ id: "ch-gw", type: "slack", address: "U123" }],
+        }),
+      ],
+    };
+
+    await runMirrorReconcile();
+    expect(channelRow("slack", "U123")?.id).toBe("ch-gw");
+
+    // Converged: a follow-up pass writes nothing.
+    const before = getSqlite()
+      .query("SELECT updated_at AS u FROM contact_channels WHERE id = 'ch-gw'")
+      .get() as { u: number };
+    await runMirrorReconcile();
+    const after = getSqlite()
+      .query("SELECT updated_at AS u FROM contact_channels WHERE id = 'ch-gw'")
+      .get() as { u: number };
+    expect(after.u).toBe(before.u);
+  });
+
+  test("recreates a channel-less gateway contact as an identity stub", async () => {
+    snapshot = {
+      ok: true,
+      contacts: [gatewayContact({ id: "co-record", displayName: "Mom" })],
+    };
+
+    await runMirrorReconcile();
+
+    expect(contactRow("co-record")?.displayName).toBe("Mom");
+  });
+});
+
+describe("what a pull must never touch", () => {
+  test("mirror-only rows and assistant-authored fields survive untouched", async () => {
+    // An a2a peer exists only in the mirror; the seed contact carries
+    // guardian-authored notes and a curated name.
+    upsertContact({
+      id: "co-a2a",
+      displayName: "Peer Assistant",
+      contactType: "assistant",
+      channels: [{ type: "a2a", address: "peer-assistant-id" }],
+    });
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "U123",
+      displayName: "Platform Name",
+      contactId: "co-known",
+      channelId: "ch-known",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    upsertContact({
+      id: "co-known",
+      displayName: "Curated Name",
+      notes: "vip",
+    });
+
+    // The gateway snapshot knows co-known (with a different display name,
+    // the curated gateway one) and has never heard of the a2a peer.
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-known",
+          displayName: "Gateway Curated",
+          channels: [{ id: "ch-known", type: "slack", address: "U123" }],
+        }),
+      ],
+    };
+
+    await runMirrorReconcile();
+
+    expect(channelRow("a2a", "peer-assistant-id")?.contactId).toBe("co-a2a");
+    expect(contactRow("co-a2a")?.displayName).toBe("Peer Assistant");
+    expect(contactRow("co-known")).toEqual({
+      displayName: "Curated Name",
+      notes: "vip",
+    });
+  });
+
+  test("a converged mirror takes no writes (fixed point)", async () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "U123",
+      externalChatId: "D123",
+      displayName: "Alice Example",
+      contactId: "co-1",
+      channelId: "ch-1",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-1",
+          displayName: "Gateway Name",
+          channels: [
+            {
+              id: "ch-1",
+              type: "slack",
+              address: "U123",
+              externalChatId: "D123",
+            },
+          ],
+        }),
+      ],
+    };
+    const before = getSqlite()
+      .query("SELECT updated_at AS u FROM contact_channels WHERE id = 'ch-1'")
+      .get() as { u: number };
+
+    await runMirrorReconcile();
+
+    const after = getSqlite()
+      .query("SELECT updated_at AS u FROM contact_channels WHERE id = 'ch-1'")
+      .get() as { u: number };
+    expect(after.u).toBe(before.u);
+    // Display name still the mirror's own (a no-op pass rewrites nothing).
+    expect(contactRow("co-1")?.displayName).toBe("Alice Example");
+  });
+
+  test("a snapshot pulled before a delete cannot resurrect the deleted contact", async () => {
+    // The gateway deleted co-gone (and the explicit mirror delete op landed)
+    // while a snapshot still listing it was in flight. Healing from that
+    // stale snapshot would bring the ghost back, and the additive contract
+    // would then keep it forever.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "UGONE",
+      displayName: "Alice Example",
+      contactId: "co-gone",
+      channelId: "ch-gone",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    deleteContact("co-gone");
+    snapshot = {
+      ok: true,
+      contacts: [
+        gatewayContact({
+          id: "co-gone",
+          displayName: "Alice Example",
+          channels: [{ id: "ch-gone", type: "slack", address: "UGONE" }],
+        }),
+      ],
+    };
+
+    await runMirrorReconcile();
+
+    expect(contactRow("co-gone")).toBeNull();
+    expect(channelRow("slack", "UGONE")).toBeNull();
+  });
+
+  test("a failed snapshot pull heals nothing and throws nothing", async () => {
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: "U123",
+      displayName: "Alice Example",
+      contactId: "co-1",
+      channelId: "ch-1",
+      refreshDisplayName: true,
+      userFileOnCreate: null,
+      reassignConflictingChannels: false,
+    });
+    ipcCallPersistentMock.mockImplementationOnce(async () => {
+      throw new Error("gateway unreachable");
+    });
+
+    await runMirrorReconcile();
+
+    expect(channelRow("slack", "U123")?.contactId).toBe("co-1");
+  });
+});

package/src/contacts/contact-store.ts

@@ -9,6 +9,7 @@ import {
   contacts,
 } from "../persistence/schema/index.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+import { recordContactTombstone } from "./mirror-tombstones.js";
 import { notifyContactsChanged } from "./notify-contacts-changed.js";
 import type {
   AssistantContactMetadata,
@@ -256,6 +257,16 @@ export function upsertContact(params: {
    *  mirror to create faithful null-user_file stubs. `userFile` takes
    *  precedence when both are supplied. */
   userFileOnCreate?: string | null;
+  /** contactType to seed ONLY when inserting a new contact; ignored on update
+   *  (and on channel-identity adoption) so a guardian-curated classification
+   *  is never clobbered by an inbound seed. `contactType` takes precedence
+   *  when both are supplied. */
+  contactTypeOnCreate?: ContactType;
+  /** notes to seed ONLY when inserting a new contact; ignored on update (and
+   *  on channel-identity adoption) so guardian-authored notes are never
+   *  clobbered by an inbound seed. `notes` takes precedence when both are
+   *  supplied. */
+  notesOnCreate?: string | null;
   channels?: SyncChannelData[];
   /** When true, conflicting channels on other contacts are reassigned to this
    *  contact instead of being skipped. Used by invite redemption to bind a
@@ -317,8 +328,20 @@ export function upsertContact(params: {
     }
   }
 
-  // Try to find by channel canonical identity to avoid duplicates
-  if (!contactId && canonicalChannels && canonicalChannels.length > 0) {
+  // Try to find by channel canonical identity to avoid duplicates. This also
+  // covers an explicit-id CREATE (the id was not found above) when the caller
+  // did not opt into reassignment: syncChannels would skip a channel owned by
+  // another contact, so inserting the supplied id would mint a channel-less
+  // duplicate of that contact. Adopting the existing owner instead keeps one
+  // contact per channel identity; the supplied id is dropped, and the
+  // *OnCreate record fields never apply here. Reassigning callers (invite
+  // binding, the guardian bootstrap mirror) skip this and keep their
+  // bind-to-target semantics.
+  if (
+    canonicalChannels &&
+    canonicalChannels.length > 0 &&
+    (!contactId || !params.reassignConflictingChannels)
+  ) {
     for (const ch of canonicalChannels) {
       const existingChannel = findConflictingChannel(db, ch.type, ch.address);
 
@@ -362,8 +385,8 @@ export function upsertContact(params: {
     .values({
       id: contactId,
       displayName: params.displayName,
-      notes: params.notes ?? null,
-      contactType: params.contactType ?? "human",
+      notes: params.notes ?? params.notesOnCreate ?? null,
+      contactType: params.contactType ?? params.contactTypeOnCreate ?? "human",
       userFile: resolvedUserFile,
       createdAt: now,
       updatedAt: now,
@@ -390,6 +413,9 @@ export function upsertContact(params: {
  */
 export function deleteContact(id: string): void {
   getDb().delete(contacts).where(eq(contacts.id, id)).run();
+  // The mirror reconciler must not resurrect this id from a gateway snapshot
+  // pulled before the delete.
+  recordContactTombstone(id);
   notifyContactsChanged();
 }
 
@@ -482,6 +508,16 @@ function syncChannels(
 
     if (existing) {
       const updateSet: Record<string, unknown> = {};
+      // Adopt a caller-supplied (gateway-minted) id onto a row still keyed
+      // by a divergent legacy id: the byId lookup above missed, so the id is
+      // free, and aligning it converges the two stores' keys (id-keyed
+      // gateway read-backs and client PATCHes then resolve directly).
+      // Nothing daemon-side persists a mirror channel id elsewhere, and
+      // readers holding the old id already fall back to the (type, address)
+      // logical key, so the swap only removes divergence.
+      if (ch.id && ch.id !== existing.id) {
+        updateSet.id = ch.id;
+      }
       // Self-heal legacy lowercased addresses to canonical form.
       if (existing.address !== ch.address) {
         updateSet.address = ch.address;
@@ -514,6 +550,12 @@ function syncChannels(
           contactId,
           updatedAt: now,
         };
+        // Adopt the caller-supplied (gateway-minted) id in the same write:
+        // the byId lookup above missed, so the id is free (same rationale as
+        // the same-contact adopt branch).
+        if (ch.id && ch.id !== conflicting.id) {
+          reassignSet.id = ch.id;
+        }
         if (ch.externalChatId !== undefined) {
           reassignSet.externalChatId = ch.externalChatId;
         }
@@ -773,6 +815,7 @@ export function mergeContactMirror(params: {
 
     // Delete the donor (cascade removes remaining duplicate channels).
     tx.delete(contacts).where(eq(contacts.id, params.mergeContactId)).run();
+    recordContactTombstone(params.mergeContactId);
     return true;
   });
 

package/src/contacts/contacts-write.ts

@@ -82,8 +82,11 @@ export function upsertContactChannel(params: {
   upsertContact({
     id: params.contactId,
     displayName,
-    contactType: params.contactType,
-    notes: params.notes,
+    // Classification and notes are create-only on this path (see the param
+    // docs above): applying them on update or on channel-identity adoption
+    // would let an inbound seed clobber guardian-authored record fields.
+    contactTypeOnCreate: params.contactType,
+    notesOnCreate: params.notes,
     userFileOnCreate: params.userFileOnCreate,
     channels: [
       {

package/src/contacts/mirror-reconciler.ts

@@ -0,0 +1,210 @@
+/**
+ * Pull-based identity reconciliation of the assistant contact mirror against
+ * the gateway DB (the source of truth for contact identity and channel
+ * ownership).
+ *
+ * The gateway's per-write mirror ops are best-effort: a failed or lost op
+ * leaves the mirror missing a row, or holding a channel under the wrong
+ * contact, until something happens to write that identity again. This module
+ * converges the drift instead: on the debounced `contacts_changed` signal it
+ * pulls the gateway's identity snapshot and heals the mirror toward it.
+ *
+ * Additive-corrective ONLY, because the mirror holds data the gateway cannot
+ * reconstruct:
+ *
+ * - It never deletes a mirror row. Mirror-only contacts and channels are
+ *   legitimate (a2a peers are written daemon-side only), and absence from
+ *   the gateway is indistinguishable from "the gateway never had it".
+ *   Delete propagation stays on the explicit delete ops.
+ * - It never touches assistant-authored fields (notes, contactType,
+ *   userFile) or an existing contact's displayName (the mirror name tracks
+ *   the live platform profile, not the gateway's curated name).
+ *
+ * Convergence is a fixed point: a pass only writes rows that diverge from
+ * the snapshot, so the follow-up pass its own writes trigger (every mirror
+ * write broadcasts `contacts_changed`) finds nothing to do and stops.
+ *
+ * TRANSITIONAL: this module exists only while the assistant DB keeps its own
+ * copy of identity columns. When identity reads move to the gateway
+ * wholesale, the mirror's identity columns and this reconciler go with them;
+ * do not grow it into a general sync framework.
+ */
+
+import { ContactsIdentitySnapshotIpcResponseSchema } from "@vellumai/gateway-client/gateway-ipc-contracts";
+
+import { getDbMigrationReadiness } from "../daemon/daemon-readiness.js";
+import { ipcCallPersistent } from "../ipc/gateway-client.js";
+import { getDb } from "../persistence/db-connection.js";
+import { contactChannels, contacts } from "../persistence/schema/index.js";
+import { getLogger } from "../util/logger.js";
+import { upsertContact } from "./contact-store.js";
+import { upsertContactChannel } from "./contacts-write.js";
+import { isContactTombstoned } from "./mirror-tombstones.js";
+
+const log = getLogger("mirror-reconciler");
+
+/**
+ * Collapse bursts of contacts_changed into one pull. Every inbound message
+ * from a known sender refreshes its channel row and notifies, so under
+ * continuous traffic this is the steady-state floor between snapshot pulls;
+ * healing latency is deliberately loose (the next quiet moment is fine).
+ */
+const DEBOUNCE_MS = 15_000;
+
+let timer: ReturnType<typeof setTimeout> | null = null;
+let running = false;
+let rerunRequested = false;
+
+/**
+ * Ask for a reconcile pass soon. Called (via dynamic import) from
+ * `notifyContactsChanged`, so every contact write, gateway-emitted or
+ * daemon-local, requests convergence. Coalesces bursts; a request landing
+ * while a pass is running (including the pass's own writes re-notifying)
+ * runs one follow-up pass after it, whose no-op result ends the cycle.
+ */
+export function scheduleMirrorReconcile(): void {
+  if (running) {
+    rerunRequested = true;
+    return;
+  }
+  if (timer) {
+    return;
+  }
+  timer = setTimeout(() => {
+    timer = null;
+    void runMirrorReconcile();
+  }, DEBOUNCE_MS);
+  // A pending debounce must never hold the process open (daemon shutdown,
+  // test teardown); a lost pass is re-requested by the next contact write.
+  timer.unref?.();
+}
+
+/**
+ * Key channels by (type, lower(address)), matching the gateway's
+ * UNIQUE(type, address) NOCASE collation. The NUL delimiter cannot appear in
+ * either field, so keys never collide.
+ */
+function channelKey(type: string, address: string): string {
+  return `${type}\u0000${address.toLowerCase()}`;
+}
+
+/**
+ * One reconcile pass: pull the gateway identity snapshot and heal every
+ * diverging mirror row through the identity-mirror primitives (which own the
+ * conflict semantics: gateway ids adopted on create, ownership reassigned to
+ * the gateway's contact, curated fields preserved). Best-effort: errors are
+ * logged, never thrown.
+ */
+export async function runMirrorReconcile(): Promise<void> {
+  if (running) {
+    rerunRequested = true;
+    return;
+  }
+  if (!getDbMigrationReadiness().ready) {
+    return;
+  }
+  running = true;
+  try {
+    const result = await ipcCallPersistent("contacts_identity_snapshot", {});
+    const snapshot = ContactsIdentitySnapshotIpcResponseSchema.parse(result);
+
+    const db = getDb();
+    const localContactIds = new Set(
+      db
+        .select({ id: contacts.id })
+        .from(contacts)
+        .all()
+        .map((r) => r.id),
+    );
+    const localByTypeAddress = new Map(
+      db
+        .select({
+          id: contactChannels.id,
+          contactId: contactChannels.contactId,
+          type: contactChannels.type,
+          address: contactChannels.address,
+          externalChatId: contactChannels.externalChatId,
+          isPrimary: contactChannels.isPrimary,
+        })
+        .from(contactChannels)
+        .all()
+        .map((row) => [channelKey(row.type, row.address), row]),
+    );
+
+    let healed = 0;
+    for (const contact of snapshot.contacts) {
+      // A contact deleted (or merged away) after this snapshot was pulled
+      // must not be resurrected from it; the additive contract would keep
+      // the ghost forever.
+      if (isContactTombstoned(contact.id)) {
+        continue;
+      }
+      if (contact.channels.length === 0) {
+        // A channel-less gateway contact (a guardian-authored record) whose
+        // mirror row is missing: recreate the identity stub.
+        if (!localContactIds.has(contact.id)) {
+          upsertContact({
+            id: contact.id,
+            displayName: contact.displayName,
+            userFileOnCreate: null,
+          });
+          healed += 1;
+        }
+        continue;
+      }
+
+      for (const channel of contact.channels) {
+        const local = localByTypeAddress.get(
+          channelKey(channel.type, channel.address),
+        );
+        // A gateway-null externalChatId means the delivery chat id was
+        // never learned (clearing one is off the upsert contract), so the
+        // mirror's value is the richer of the two and is not divergence. A
+        // divergent channel id IS: the heal adopts the gateway id (see
+        // syncChannels), so id-keyed read-backs and client PATCHes resolve
+        // directly instead of through the logical-key fallback forever.
+        const diverges =
+          !local ||
+          local.id !== channel.id ||
+          local.contactId !== contact.id ||
+          (channel.externalChatId != null &&
+            local.externalChatId !== channel.externalChatId) ||
+          local.isPrimary !== channel.isPrimary;
+        if (!diverges) {
+          continue;
+        }
+        // The identity-mirror primitive adopts the gateway ids on create,
+        // reassigns a divergent owner (the gateway owns channel ownership),
+        // and preserves an existing contact's curated name and record fields.
+        upsertContactChannel({
+          sourceChannel: channel.type,
+          externalUserId: channel.address,
+          externalChatId: channel.externalChatId ?? undefined,
+          displayName: contact.displayName,
+          contactId: contact.id,
+          channelId: channel.id,
+          refreshDisplayName: false,
+          reassignConflictingChannels: true,
+          isPrimary: channel.isPrimary,
+          userFileOnCreate: null,
+        });
+        healed += 1;
+      }
+    }
+
+    if (healed > 0) {
+      log.info(
+        { healed },
+        "mirror reconciler converged identity rows onto the gateway snapshot",
+      );
+    }
+  } catch (err) {
+    log.warn({ err }, "mirror reconcile failed (best-effort)");
+  } finally {
+    running = false;
+    if (rerunRequested) {
+      rerunRequested = false;
+      scheduleMirrorReconcile();
+    }
+  }
+}