@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/runtime/AGENTS.md

@@ -168,6 +168,41 @@ Identifiers and plumbing notes:
 - Guardian request records live in the gateway-owned `guardian_requests` table (and their `guardian_request_deliveries`); the daemon reads/writes them through the `channels/gateway-guardian-requests.ts` client.
 - Legacy in-turn interception (`routes/guardian-approval-interception.ts` + the approval prompt watcher) still serves a guardian's own tool-approval prompts mid-turn, resolving via `conversation.handleConfirmationResponse(requestId, decision)`. It is a legacy rail — the reply router runs first; converge new work on the pipeline.
 
+### Message metadata vocabulary
+
+Several differently-scoped things are called metadata on the channel path, and
+they nest, so a name that fits two of them reads as one concept. Counterpart to
+the gateway's Channel Identity Vocabulary, which covers the wire side.
+
+- **`sourceMetadata`** describes an inbound event in flight on the gateway to
+  daemon wire (`SourceMetadataSchema`, `packages/gateway-client`): provider
+  ids, trust verdict, admission policy. It is also persisted verbatim on the
+  stored inbound payload, because the retry sweep replays that payload and has
+  to reconstruct the same turn (`channel-retry-sweep.ts`).
+- **`messages.metadata`** is the stored envelope on a row. Everything below is
+  a key inside it. `messageMetadataSchema` (`persistence/conversation-crud.ts`)
+  describes its shared keys; it is parsed where a reader needs them, not
+  enforced on every write.
+- **`buildChannelMetadata`** (`routes/channel-metadata.ts`) builds the turn's
+  portion of that envelope: provenance, `userMessageChannel`, interfaces,
+  attachments. Callers spread it and add channel-specific keys alongside, so it
+  is a producer of the envelope, never a key within it.
+- **`slackMeta`** is the per-row key describing what a row is in its Slack
+  conversation: `channelTs` for the row's own id, `threadTs` for its thread,
+  `reaction.targetChannelTs` for the message a reaction was attached to, plus
+  Slack's own file markers and timezone labels. Every channel-path reader goes
+  through it today.
+- **`providerMeta`** is the channel-neutral counterpart of that key
+  (`messaging/provider-message-metadata.ts`): `conversationExternalId`,
+  `messageId`, `threadId`, `actorExternalId`, `eventKind` and
+  `reaction.targetMessageId`, deliberately the same vocabulary the inbound
+  wire uses in `InboundEventBase`, so a channel that can describe itself at
+  ingress can describe its stored rows without a translation of its own.
+  Writable by any channel, including one this repo has no code for. `readProviderMetadata` reads it and maps `slackMeta` onto it.
+  **Nothing writes or reads it yet**; it is the home a new channel should use
+  rather than inventing a sixth key, and existing readers move onto it as
+  channels adopt it.
+
 ### Channel verification: gateway-owned
 
 Verification SESSION state (sessions, secrets, rate limits, validate+consume) AND the channel-verified OUTCOME (status / verifiedAt / verifiedVia) are both gateway-owned. The gateway holds the `channel_verification_sessions` + `channel_guardian_rate_limits` tables (`gateway/src/db/session-store.ts`) and mints all secrets in `gateway/src/verification/session-service.ts`; the daemon holds no session or rate-limit state (its legacy tables were dropped by gateway data migration m0014).

