@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/messaging/providers/slack/send.test.ts

@@ -1,9 +1,12 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
-type CallSlackApi = (
-  method: string,
-  body: Record<string, unknown>,
-) => Promise<Record<string, unknown>>;
+import type { KnownBlock } from "@slack/types";
+
+// Derive the mock signature from the real export so it cannot drift from the
+// production response shape (`SlackApiResponse`). A hand-rolled
+// `Promise<Record<string, unknown>>` here would let a test pass against a
+// response shape production never actually returns.
+type CallSlackApi = typeof import("./api.js").callSlackApi;
 
 const callSlackApiMock = mock<CallSlackApi>(async () => ({ ok: true }));
 
@@ -85,10 +88,16 @@ describe("sendSlackAssistantThreadStatus", () => {
 
 describe("sendSlackReply update path", () => {
   const messageTs = "1700000000.000100";
-  const blocks = [
+  const threadTs = "1700000000.000001";
+  const blocks: KnownBlock[] = [
     { type: "section", text: { type: "mrkdwn", text: "Final reply" } },
   ];
 
+  const postMessageCalls = () =>
+    callSlackApiMock.mock.calls.filter(
+      (call) => call[0] === "chat.postMessage",
+    );
+
   beforeEach(() => {
     callSlackApiMock.mockReset();
     callSlackApiMock.mockImplementation(async () => ({ ok: true }));
@@ -103,13 +112,13 @@ describe("sendSlackReply update path", () => {
 
     const result = await sendSlackReply("C123", "Final reply", {
       messageTs,
-      threadTs: "1700000000.000001",
+      threadTs,
       blocks,
     });
 
     expect(result).toEqual({ ok: true, ts: messageTs });
     // Two chat.update calls (with then without blocks); never chat.postMessage,
-    // so the placeholder is edited in place rather than duplicated.
+    // so the message is edited in place rather than duplicated.
     expect(callSlackApiMock).toHaveBeenCalledTimes(2);
     expect(callSlackApiMock).toHaveBeenNthCalledWith(1, "chat.update", {
       channel: "C123",
@@ -122,68 +131,107 @@ describe("sendSlackReply update path", () => {
       text: "Final reply",
       ts: messageTs,
     });
-    const postMessageCalls = callSlackApiMock.mock.calls.filter(
-      (call) => call[0] === "chat.postMessage",
-    );
-    expect(postMessageCalls).toHaveLength(0);
+    expect(postMessageCalls()).toHaveLength(0);
   });
 
-  test("falls back to chat.postMessage only after the no-block update retry also fails", async () => {
+  test("throws when the no-block update retry also fails, never posting a duplicate", async () => {
     callSlackApiMock
       .mockImplementationOnce(async () => {
         throw new SlackApiError("invalid_blocks");
       })
       .mockImplementationOnce(async () => {
         throw new SlackApiError("message_not_found");
-      })
-      .mockImplementationOnce(async () => ({
-        ok: true,
-        ts: "1700000000.000200",
-      }));
+      });
 
-    const result = await sendSlackReply("C123", "Final reply", {
-      messageTs,
-      threadTs: "1700000000.000001",
-      blocks,
-    });
+    await expect(
+      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+    ).rejects.toThrow();
 
-    expect(result).toEqual({ ok: true, ts: "1700000000.000200" });
-    expect(callSlackApiMock).toHaveBeenCalledTimes(3);
+    // Two in-place chat.update attempts (with then without blocks), then give
+    // up — it must not fall back to chat.postMessage and duplicate the message.
+    expect(callSlackApiMock).toHaveBeenCalledTimes(2);
     expect(callSlackApiMock.mock.calls[0]?.[0]).toBe("chat.update");
     expect(callSlackApiMock.mock.calls[1]?.[0]).toBe("chat.update");
-    // The post fallback drops the rejected blocks.
-    expect(callSlackApiMock).toHaveBeenNthCalledWith(3, "chat.postMessage", {
-      channel: "C123",
-      text: "Final reply",
-      thread_ts: "1700000000.000001",
+    expect(postMessageCalls()).toHaveLength(0);
+  });
+
+  test("throws on a transient chat.update failure instead of posting a duplicate", async () => {
+    callSlackApiMock.mockImplementationOnce(async () => {
+      throw new SlackApiError("internal_error");
     });
+
+    await expect(
+      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+    ).rejects.toThrow();
+
+    // A single failed chat.update, no chat.postMessage fallback: a transient
+    // failure must not spawn a "ghost" reply beside the message we failed to
+    // edit. Re-delivery is the delivery layer's job.
+    expect(callSlackApiMock).toHaveBeenCalledTimes(1);
+    expect(callSlackApiMock.mock.calls[0]?.[0]).toBe("chat.update");
+    expect(postMessageCalls()).toHaveLength(0);
   });
 
-  test("non-invalid_blocks update failure still falls back to chat.postMessage", async () => {
+  test("throws when the edit target is gone rather than re-posting it", async () => {
+    // Even when the target message no longer exists, this function does not
+    // post a fresh one — re-delivery is owned by the delivery layer, which
+    // would otherwise double-post.
+    callSlackApiMock.mockImplementationOnce(async () => {
+      throw new SlackApiError("message_not_found");
+    });
+
+    await expect(
+      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+    ).rejects.toThrow();
+
+    expect(callSlackApiMock).toHaveBeenCalledTimes(1);
+    expect(callSlackApiMock.mock.calls[0]?.[0]).toBe("chat.update");
+    expect(postMessageCalls()).toHaveLength(0);
+  });
+});
+
+describe("sendSlackReply post path", () => {
+  const threadTs = "1700000000.000001";
+  const blocks: KnownBlock[] = [
+    { type: "section", text: { type: "mrkdwn", text: "Fresh reply" } },
+  ];
+
+  beforeEach(() => {
+    callSlackApiMock.mockReset();
+    callSlackApiMock.mockImplementation(async () => ({ ok: true }));
+  });
+
+  test("retries chat.postMessage without blocks on invalid_blocks", async () => {
     callSlackApiMock
       .mockImplementationOnce(async () => {
-        throw new SlackApiError("internal_error");
+        throw new SlackApiError("invalid_blocks");
       })
       .mockImplementationOnce(async () => ({
         ok: true,
         ts: "1700000000.000200",
       }));
 
-    const result = await sendSlackReply("C123", "Final reply", {
-      messageTs,
-      threadTs: "1700000000.000001",
+    const result = await sendSlackReply("C123", "Fresh reply", {
+      threadTs,
       blocks,
     });
 
     expect(result).toEqual({ ok: true, ts: "1700000000.000200" });
-    // One failed chat.update, then a single chat.postMessage (no extra retry).
+    // Two chat.postMessage calls (with then without blocks); never chat.update.
     expect(callSlackApiMock).toHaveBeenCalledTimes(2);
-    expect(callSlackApiMock.mock.calls[0]?.[0]).toBe("chat.update");
-    expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "chat.postMessage", {
+    expect(callSlackApiMock).toHaveBeenNthCalledWith(1, "chat.postMessage", {
       channel: "C123",
-      text: "Final reply",
-      thread_ts: "1700000000.000001",
+      text: "Fresh reply",
+      thread_ts: threadTs,
       blocks,
     });
+    expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "chat.postMessage", {
+      channel: "C123",
+      text: "Fresh reply",
+      thread_ts: threadTs,
+    });
+    expect(
+      callSlackApiMock.mock.calls.filter((call) => call[0] === "chat.update"),
+    ).toHaveLength(0);
   });
 });

package/src/messaging/providers/slack/send.ts

@@ -6,6 +6,7 @@
  * attachments by calling the Slack Web API directly via ./api.ts.
  */
 
+import type { Button, KnownBlock } from "@slack/types";
 import type { ApprovalUIMetadata } from "@vellumai/gateway-client";
 
 import { getAttachmentContent } from "../../../memory/attachments-store.js";
@@ -27,24 +28,22 @@ const log = getLogger("slack-send");
 const SLACK_MAX_ATTACHMENT_BYTES = 100 * 1024 * 1024;
 
 // ---------------------------------------------------------------------------
-// Approval Block Kit builder (mirrors gateway/src/slack/block-kit-builder.ts)
+// Approval Block Kit builder
 // ---------------------------------------------------------------------------
 
 function buildApprovalBlocks(
   message: string,
   approval: ApprovalUIMetadata,
-): unknown[] {
+): KnownBlock[] {
+  const buttons: Button[] = approval.actions.map((action) => ({
+    type: "button",
+    text: { type: "plain_text", text: action.label, emoji: true },
+    action_id: `apr:${approval.requestId}:${action.id}`,
+    value: `apr:${approval.requestId}:${action.id}`,
+  }));
   return [
     { type: "section", text: { type: "mrkdwn", text: message } },
-    {
-      type: "actions",
-      elements: approval.actions.map((action) => ({
-        type: "button",
-        text: { type: "plain_text", text: action.label, emoji: true },
-        action_id: `apr:${approval.requestId}:${action.id}`,
-        value: `apr:${approval.requestId}:${action.id}`,
-      })),
-    },
+    { type: "actions", elements: buttons },
     {
       type: "context",
       elements: [
@@ -63,10 +62,10 @@ function buildApprovalBlocks(
 
 function resolveBlocks(
   text: string | undefined,
-  providedBlocks: unknown[] | undefined,
+  providedBlocks: KnownBlock[] | undefined,
   approval: ApprovalUIMetadata | undefined,
   useBlocks: boolean | undefined,
-): unknown[] {
+): KnownBlock[] {
   if (Array.isArray(providedBlocks) && providedBlocks.length > 0) {
     return providedBlocks;
   }
@@ -110,7 +109,7 @@ async function uploadFileToSlack(
 
 export interface SlackSendOptions {
   threadTs?: string;
-  blocks?: unknown[];
+  blocks?: KnownBlock[];
   approval?: ApprovalUIMetadata;
   useBlocks?: boolean;
   ephemeral?: boolean;
@@ -121,11 +120,53 @@ export interface SlackSendOptions {
 export interface SlackSendResult {
   ok: boolean;
   ts?: string;
-  placeholderTs?: string;
+}
+
+/**
+ * Call a Slack message API once, retrying a single time without Block Kit
+ * blocks if Slack rejects the payload with `invalid_blocks`.
+ *
+ * `invalid_blocks` faults the Block Kit payload, not the target — the retry
+ * repeats the *same* operation (same `chat.update` ts, same `chat.postMessage`
+ * thread) without blocks, so it edits/posts in place rather than spawning a
+ * second message. Any other error propagates to the caller.
+ */
+async function sendWithBlockFallback(
+  method: string,
+  baseBody: Record<string, unknown>,
+  blocks: KnownBlock[],
+  options: { fallbackWithoutBlocks: boolean },
+): Promise<SlackSendResult> {
+  try {
+    const result = await callSlackApi(
+      method,
+      blocks.length > 0 ? { ...baseBody, blocks } : baseBody,
+    );
+    return { ok: true, ts: result.ts };
+  } catch (err) {
+    if (
+      options.fallbackWithoutBlocks &&
+      blocks.length > 0 &&
+      err instanceof SlackApiError &&
+      err.slackError === "invalid_blocks"
+    ) {
+      log.warn({ method }, "Slack rejected blocks; retrying without blocks");
+      const result = await callSlackApi(method, baseBody);
+      return { ok: true, ts: result.ts };
+    }
+    throw err;
+  }
 }
 
 /**
  * Send a Slack text message with optional Block Kit formatting.
+ *
+ * When `messageTs` is set this is strictly an in-place edit (`chat.update`),
+ * mirroring `editMessage()` in ./withdraw.ts: a failed edit throws and is
+ * never converted into a fresh `chat.postMessage`. Posting on failure would
+ * leave the original message beside a duplicate ("ghost") reply; re-delivery
+ * after a transient failure is the delivery layer's responsibility, not this
+ * function's.
  */
 export async function sendSlackReply(
   chatId: string,
@@ -139,107 +180,45 @@ export async function sendSlackReply(
     options?.useBlocks,
   );
 
-  const slackBody: Record<string, unknown> = {
-    channel: chatId,
-    text,
-  };
-  if (blocks.length > 0) slackBody.blocks = blocks;
-  if (options?.threadTs) slackBody.thread_ts = options.threadTs;
-
-  const isUpdate =
-    typeof options?.messageTs === "string" && options.messageTs.length > 0;
-
-  if (isUpdate) {
-    const updateBody: Record<string, unknown> = {
-      channel: chatId,
-      text,
-      ts: options!.messageTs,
-    };
-    if (blocks.length > 0) updateBody.blocks = blocks;
-
-    try {
-      const result = await callSlackApi("chat.update", updateBody);
-      log.info(
-        { chatId, messageTs: options!.messageTs },
-        "Slack message updated",
-      );
-      return { ok: true, ts: result.ts };
-    } catch (err) {
-      if (
-        err instanceof SlackApiError &&
-        err.slackError === "invalid_blocks" &&
-        Array.isArray(updateBody.blocks) &&
-        updateBody.blocks.length > 0
-      ) {
-        // `invalid_blocks` means Slack rejected the Block Kit payload, not the
-        // target message — the message still exists. Retry the update without
-        // blocks so it is edited in place. Posting a fresh message here would
-        // leave the original alongside a duplicate ("ghost") reply.
-        const retryBody: Record<string, unknown> = {
-          channel: chatId,
-          text,
-          ts: options!.messageTs,
-        };
-        try {
-          const retryResult = await callSlackApi("chat.update", retryBody);
-          log.info(
-            { chatId, messageTs: options!.messageTs },
-            "Slack message updated without blocks after invalid_blocks",
-          );
-          return { ok: true, ts: retryResult.ts };
-        } catch (retryErr) {
-          log.warn(
-            { err: retryErr, chatId, messageTs: options!.messageTs },
-            "Slack chat.update without blocks failed, falling back to chat.postMessage",
-          );
-          delete slackBody.blocks;
-        }
-      } else {
-        log.warn(
-          { err, chatId, messageTs: options!.messageTs },
-          "Slack chat.update failed, falling back to chat.postMessage",
-        );
-      }
-    }
+  const messageTs = options?.messageTs;
+  if (typeof messageTs === "string" && messageTs.length > 0) {
+    const result = await sendWithBlockFallback(
+      "chat.update",
+      { channel: chatId, text, ts: messageTs },
+      blocks,
+      { fallbackWithoutBlocks: true },
+    );
+    log.info({ chatId, messageTs }, "Slack message updated");
+    return result;
   }
 
+  const postBase: Record<string, unknown> = { channel: chatId, text };
+  if (options?.threadTs) postBase.thread_ts = options.threadTs;
+
   if (options?.ephemeral) {
     if (!options.user)
       throw new Error("user is required for ephemeral messages");
     const result = await callSlackApi("chat.postEphemeral", {
-      ...slackBody,
+      ...postBase,
+      ...(blocks.length > 0 ? { blocks } : {}),
       user: options.user,
     });
     return { ok: true, ts: result.ts };
   }
 
-  try {
-    const result = await callSlackApi("chat.postMessage", slackBody);
-    log.info(
-      { chatId, hasThreadTs: !!options?.threadTs },
-      "Slack message sent",
-    );
-    return { ok: true, ts: result.ts };
-  } catch (err) {
-    // Retry without blocks for invalid_blocks errors
-    if (
-      err instanceof SlackApiError &&
-      err.slackError === "invalid_blocks" &&
-      !options?.approval &&
-      !options?.ephemeral &&
-      Array.isArray(slackBody.blocks) &&
-      (slackBody.blocks as unknown[]).length > 0
-    ) {
-      log.warn(
-        { chatId },
-        "Retrying Slack delivery without blocks after invalid_blocks",
-      );
-      delete slackBody.blocks;
-      const result = await callSlackApi("chat.postMessage", slackBody);
-      return { ok: true, ts: result.ts };
-    }
-    throw err;
-  }
+  // Approval prompts carry their action buttons in `blocks`; dropping them on
+  // `invalid_blocks` would post a card with no way to respond, so only
+  // non-approval posts fall back to a block-free retry.
+  const result = await sendWithBlockFallback(
+    "chat.postMessage",
+    postBase,
+    blocks,
+    {
+      fallbackWithoutBlocks: !options?.approval,
+    },
+  );
+  log.info({ chatId, hasThreadTs: !!options?.threadTs }, "Slack message sent");
+  return result;
 }
 
 /**

package/src/notifications/README.md

@@ -5,7 +5,7 @@ Signal-driven notification architecture where producers emit free-form events an
 ## Lifecycle
 
 ```
-Producer → NotificationSignal → Candidate Generation → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
+Producer → NotificationSignal → Source-Active Gate → Candidate Generation → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
                                                               ↑                                                            ↓
                                                       Preference Summary                                    notification_conversation_created SSE event
                                                       Conversation Candidates                               (creation-only — not emitted on reuse)
@@ -15,6 +15,8 @@ Producer → NotificationSignal → Candidate Generation → Decision Engine (LL
 
 A producer calls `emitNotificationSignal()` with a free-form event name, attention hints (urgency, requiresAction, deadlineAt), and a context payload. The signal is persisted as a `notification_events` row.
 
+Immediately after persistence, a **source-active pre-gate** runs (`checkSourceActiveSuppression`): when `visibleInSourceNow` is set — a hard, signal-only invariant the decision engine cannot override — the signal is suppressed and short-circuits here, before candidate generation and the LLM decision. This keeps an always-suppressed signal (e.g. trusted-contact `verification_sent`) from spending an LLM inference whose result would be discarded. The `notification_events` row is still written for the audit trail.
+
 ### 2. Candidate Generation
 
 Before the decision engine runs, the system builds a **conversation candidate set** per channel (`conversation-candidates.ts`). This is a compact snapshot of recent notification-sourced conversations that the decision engine can choose to reuse instead of starting a new conversation.
@@ -58,12 +60,14 @@ Hard invariants that the LLM cannot override:
 - **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them.
 - **Access-request instruction enforcement** — `enforceAccessRequestInstructions()` validates that `ingress.access_request` copy contains: (1) the request-code approve/reject directive, (2) the exact "open invite flow" phrase. If any required element is missing, the full deterministic contract text is appended. This prevents model-generated copy from dropping security-critical action directives.
 
-**Pre-send gate checks** (`deterministic-checks.ts`):
+**Pre-send gate checks** (`deterministic-checks.ts`) — these all depend on the decision, so they run here, after it:
 
 - **Schema validity** -- fail-closed if the decision is malformed
-- **Source-active suppression** -- if the user is already viewing the source context, suppress
 - **Channel availability** -- at least one selected channel must be connected
 - **Deduplication** -- same `dedupeKey` within the dedupe window (1 hour default) is suppressed
+- **Rendered copy quality** -- fail-closed on empty copy or a fallback leak (body equal to the raw event name)
+
+Source-active suppression depends only on the signal, so it runs earlier — as the pre-decision gate in `emit-signal.ts` (see step 1), not as a pre-send check here.
 
 ### 5. Dispatch
 
@@ -409,13 +413,13 @@ All disambiguation messages are generated through `composeGuardianActionMessageG
 | File                            | Purpose                                                                                                    |
 | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `../channels/config.ts`         | Channel policy registry -- single source of truth for per-channel notification behavior                    |
-| `emit-signal.ts`                | Single entry point for producers; orchestrates the full pipeline                                           |
+| `emit-signal.ts`                | Single entry point for producers; orchestrates the full pipeline; runs the source-active pre-decision gate |
 | `signal.ts`                     | `NotificationSignal` and `AttentionHints` type definitions                                                 |
 | `types.ts`                      | Channel adapter interfaces, delivery types, decision output contract, `ConversationAction` union           |
 | `conversation-candidates.ts`    | Builds per-channel candidate set of recent notification conversations for the decision engine              |
 | `conversation-pairing.ts`       | Materializes conversation + message per delivery based on channel strategy                                 |
 | `decision-engine.ts`            | LLM-based routing with forced tool_choice; deterministic fallback                                          |
-| `deterministic-checks.ts`       | Pre-send gate checks (dedupe, source-active, channel availability)                                         |
+| `deterministic-checks.ts`       | Post-decision pre-send gate checks (schema, dedupe, channel availability, copy quality)                    |
 | `runtime-dispatch.ts`           | Dispatch gating (no-op decisions, empty channels)                                                          |
 | `broadcaster.ts`                | Fan-out to channel adapters with delivery audit trail; emits `notification_conversation_created` SSE event |
 | `copy-composer.ts`              | Template-based fallback notification copy when LLM copy is unavailable                                     |

package/src/notifications/__tests__/deterministic-checks.test.ts

@@ -20,13 +20,14 @@ import { getDb } from "../../memory/db-connection.js";
 import { initializeDb } from "../../memory/db-init.js";
 import { notificationEvents } from "../../memory/schema.js";
 import {
+  checkSourceActiveSuppression,
   type DeterministicCheckContext,
   runDeterministicChecks,
 } from "../deterministic-checks.js";
 import type { NotificationSignal } from "../signal.js";
 import type { NotificationDecision } from "../types.js";
 
-initializeDb();
+await initializeDb();
 
 beforeEach(() => {
   getDb().delete(notificationEvents).run();
@@ -284,3 +285,44 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
     expect(result.reason).toContain("fallback leak");
   });
 });
+
+describe("checkSourceActiveSuppression (pre-decision gate)", () => {
+  test("fails when visibleInSourceNow is set", () => {
+    const result = checkSourceActiveSuppression(
+      makeSignal({
+        attentionHints: {
+          requiresAction: false,
+          urgency: "low",
+          isAsyncBackground: true,
+          visibleInSourceNow: true,
+        },
+      }),
+    );
+    expect(result.passed).toBe(false);
+    expect(result.reason).toContain("Source-active suppression");
+  });
+
+  test("passes when visibleInSourceNow is false", () => {
+    expect(checkSourceActiveSuppression(makeSignal()).passed).toBe(true);
+  });
+
+  test("runDeterministicChecks does not suppress source-active signals (handled by the pre-decision gate)", async () => {
+    // Source-active suppression is enforced by the pre-decision gate in
+    // emitNotificationSignal, not by this stage. A source-active signal
+    // evaluated here therefore passes — this stage only validates the decision.
+    const signal = makeSignal({
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: true,
+        visibleInSourceNow: true,
+      },
+    });
+    const result = await runDeterministicChecks(
+      signal,
+      makeDecision(),
+      context,
+    );
+    expect(result.passed).toBe(true);
+  });
+});

package/src/notifications/adapters/slack.ts

@@ -12,6 +12,8 @@
  * https://docs.slack.dev/reference/block-kit/blocks/card-block
  */
 
+import type { Button, CardBlock, ContextBlock, KnownBlock } from "@slack/types";
+
 import { sendSlackReply } from "../../messaging/providers/slack/send.js";
 import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
 import { getLogger } from "../../util/logger.js";
@@ -39,7 +41,7 @@ const log = getLogger("notif-adapter-slack");
 // ---------------------------------------------------------------------------
 
 /** Build action buttons for a Slack Card block from approval metadata. */
-function buildCardActions(approval: ApprovalUIMetadata): unknown[] {
+function buildCardActions(approval: ApprovalUIMetadata): Button[] {
   return approval.actions.map((action) => ({
     type: "button",
     text: { type: "plain_text", text: action.label, emoji: true },
@@ -80,7 +82,7 @@ function buildAccessRequestBody(view: AccessRequestCardView): string {
 /** Source-channel context block with Slack permalink when available. */
 function buildSourceContextBlock(
   view: AccessRequestCardView,
-): unknown | undefined {
+): ContextBlock | undefined {
   if (view.sourceChannel !== "slack" || !view.conversationExternalId) {
     return undefined;
   }
@@ -107,7 +109,7 @@ function buildSourceContextBlock(
 /** Stable requester identifier context block (external ID when it adds info). */
 function buildRequesterIdBlock(
   view: AccessRequestCardView,
-): unknown | undefined {
+): ContextBlock | undefined {
   const safeExternalId = view.externalId;
   if (!safeExternalId) return undefined;
 
@@ -134,10 +136,10 @@ function buildRequesterIdBlock(
  */
 function buildAccessRequestCardBlocks(
   payload: ChannelDeliveryPayload,
-): unknown[] {
+): KnownBlock[] {
   const approval = payload.approvalContext!;
   const view = buildAccessRequestCardView(payload.accessRequestContext!);
-  const blocks: unknown[] = [];
+  const blocks: KnownBlock[] = [];
 
   const subtitle = buildAccessRequestSubtitle(view);
   const body = buildAccessRequestBody(view);
@@ -147,7 +149,7 @@ function buildAccessRequestCardBlocks(
       ? truncate(view.warnings.map((w) => `:warning: ${w}`).join(" · "), 200)
       : undefined;
 
-  const card: Record<string, unknown> = {
+  const card: CardBlock = {
     type: "card",
     title: { type: "mrkdwn", text: "Access Request" },
     subtitle: { type: "mrkdwn", text: subtitle },
@@ -211,9 +213,9 @@ function buildAccessRequestCardBlocks(
 function buildToolApprovalCardBlocks(
   payload: ChannelDeliveryPayload,
   messageText: string,
-): unknown[] {
+): KnownBlock[] {
   const approval = payload.approvalContext!;
-  const blocks: unknown[] = [];
+  const blocks: KnownBlock[] = [];
 
   const details = approval.permissionDetails;
   const toolName = details?.toolName;
@@ -226,7 +228,7 @@ function buildToolApprovalCardBlocks(
   }
 
   const needsOverflow = messageText.length > 200;
-  const card: Record<string, unknown> = {
+  const card: CardBlock = {
     type: "card",
     title: {
       type: "mrkdwn",
@@ -266,7 +268,7 @@ function buildToolApprovalCardBlocks(
 export function buildApprovalNotificationBlocks(
   payload: ChannelDeliveryPayload,
   messageText: string,
-): unknown[] {
+): KnownBlock[] {
   if (
     payload.sourceEventName === "ingress.access_request" &&
     payload.accessRequestContext != null