@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

package/src/runtime/routes/workspace-routes.ts

@@ -46,14 +46,24 @@ const workspaceTreeEntrySchema = z.object({
 
 type TreeEntry = z.infer<typeof workspaceTreeEntrySchema>;
 
-// Total number of filesystem entries we're willing to traverse when computing
-// recursive directory sizes for a single tree listing. The budget is shared
-// across every directory in the response so a giant `repos/` checkout cannot
-// starve the request — once exhausted, remaining directories report `size:
-// null` (caller renders an unknown-size placeholder). 50k is generous for
-// typical workspaces (sounds, db, logs) while bailing fast on multi-repo
-// trees.
-const DIR_SIZE_TOTAL_ENTRY_BUDGET = 50_000;
+// Recursive directory sizing walks the filesystem synchronously, so it is
+// bounded by two caps that work together:
+//
+// - `DIR_SIZE_PER_DIR_ENTRY_BUDGET` caps a single directory. No one giant
+//   subtree (e.g. a `node_modules/` or `repos/` checkout) can consume the whole
+//   listing's budget and starve its siblings; only the oversized directory
+//   itself reports `size: null` (the caller renders an unknown-size
+//   placeholder) while every other folder still shows an accurate size.
+// - `DIR_SIZE_TOTAL_ENTRY_BUDGET` caps the listing as a whole, so a workspace
+//   with many large sibling directories still can't block the daemon event loop
+//   for an unbounded amount of time. Once it is exhausted, the remaining
+//   directories report `size: null`.
+//
+// Each directory is allotted `min(per-dir cap, remaining listing budget)`
+// entries, and whatever it actually consumes is deducted from the listing
+// budget.
+const DIR_SIZE_PER_DIR_ENTRY_BUDGET = 250_000;
+const DIR_SIZE_TOTAL_ENTRY_BUDGET = 1_000_000;
 
 interface DirSizeBudget {
   remaining: number;
@@ -61,13 +71,13 @@ interface DirSizeBudget {
 
 /**
  * Recursively sum the byte size of every regular file under `absPath`,
- * sharing a single entry budget across all directories in the same listing.
+ * traversing up to `budget.remaining` filesystem entries.
  *
  * Returns:
  * - the total size in bytes when the entire subtree was traversed within
  *   budget
- * - `null` if the shared budget was exhausted before completion (the caller
- *   surfaces that as an unknown size in the UI)
+ * - `null` if the budget was exhausted before completion (the caller surfaces
+ *   that as an unknown size in the UI)
  *
  * Symlinks are not followed. We rely on `withFileTypes` so we never `stat`
  * directories purely to discover their type.
@@ -108,6 +118,27 @@ function computeDirSize(absPath: string, budget: DirSizeBudget): number | null {
   return total;
 }
 
+/**
+ * Compute a directory's recursive size while drawing from a shared listing
+ * budget. The directory is allotted at most `DIR_SIZE_PER_DIR_ENTRY_BUDGET`
+ * entries — and never more than the listing has left — and whatever it consumes
+ * is deducted from `listingBudget` so the next sibling sees the reduced
+ * remainder. Returns `null` (unknown size) when the allotment is exhausted.
+ */
+function computeDirSizeWithinListing(
+  absPath: string,
+  listingBudget: DirSizeBudget,
+): number | null {
+  const allotment = Math.min(
+    DIR_SIZE_PER_DIR_ENTRY_BUDGET,
+    listingBudget.remaining,
+  );
+  const dirBudget: DirSizeBudget = { remaining: allotment };
+  const size = computeDirSize(absPath, dirBudget);
+  listingBudget.remaining -= allotment - dirBudget.remaining;
+  return size;
+}
+
 const SOUNDS_WORKSPACE_PATH = "data/sounds";
 
 function normaliseWorkspacePathForSync(path: string): string {
@@ -153,9 +184,11 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
     const dirents = readdirSync(resolved, { withFileTypes: true });
     const workspaceDir = getWorkspaceDir();
 
-    // Shared budget across every directory in this listing. When opted out,
-    // we never construct one, so directories report `size: null` as before.
-    const dirSizeBudget: DirSizeBudget | undefined = includeDirSizes
+    // Listing-wide budget, only constructed when sizes are requested. Each
+    // directory draws a per-directory allotment from it so one oversized
+    // subtree can't starve its siblings, while the shared remainder still caps
+    // total synchronous traversal for the whole listing.
+    const listingBudget: DirSizeBudget | undefined = includeDirSizes
       ? { remaining: DIR_SIZE_TOTAL_ENTRY_BUDGET }
       : undefined;
 
@@ -176,7 +209,9 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
       const relativePath = fullPath.slice(workspaceDir.length + 1);
 
       const dirSize =
-        isDir && dirSizeBudget ? computeDirSize(fullPath, dirSizeBudget) : null;
+        isDir && listingBudget
+          ? computeDirSizeWithinListing(fullPath, listingBudget)
+          : null;
 
       entries.push({
         name: entry.name,

package/src/runtime/services/conversation-serializer.ts

@@ -9,7 +9,7 @@
 
 import { parseChannelId } from "../../channels/types.js";
 import { getConfig } from "../../config/loader.js";
-import { findConversation } from "../../daemon/conversation-store.js";
+import { findConversation } from "../../daemon/conversation-registry.js";
 import { normalizeConversationType } from "../../daemon/message-types/shared.js";
 import {
   type AttentionState,

package/src/runtime/verification-outbound-actions.ts

@@ -2,7 +2,7 @@
  * Shared outbound verification action logic.
  *
  * These pure functions encapsulate the business logic for starting, resending,
- * and cancelling outbound verification flows (Telegram, voice, Slack).
+ * and cancelling outbound verification flows (Telegram, voice, Slack, email).
  * They return transport-agnostic result objects and are consumed by both the
  * message handler (config-channels.ts) and the HTTP route layer (channel-verification-routes.ts).
  */
@@ -26,6 +26,7 @@ import {
   updateSessionStatus,
 } from "./channel-verification-service.js";
 import {
+  composeVerificationEmail,
   composeVerificationSlack,
   composeVerificationTelegram,
   GUARDIAN_VERIFY_TEMPLATE_KEYS,
@@ -52,6 +53,8 @@ export const DESTINATION_RATE_WINDOW_MS = 3_600_000;
 /** Session TTL in seconds (matches challenge TTL of 10 minutes). */
 const SESSION_TTL_SECONDS = 600;
 
+const EMAIL_VERIFICATION_SUBJECT = "Vellum Assistant Guardian Verification";
+
 // ---------------------------------------------------------------------------
 // Telegram destination classification
 // ---------------------------------------------------------------------------
@@ -122,6 +125,8 @@ interface OutboundActionResult {
    *  reach the gateway.  The daemon HTTP route handler calls
    *  deliverVerificationSlack() after receiving this payload. */
   _pendingSlackDm?: { userId: string; text: string; assistantId: string };
+  /** Internal: email delivery payload for the caller to dispatch (same pattern as Slack). */
+  _pendingEmail?: { to: string; text: string; subject: string; assistantId: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -512,6 +517,80 @@ export function deliverVerificationSlack(
   deliverVerificationSlackAsync(userId, text, assistantId);
 }
 
+// ---------------------------------------------------------------------------
+// Email delivery helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Deliver a verification email via the platform email send API.
+ * Fire-and-forget wrapper for use in the daemon process (HTTP route handlers).
+ */
+export function deliverVerificationEmail(
+  to: string,
+  text: string,
+  subject: string,
+  _assistantId: string,
+): void {
+  (async () => {
+    try {
+      const { VellumPlatformClient } = await import(
+        "../platform/client.js"
+      );
+      const client = await VellumPlatformClient.create();
+      if (!client?.platformAssistantId) {
+        log.error("Cannot deliver verification email: platform client not configured");
+        return;
+      }
+
+      const listResponse = await client.fetch(
+        `/v1/assistants/${client.platformAssistantId}/email-addresses/`,
+      );
+      if (!listResponse.ok) {
+        log.error({ status: listResponse.status }, "Failed to list email addresses for verification");
+        return;
+      }
+      const listData = (await listResponse.json()) as {
+        results: { address: string }[];
+      };
+      const addresses = listData.results ?? [];
+      if (addresses.length === 0) {
+        log.error("No email address registered — cannot deliver verification email");
+        return;
+      }
+      const fromAddress = addresses[0].address;
+
+      const { markdownToEmailHtml } = await import(
+        "../email/html-renderer.js"
+      );
+      const html = markdownToEmailHtml(text);
+
+      const response = await client.fetch("/v1/runtime-proxy/email/send/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          to: [to],
+          from_address: fromAddress,
+          text,
+          subject,
+          html,
+        }),
+      });
+
+      if (response.ok) {
+        log.info({ to }, "Verification email delivered");
+      } else {
+        const respBody = await response.json().catch(() => ({}));
+        log.error(
+          { to, status: response.status, respBody },
+          "Failed to deliver verification email",
+        );
+      }
+    } catch (err) {
+      log.error({ err, to }, "Failed to deliver verification email");
+    }
+  })();
+}
+
 function startOutboundSlack(
   destination: string | undefined,
   assistantId: string,
@@ -644,13 +723,35 @@ function startOutboundEmail(
     verificationPurpose: "guardian",
   });
 
+  const emailBody = composeVerificationEmail(
+    GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST,
+    {
+      code: sessionResult.secret,
+      expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+    },
+  );
+
+  const now = Date.now();
+  const nextResendAt = now + RESEND_COOLDOWN_MS;
+  const sendCount = 1;
+
+  updateSessionDelivery(sessionResult.sessionId, now, sendCount, nextResendAt);
+
   return {
     success: true,
     verificationSessionId: sessionResult.sessionId,
     secret: sessionResult.secret,
     expiresAt: sessionResult.expiresAt,
+    nextResendAt,
+    sendCount,
     channel,
     originConversationId,
+    _pendingEmail: {
+      to: normalizedEmail,
+      text: emailBody,
+      subject: EMAIL_VERIFICATION_SUBJECT,
+      assistantId,
+    },
   };
 }
 
@@ -851,12 +952,56 @@ export function resendOutbound(
       originConversationId,
       _pendingSlackDm: { userId: destination, text: slackBody, assistantId },
     };
+  } else if (channel === "email") {
+    const newSession = createOutboundSession({
+      channel,
+      expectedExternalUserId: destination,
+      expectedChatId: destination,
+      identityBindingStatus: "bound",
+      destinationAddress: destination,
+      verificationPurpose: "guardian",
+    });
+
+    const emailBody = composeVerificationEmail(
+      GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND,
+      {
+        code: newSession.secret,
+        expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+      },
+    );
+
+    const now = Date.now();
+    const newSendCount = currentSendCount + 1;
+    const nextResendAt = now + RESEND_COOLDOWN_MS;
+
+    updateSessionDelivery(
+      newSession.sessionId,
+      now,
+      newSendCount,
+      nextResendAt,
+    );
+
+    return {
+      success: true,
+      verificationSessionId: newSession.sessionId,
+      secret: newSession.secret,
+      nextResendAt,
+      sendCount: newSendCount,
+      channel,
+      originConversationId,
+      _pendingEmail: {
+        to: destination,
+        text: emailBody,
+        subject: EMAIL_VERIFICATION_SUBJECT,
+        assistantId,
+      },
+    };
   }
 
   return {
     success: false,
     error: "unsupported_channel",
-    message: `Resend is only supported for Telegram, phone, and Slack. Got: ${channel}`,
+    message: `Resend is only supported for Telegram, phone, Slack, and email. Got: ${channel}`,
     channel,
   };
 }

package/src/runtime/verification-templates.ts

@@ -1,5 +1,5 @@
 /**
- * Template-only copy for outbound guardian verification messages (Telegram, Slack, and voice).
+ * Template-only copy for outbound guardian verification messages (Telegram, Slack, email, and voice).
  *
  * All outbound verification messages are composed from these templates
  * to prevent free-form caller/user text injection. Only typed variables
@@ -26,6 +26,10 @@ export const GUARDIAN_VERIFY_TEMPLATE_KEYS = {
     "guardian_verify.slack.trusted_contact_challenge",
   /** Resend Slack DM verification for inbound trusted contact (includes the code). */
   SLACK_TRUSTED_CONTACT_RESEND: "guardian_verify.slack.trusted_contact_resend",
+  /** Initial outbound email verification prompt (includes the code). */
+  EMAIL_CHALLENGE_REQUEST: "guardian_verify.email.challenge_request",
+  /** Resend email verification prompt (includes the code). */
+  EMAIL_RESEND: "guardian_verify.email.resend",
   /** Outbound voice call intro prompt: asks guardian to enter verification code via keypad. */
   VOICE_CALL_INTRO: "guardian_verify.voice.call_intro",
   /** Voice retry prompt after an incorrect code entry. */
@@ -42,7 +46,7 @@ export const GUARDIAN_VERIFY_TEMPLATE_KEYS = {
   CHANNEL_BOOTSTRAP_BOUND: "guardian_verify.channel.bootstrap_bound",
 } as const;
 
-/** Template keys for Telegram/Slack text-based verification messages. */
+/** Template keys for Telegram/Slack/email text-based verification messages. */
 type TextVerifyTemplateKey =
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.ALREADY_VERIFIED
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.TELEGRAM_CHALLENGE_REQUEST
@@ -50,7 +54,9 @@ type TextVerifyTemplateKey =
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_CHALLENGE_REQUEST
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_RESEND
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_CHALLENGE
-  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND;
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND;
 
 /** Template keys for deterministic channel verification reply messages. */
 type ChannelVerifyReplyTemplateKey =
@@ -115,6 +121,14 @@ const templates: Record<
   [GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND]: (vars) => {
     return `Vellum assistant verification: your code is ${vars.code}. Reply with this code to verify your identity. It expires in ${vars.expiresInMinutes} minutes. (resent)`;
   },
+
+  [GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST]: (vars) => {
+    return `Vellum assistant guardian verification requested.\n\nYour verification code is: ${vars.code}\n\nReply to this email with only the 6-digit code above to complete verification. This code expires in ${vars.expiresInMinutes} minutes.`;
+  },
+
+  [GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND]: (vars) => {
+    return `Vellum assistant guardian verification requested.\n\nYour new verification code is: ${vars.code}\n\nReply to this email with only the 6-digit code above to complete verification. This code expires in ${vars.expiresInMinutes} minutes. (resent)`;
+  },
 };
 
 /**
@@ -129,6 +143,18 @@ export function composeVerificationSlack(
   return composer(vars);
 }
 
+/**
+ * Compose an outbound verification email from a template key and typed variables.
+ * Returns plain string content suitable for email delivery.
+ */
+export function composeVerificationEmail(
+  templateKey: TextVerifyTemplateKey,
+  vars: GuardianVerifyTemplateVars,
+): string {
+  const composer = templates[templateKey];
+  return composer(vars);
+}
+
 /**
  * Compose an outbound verification Telegram message from a template key and typed variables.
  * Returns plain string content suitable for Telegram delivery.

package/src/services/published-app-updater.ts

@@ -3,8 +3,15 @@
  */
 
 import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 
-import { getApp } from "../memory/app-store.js";
+import {
+  getApp,
+  getAppDirPath,
+  isMultifileApp,
+  resolveEffectiveAppHtml,
+} from "../memory/app-store.js";
 import {
   getActivePublishedPageByAppId,
   updatePublishedPage,
@@ -23,17 +30,32 @@ export async function updatePublishedAppDeployment(
     const publishedPage = getActivePublishedPageByAppId(appId);
     if (!publishedPage) return;
 
-    // 2. Load the app to get current HTML
+    // 2. Load the app and resolve its deployable HTML. For multifile apps the
+    // real content lives in dist/index.html (compiled from src/), not in
+    // htmlDefinition (which is "" for them) — using htmlDefinition directly
+    // would deploy a blank page.
     const app = getApp(appId);
-    if (!app || !app.htmlDefinition) {
-      log.warn({ appId }, "Published app not found or has no HTML");
+    if (!app) {
+      log.warn({ appId }, "Published app not found");
       return;
     }
 
+    // Skip rather than deploy the compile-failure fallback when a multifile
+    // app has no compiled output (e.g. a concurrent compile failed); a later
+    // successful compile re-triggers this path.
+    if (
+      isMultifileApp(app) &&
+      !existsSync(join(getAppDirPath(app.id), "dist", "index.html"))
+    ) {
+      log.warn({ appId }, "Skipping auto-redeploy: compiled output missing");
+      return;
+    }
+
+    const html = resolveEffectiveAppHtml(app);
+    if (!html) return;
+
     // 3. Hash the current HTML and check if it changed
-    const newHash = createHash("sha256")
-      .update(app.htmlDefinition)
-      .digest("hex");
+    const newHash = createHash("sha256").update(html).digest("hex");
     if (newHash === publishedPage.htmlHash) return; // No change
 
     // 4. Get Vercel token — don't prompt, just skip if unavailable
@@ -46,7 +68,7 @@ export async function updatePublishedAppDeployment(
       execute: async (token) => {
         // 5. Deploy updated HTML using the same project slug
         const result = await deployHtmlToVercel({
-          html: app.htmlDefinition,
+          html,
           name: slug,
           token,
         });

package/src/signals/cancel.ts

@@ -11,10 +11,8 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getIsContainerized } from "../config/env-registry.js";
-import {
-  findConversation,
-  touchConversation,
-} from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
+import { touchConversation } from "../daemon/conversation-store.js";
 import { getSubagentManager } from "../subagent/index.js";
 import { createAbortReason } from "../util/abort-reasons.js";
 import { getLogger } from "../util/logger.js";

package/src/subagent/manager.ts

@@ -13,7 +13,11 @@ import { v4 as uuid } from "uuid";
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import { getConfig } from "../config/loader.js";
 import { Conversation } from "../daemon/conversation.js";
-import { findConversation } from "../daemon/conversation-store.js";
+import {
+  findConversation,
+  removeSubagentConversation,
+  setSubagentConversation,
+} from "../daemon/conversation-registry.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import { wrapWithCallSiteRouting } from "../providers/call-site-routing.js";
@@ -294,6 +298,10 @@ export class SubagentManager {
     // This ensures interactive prompts (host attachment reads) fail fast.
     conversation.updateClient(wrappedSendToClient, true);
     conversation.setIsSubagent(true);
+    // Subagents are created as background conversations (see the
+    // `bootstrapConversation` call above) and never call `loadFromDb`, so cache
+    // the type on the live conversation directly for the runtime-assembly path.
+    conversation.conversationType = "background";
 
     // Subagents execute as background child conversations, but their tool
     // permissions must still be scoped to the actor that spawned them. Without
@@ -334,6 +342,10 @@ export class SubagentManager {
 
     managed.conversation = conversation;
     this.subagents.set(subagentId, managed);
+    // Index the live conversation so the per-conversation injectors (workspace
+    // context, disk-pressure warning) can resolve it by id; subagents are not
+    // in the eviction-managed conversation store.
+    setSubagentConversation(conversationRecord.id, conversation);
     const labelKey = `${config.parentConversationId}:${config.label.toLowerCase().trim()}`;
     if (this.labelIndex.has(labelKey)) {
       log.warn(
@@ -695,7 +707,9 @@ export class SubagentManager {
    */
   private releaseConversation(managed: ManagedSubagent): void {
     if (!managed.conversation) return;
-    managed.conversation.dispose();
+    const conversation = managed.conversation;
+    removeSubagentConversation(conversation.conversationId, conversation);
+    conversation.dispose();
     managed.conversation = null;
     managed.retainedUntil = Date.now() + TERMINAL_RETENTION_MS;
     this.ensureSweepRunning();
@@ -716,16 +730,18 @@ export class SubagentManager {
     if (!managed) return;
 
     if (managed.conversation) {
+      const conversation = managed.conversation;
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
-        managed.conversation.abort(
+        conversation.abort(
           createAbortReason(
             "subagent_aborted",
             "SubagentManager.dispose",
-            managed.conversation.conversationId,
+            conversation.conversationId,
           ),
         );
       }
-      managed.conversation.dispose();
+      removeSubagentConversation(conversation.conversationId, conversation);
+      conversation.dispose();
       managed.conversation = null;
     }
     this.subagents.delete(subagentId);

package/src/telemetry/__tests__/activation-funnel.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  ACTIVATION_MOMENT_PARAMS,
+  ACTIVATION_STEPS,
+  activationStepIndex,
+  activationStepNameForMomentParam,
+  buildActivationDaemonEventId,
+  isActivationMomentParam,
+  isActivationStepName,
+} from "../activation-funnel.js";
+
+const ALL_STEP_NAMES = Object.values(ACTIVATION_STEPS).map((s) => s.stepName);
+
+describe("activation funnel vocabulary", () => {
+  test("step indices are 1-5 and unique", () => {
+    const indices = Object.values(ACTIVATION_STEPS).map((s) => s.stepIndex);
+    expect([...indices].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+    expect(new Set(indices).size).toBe(indices.length);
+  });
+
+  test("activationStepIndex resolves index from name", () => {
+    for (const { stepName, stepIndex } of Object.values(ACTIVATION_STEPS)) {
+      expect(activationStepIndex(stepName)).toBe(stepIndex);
+    }
+  });
+
+  test("isActivationStepName accepts all five step names", () => {
+    expect(ALL_STEP_NAMES).toHaveLength(5);
+    for (const stepName of ALL_STEP_NAMES) {
+      expect(isActivationStepName(stepName)).toBe(true);
+    }
+  });
+
+  test("isActivationStepName rejects unknown names", () => {
+    expect(isActivationStepName("bogus")).toBe(false);
+  });
+
+  test("buildActivationDaemonEventId is deterministic", () => {
+    expect(
+      buildActivationDaemonEventId("conv-abc", "activation_moment_1_complete"),
+    ).toBe("activation_v1_2026_06:conv-abc:activation_moment_1_complete");
+  });
+});
+
+describe("activation moment param (model-facing tag)", () => {
+  test("ACTIVATION_MOMENT_PARAMS lists the five tokens in step order", () => {
+    expect(ACTIVATION_MOMENT_PARAMS).toEqual([
+      "moment_1",
+      "moment_2",
+      "moment_3",
+      "first_wow_executed",
+      "first_wow_interacted",
+    ]);
+  });
+
+  test("isActivationMomentParam accepts all five tokens", () => {
+    for (const param of ACTIVATION_MOMENT_PARAMS) {
+      expect(isActivationMomentParam(param)).toBe(true);
+    }
+  });
+
+  test("isActivationMomentParam rejects unknown tokens (incl. wire step names)", () => {
+    expect(isActivationMomentParam("bogus")).toBe(false);
+    // The wire step name is NOT a valid model-facing token.
+    expect(isActivationMomentParam("activation_moment_1_complete")).toBe(false);
+    expect(isActivationMomentParam("moment_4")).toBe(false);
+  });
+
+  test("activationStepNameForMomentParam maps each token to its step name", () => {
+    expect(activationStepNameForMomentParam("moment_1")).toBe(
+      ACTIVATION_STEPS.moment1.stepName,
+    );
+    expect(activationStepNameForMomentParam("moment_2")).toBe(
+      ACTIVATION_STEPS.moment2.stepName,
+    );
+    expect(activationStepNameForMomentParam("moment_3")).toBe(
+      ACTIVATION_STEPS.moment3.stepName,
+    );
+    expect(activationStepNameForMomentParam("first_wow_executed")).toBe(
+      ACTIVATION_STEPS.firstWowExecuted.stepName,
+    );
+    expect(activationStepNameForMomentParam("first_wow_interacted")).toBe(
+      ACTIVATION_STEPS.firstWowInteracted.stepName,
+    );
+  });
+
+  test("every moment param maps to a valid wire step name", () => {
+    for (const param of ACTIVATION_MOMENT_PARAMS) {
+      expect(
+        isActivationStepName(activationStepNameForMomentParam(param)),
+      ).toBe(true);
+    }
+  });
+});