package/src/runtime/__tests__/runtime-http-port-collision.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { emitDaemonError } from "../../daemon/startup-error.js";
+import {
+  startRuntimeHttpServer,
+  stopRuntimeHttpServer,
+} from "../http-server.js";
+
+/**
+ * The daemon binds two client-facing transports. An occupied runtime HTTP port
+ * must abort startup the same way an occupied IPC socket does, so the daemon
+ * can never answer IPC (reading healthy to `vellum ps` and platform status)
+ * while the gateway proxies /v1/* to a foreign listener.
+ */
+describe("runtime HTTP port collision", () => {
+  const originalPort = process.env.RUNTIME_HTTP_PORT;
+
+  afterEach(async () => {
+    await stopRuntimeHttpServer();
+    if (originalPort === undefined) {
+      delete process.env.RUNTIME_HTTP_PORT;
+    } else {
+      process.env.RUNTIME_HTTP_PORT = originalPort;
+    }
+  });
+
+  test("aborts startup when a foreign process holds the runtime HTTP port", async () => {
+    /**
+     * Tests that a runtime HTTP bind collision fails daemon startup instead of
+     * silently degrading to IPC-only operation.
+     */
+
+    // GIVEN a foreign process holding a port
+    const foreign = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("foreign"),
+    });
+
+    // AND the daemon configured to serve HTTP on that same port
+    process.env.RUNTIME_HTTP_PORT = String(foreign.port);
+
+    try {
+      // WHEN the daemon starts its runtime HTTP server
+      const err = await startRuntimeHttpServer().then(
+        () => null,
+        (e: unknown) => e,
+      );
+
+      // THEN startup fails rather than continuing without HTTP
+      expect(err).toBeInstanceOf(Error);
+
+      // AND the failure carries the address-collision code the daemon's
+      // startup-error categorization branches on
+      expect((err as NodeJS.ErrnoException).code).toBe("EADDRINUSE");
+
+      // AND the message names the occupied port and the env var that moves it
+      expect((err as Error).message).toContain(String(foreign.port));
+      expect((err as Error).message).toContain("RUNTIME_HTTP_PORT");
+    } finally {
+      foreign.stop(true);
+    }
+  });
+
+  test("reports a runtime HTTP port collision as PORT_IN_USE on stderr", async () => {
+    /**
+     * Tests that the bind failure reaches consumers that parse the daemon's
+     * structured startup-error line (e.g. the macOS app) as PORT_IN_USE.
+     */
+
+    // GIVEN a foreign process holding the daemon's runtime HTTP port
+    const foreign = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("foreign"),
+    });
+    process.env.RUNTIME_HTTP_PORT = String(foreign.port);
+
+    // AND stderr captured so the structured startup-error line is observable
+    const written: string[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      written.push(chunk.toString());
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      // WHEN the daemon's startup error handler reports the bind failure
+      const err = await startRuntimeHttpServer().then(
+        () => null,
+        (e: unknown) => e,
+      );
+      emitDaemonError(err);
+
+      // THEN the structured line categorizes the failure as PORT_IN_USE
+      const line = written.find((entry) => entry.includes("DAEMON_ERROR:"));
+      expect(line).toBeDefined();
+      const structured = JSON.parse(
+        (line as string).replace("DAEMON_ERROR:", "").trim(),
+      ) as Record<string, unknown>;
+      expect(structured.error).toBe("PORT_IN_USE");
+    } finally {
+      process.stderr.write = originalWrite;
+      foreign.stop(true);
+    }
+  });
+
+  test("binds and leaves the singleton serving when the port is free", async () => {
+    /**
+     * Tests that the collision guard does not turn ordinary startup into a
+     * failure: a free port still yields a listening HTTP server.
+     */
+
+    // GIVEN a free port for the runtime HTTP server
+    const probe = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("probe"),
+    });
+    const freePort = probe.port;
+    probe.stop(true);
+    process.env.RUNTIME_HTTP_PORT = String(freePort);
+
+    // WHEN the daemon starts its runtime HTTP server
+    await startRuntimeHttpServer();
+
+    // THEN the server answers its liveness probe
+    const response = await fetch(`http://127.0.0.1:${freePort}/healthz`);
+    expect(response.status).toBe(200);
+  });
+});

package/src/runtime/__tests__/web-presence.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Tests for the web presence policy.
+ *
+ * The invariant under test is fail-open: only a fresh report from a `web`
+ * client with `visible: true` and a matching `focusedConversationId` answers
+ * `true`. Every other shape (stale, hidden, mismatched conversation, no
+ * report, wrong interface, no clients, hub throw) answers `false` so the push
+ * is sent. Scoping the read to an actor principal narrows what counts as
+ * focus, so it can only ever turn a `true` into a `false`.
+ */
+
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+
+import {
+  clearHubClients,
+  registerHubClient,
+  type RegisterHubClientArgs,
+} from "../../__tests__/helpers/hub-clients.js";
+import { assistantEventHub } from "../assistant-event-hub.js";
+import {
+  isWebConversationFocused,
+  WEB_PRESENCE_STALE_AFTER_MS,
+} from "../web-presence.js";
+
+const CONVERSATION_ID = "conv-1";
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+/** A `now` far enough past every report to push all of them out of the window. */
+function afterStaleness(): Date {
+  return new Date(Date.now() + WEB_PRESENCE_STALE_AFTER_MS + 1_000);
+}
+
+function registerClient(
+  args: Omit<RegisterHubClientArgs, "hub" | "presence">,
+): void {
+  registerHubClient({ ...args, hub: assistantEventHub, interfaceId: "web" });
+}
+
+function reportWebPresence(
+  clientId: string,
+  report: { visible: boolean; focusedConversationId: string | null },
+): void {
+  assistantEventHub.setClientWebPresence(clientId, report);
+}
+
+function clientEntry(clientId: string) {
+  const client = assistantEventHub
+    .listClientsByInterface("web")
+    .find((entry) => entry.clientId === clientId);
+  if (!client) {
+    throw new Error(`missing test client ${clientId}`);
+  }
+  return client;
+}
+
+afterEach(() => {
+  clearHubClients(assistantEventHub);
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe("isWebConversationFocused", () => {
+  test("fresh visible report focused on the conversation is focused", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(true);
+  });
+
+  test("report older than the staleness bound is not focused", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(
+      isWebConversationFocused(CONVERSATION_ID, { now: afterStaleness() }),
+    ).toBe(false);
+  });
+
+  test("semantic report expires even while SSE transport stays alive", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    const now = new Date(Date.now() + WEB_PRESENCE_STALE_AFTER_MS + 1_000);
+    clientEntry("web-1").lastActiveAt = now;
+
+    expect(isWebConversationFocused(CONVERSATION_ID, { now })).toBe(false);
+  });
+
+  test("transport expiry is not focused even with a fresh semantic report", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    const now = new Date();
+    clientEntry("web-1").lastActiveAt = new Date(
+      now.getTime() - WEB_PRESENCE_STALE_AFTER_MS - 1_000,
+    );
+    clientEntry("web-1").webPresence!.reportedAt = now;
+
+    expect(isWebConversationFocused(CONVERSATION_ID, { now })).toBe(false);
+  });
+
+  test("hidden tab is not focused even on the matching conversation", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: false,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("visible tab focused on a different conversation is not focused", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: "conv-other",
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("visible tab with no focused conversation is not focused", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", { visible: true, focusedConversationId: null });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("client that never reported presence is not focused", () => {
+    registerClient({ clientId: "web-1" });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("a macos client's presence does not count as web focus", () => {
+    registerHubClient({
+      hub: assistantEventHub,
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    assistantEventHub.setClientWebPresence("mac-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("no connected clients is not focused", () => {
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+  });
+
+  test("a hub read that throws is not focused", () => {
+    const spy = spyOn(
+      assistantEventHub,
+      "listClientsByInterface",
+    ).mockImplementation(() => {
+      throw new Error("hub exploded");
+    });
+    try {
+      expect(isWebConversationFocused(CONVERSATION_ID)).toBe(false);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("one focused web client among several is enough", () => {
+    registerClient({ clientId: "web-1" });
+    registerClient({ clientId: "web-2" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: "conv-other",
+    });
+    reportWebPresence("web-2", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(true);
+  });
+});
+
+describe("isWebConversationFocused scoped to an actor principal", () => {
+  test("matching actor principal is focused", () => {
+    registerClient({ clientId: "web-1", actorPrincipalId: "actor-a" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(
+      isWebConversationFocused(CONVERSATION_ID, {
+        actorPrincipalId: "actor-a",
+      }),
+    ).toBe(true);
+  });
+
+  test("another actor's focused tab does not count", () => {
+    registerClient({ clientId: "web-1", actorPrincipalId: "actor-a" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(
+      isWebConversationFocused(CONVERSATION_ID, {
+        actorPrincipalId: "actor-b",
+      }),
+    ).toBe(false);
+  });
+
+  test("client with no principal does not match a supplied principal", () => {
+    registerClient({ clientId: "web-1" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(
+      isWebConversationFocused(CONVERSATION_ID, {
+        actorPrincipalId: "actor-a",
+      }),
+    ).toBe(false);
+  });
+
+  test("omitting the principal counts any focused web client", () => {
+    registerClient({ clientId: "web-1", actorPrincipalId: "actor-a" });
+    reportWebPresence("web-1", {
+      visible: true,
+      focusedConversationId: CONVERSATION_ID,
+    });
+    expect(isWebConversationFocused(CONVERSATION_ID)).toBe(true);
+  });
+});

package/src/runtime/assistant-event-hub.ts

@@ -109,6 +109,24 @@ export interface ClientPresence {
   reportedAt: Date;
 }
 
+/**
+ * Web tab visibility and conversation focus, as reported by a `web`-interface
+ * client (a browser tab or the Electron renderer). Distinct from
+ * {@link ClientPresence}: scoped to a single conversation rather than app-wide
+ * attendance, and reported by the shared web renderer rather than the macOS
+ * host-proxy bridge. See `runtime/web-presence.ts` for the read-side policy.
+ */
+export interface WebPresenceReport {
+  visible: boolean;
+  /** The conversation currently focused (chat composer on screen), or `null`. */
+  focusedConversationId: string | null;
+}
+
+export interface ClientWebPresence extends WebPresenceReport {
+  /** When the daemon last heard from the client. Drives staleness. */
+  reportedAt: Date;
+}
+
 interface ClientEntry extends BaseSubscriberEntry {
   type: "client";
   clientId: string;
@@ -130,6 +148,11 @@ interface ClientEntry extends BaseSubscriberEntry {
    * In-memory only, so consumers must fail open when it is absent.
    */
   presence?: ClientPresence;
+  /**
+   * Last web tab visibility/focus reported by this client, for clients that
+   * report it. In-memory only, so consumers must fail open when it is absent.
+   */
+  webPresence?: ClientWebPresence;
 }
 
 interface ProcessEntry extends BaseSubscriberEntry {
@@ -621,6 +644,21 @@ export class AssistantEventHub {
     return matched;
   }
 
+  /**
+   * Record the web tab visibility/focused-conversation reported by a client.
+   * `reportedAt` always advances. Returns true when at least one active
+   * client entry matched.
+   */
+  setClientWebPresence(clientId: string, report: WebPresenceReport): boolean {
+    const now = new Date();
+    let matched = false;
+    for (const entry of this.activeClientEntries(clientId)) {
+      entry.webPresence = { ...report, reportedAt: now };
+      matched = true;
+    }
+    return matched;
+  }
+
   /**
    * Force-disconnect a client by disposing all subscribers for the given
    * `clientId`. Returns the number of disposed entries.

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

@@ -1,6 +1,9 @@
+import type { MessageAudience } from "@vellumai/gateway-client";
+
 import { stripVellumLinks } from "../daemon/assistant-attachments.js";
 import type { RenderedHistoryContent } from "../daemon/handlers/shared.js";
 import { renderHistoryContent } from "../daemon/handlers/shared.js";
+import { editChannelMessage } from "../messaging/providers/index.js";
 import { readSlackMetadata } from "../messaging/providers/slack/message-metadata.js";
 import { getAttachmentMetadataForMessage } from "../persistence/attachments-store.js";
 import {
@@ -35,13 +38,11 @@ type DeliverRenderedReplyParams = {
    *  1-based count of segments delivered so far (including prior attempts). */
   onSegmentDelivered?: (deliveredCount: number) => void;
   /**
-   * When true, deliver via ephemeral messaging so only the target `user`
-   * sees the content. Ephemeral messages are fire-and-forget: they cannot
-   * be edited or deleted after posting.
+   * Restricts the reply to one reader. Absent means the whole room sees it.
+   * A restricted reply is fire-and-forget: it cannot be edited or deleted
+   * after posting.
    */
-  ephemeral?: boolean;
-  /** Channel-specific user ID — required when `ephemeral` is true. */
-  user?: string;
+  audience?: MessageAudience;
   /** When provided, the first segment will update the existing message
    *  identified by this ts instead of posting a new one (Slack-specific). */
   messageTs?: string;
@@ -140,8 +141,7 @@ export async function deliverRenderedReplyViaCallback(
     interSegmentDelayMs = INTER_SEGMENT_DELAY_MS,
     startFromSegment = 0,
     onSegmentDelivered,
-    ephemeral,
-    user,
+    audience,
     messageTs,
     onMessageTs,
   } = params;
@@ -167,9 +167,7 @@ export async function deliverRenderedReplyViaCallback(
           chatId,
           attachments: replyAttachments,
           assistantId,
-          ephemeral,
-          user,
-          messageTs,
+          audience,
         },
       );
       if (result.ts) {
@@ -187,9 +185,7 @@ export async function deliverRenderedReplyViaCallback(
           chatId,
           attachments: replyAttachments,
           assistantId,
-          ephemeral,
-          user,
-          messageTs,
+          audience,
         },
       );
       const deliveredTs = result.ts ?? messageTs;
@@ -210,21 +206,51 @@ export async function deliverRenderedReplyViaCallback(
     const isLastSegment = i === deliverableSegments.length - 1;
     const isFirstSegment = i === startFromSegment;
     const segmentText = deliverableSegments[i];
-    const result: ChannelDeliveryResult = await deliverChannelReply(
-      callbackUrl,
-      {
+    // Ask the channel to render richly; each channel's adapter decides how
+    // (Slack to Block Kit). Channels without rich rendering send plain text.
+    const segmentAttachments = isLastSegment ? replyAttachments : undefined;
+    const editTarget = isFirstSegment ? currentMessageTs : undefined;
+
+    let result: ChannelDeliveryResult;
+    if (editTarget) {
+      result = await editChannelMessage(callbackUrl, {
         chatId,
+        messageId: editTarget,
         text: segmentText,
-        // 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,
+      });
+      // An edit replaces the text of one message. Attachments are always new
+      // messages, so they still have to be posted alongside it.
+      //
+      // Failures here are not the reply failing. A transport rejects a total
+      // attachment failure only when there is no text to fall back on, and the
+      // edit above already delivered the text. Rethrowing would mark a reply
+      // undelivered that the reader can see, and have the sweep repost it.
+      if (segmentAttachments) {
+        try {
+          await deliverChannelReply(callbackUrl, {
+            chatId,
+            attachments: segmentAttachments,
+            assistantId,
+            audience,
+          });
+        } catch (err) {
+          log.warn(
+            { err, chatId },
+            "Attachments failed after an in-place edit; the edited text stands",
+          );
+        }
+      }
+    } else {
+      result = await deliverChannelReply(callbackUrl, {
+        chatId,
+        text: segmentText,
+        useBlocks: true,
+        attachments: segmentAttachments,
         assistantId,
-        ephemeral,
-        user,
-        messageTs: isFirstSegment ? currentMessageTs : undefined,
-      },
-    );
+        audience,
+      });
+    }
 
     if (result.ts) {
       currentMessageTs = result.ts;
@@ -251,10 +277,8 @@ export type DeliverReplyOptions = {
   sinceMessageId?: string;
   startFromSegment?: number;
   onSegmentDelivered?: (deliveredCount: number) => void;
-  /** Deliver as ephemeral (visible only to `user`). Fire-and-forget. */
-  ephemeral?: boolean;
-  /** Channel-specific user ID — required when `ephemeral` is true. */
-  user?: string;
+  /** Restricts the reply to one reader. Absent means the whole room. */
+  audience?: MessageAudience;
   /** Update an existing message instead of posting a new one. */
   messageTs?: string;
   /** Called with the ts of the delivered/updated message. */
@@ -384,8 +408,7 @@ async function deliverPersistedAssistantMessageViaCallback(
     assistantId,
     startFromSegment: options?.startFromSegment,
     onSegmentDelivered: options?.onSegmentDelivered,
-    ephemeral: options?.ephemeral,
-    user: options?.user,
+    audience: options?.audience,
     messageTs: options?.messageTs,
     onMessageTs: composedOnMessageTs,
   });

package/src/runtime/channel-retry-sweep.ts

@@ -3,6 +3,7 @@
  */
 
 import type { AssistantEvent } from "../api/index.js";
+import { audienceForReader } from "../channels/message-audience.js";
 import {
   type ChannelId,
   isChannelId,
@@ -333,10 +334,11 @@ export async function sweepFailedEvents(
           text: DISK_PRESSURE_REMOTE_BLOCK_REPLY,
           assistantId,
         };
-        if (sourceChannel === "slack" && requesterExternalUserId) {
-          replyPayload.ephemeral = true;
-          replyPayload.user = requesterExternalUserId;
-        }
+        replyPayload.audience = audienceForReader(
+          sourceChannel,
+          externalChatId,
+          requesterExternalUserId,
+        );
         try {
           await deliverChannelReply(replyCallbackUrl, replyPayload);
         } catch (err) {

package/src/runtime/effective-capabilities.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   canActOnPrivilegedDocuments,
+  canSeePersonalMemory,
   isArchiveBySenderAuthorized,
 } from "./effective-capabilities.js";
 
@@ -90,3 +91,21 @@ describe("isArchiveBySenderAuthorized", () => {
     ).toBe(false);
   });
 });
+
+describe("canSeePersonalMemory", () => {
+  test("only the guardian class sees personal memory", () => {
+    expect(canSeePersonalMemory({ trustClass: "guardian" })).toBe(true);
+    for (const trustClass of [
+      "trusted_contact",
+      "unverified_contact",
+      "unknown",
+    ]) {
+      expect(canSeePersonalMemory({ trustClass })).toBe(false);
+    }
+  });
+
+  test("an unrecognized or absent class fails closed", () => {
+    expect(canSeePersonalMemory({ trustClass: "non_guardian" })).toBe(false);
+    expect(canSeePersonalMemory({ trustClass: undefined })).toBe(false);
+  });
+});