@vellumai/assistant 0.10.9-staging.1 → 0.10.9-staging.2

package/src/telemetry/telemetry-wire-validation.ts

@@ -0,0 +1,125 @@
+/**
+ * Pre-flush validation of outgoing telemetry events against the
+ * platform-generated wire schemas (`telemetry-wire.generated.ts`).
+ *
+ * The platform ingest endpoint rejects individual events that violate its
+ * serializer bounds and skips event types it has no serializer for — both
+ * silently from the daemon's point of view (the batch still 2xxes). This
+ * module surfaces those would-be-silent drops as structured warnings at the
+ * source, right before each POST.
+ *
+ * Observability only: validation never mutates, filters, or blocks a batch.
+ * The server remains the authority on what it accepts; in particular the
+ * `.trim()`-transformed parse output is never substituted for the original
+ * events.
+ */
+
+import type { z } from "zod";
+
+import type { getLogger } from "../util/logger.js";
+import { telemetryEventSchema } from "./telemetry-wire.generated.js";
+
+type Logger = ReturnType<typeof getLogger>;
+
+/**
+ * Per-event-type wire schema, derived by introspecting the generated
+ * discriminated union (`.options` + each member's `type` literal), so a new
+ * generated event type is validated with zero hand edits here.
+ */
+const wireSchemaByType: ReadonlyMap<string, z.ZodType> = new Map(
+  telemetryEventSchema.options.map((option) => [
+    option.shape.type.value,
+    option,
+  ]),
+);
+
+/**
+ * Event types already warned about as absent from the wire contract.
+ * Unknown-type warnings are rate-limited to once per process per type —
+ * without this, a daemon-only extension type (e.g. `onboarding_research`)
+ * would warn on every 5-minute flush forever.
+ */
+const warnedUnknownTypes = new Set<string>();
+
+/** Clears the once-per-process unknown-type warning rate limit. Test-only. */
+export function resetUnknownTypeWarningsForTests(): void {
+  warnedUnknownTypes.clear();
+}
+
+/**
+ * Render a zod issue path for logging without leaking dynamic record keys.
+ *
+ * Rule: keep numeric components (array indices — structural, never data) and
+ * keep the first (depth-0) component; redact every deeper string component to
+ * a literal `*`. Depth-0 is safe because every generated event schema is a
+ * flat `z.object`, so top-level path components are schema-defined field
+ * names. Deeper string components can be dynamic record keys — e.g. the turn
+ * schema's `client` bag superRefine emits issues at `['client', <key>]` where
+ * `<key>` comes from an uncontrolled JSON metadata column and could carry
+ * user text.
+ */
+function sanitizeIssuePath(path: ReadonlyArray<PropertyKey>): string {
+  return path
+    .map((component, depth) =>
+      typeof component === "number" || depth === 0 ? String(component) : "*",
+    )
+    .join(".");
+}
+
+interface WireValidationResult {
+  /** Events whose type had a wire schema and were parsed against it. */
+  checked: number;
+  /** Checked events that failed their wire schema. */
+  invalid: number;
+  /** Distinct event types with no wire schema — the server drops these. */
+  unknownTypes: string[];
+}
+
+/**
+ * Validate a batch of outgoing telemetry events against the platform wire
+ * schemas, logging a structured warning for each event the server would
+ * silently drop. Warn payloads carry the event `type` and issue
+ * `{ path, code }` shapes only — never field values, and never dynamic key
+ * components inside paths (see {@link sanitizeIssuePath}). That includes
+ * `daemon_event_id`: traces/claims can hold PII, and activation-funnel ids
+ * embed the onboarding session id.
+ *
+ * Never mutates, filters, or blocks: callers send the batch unchanged
+ * regardless of the result.
+ */
+export function validateWireEvents(
+  events: readonly { type: string }[],
+  log: Logger,
+): WireValidationResult {
+  let checked = 0;
+  let invalid = 0;
+  const unknownTypes = new Set<string>();
+  for (const event of events) {
+    const schema = wireSchemaByType.get(event.type);
+    if (!schema) {
+      unknownTypes.add(event.type);
+      if (!warnedUnknownTypes.has(event.type)) {
+        warnedUnknownTypes.add(event.type);
+        log.warn(
+          { eventType: event.type },
+          "telemetry event type not in platform wire contract — server drops these; see telemetry-wire.generated.ts",
+        );
+      }
+      continue;
+    }
+    checked += 1;
+    const result = schema.safeParse(event);
+    if (!result.success) {
+      invalid += 1;
+      const issues = result.error.issues.map((issue) => ({
+        path: sanitizeIssuePath(issue.path),
+        code: issue.code,
+      }));
+      log.warn(
+        { eventType: event.type, issues },
+        "telemetry event fails platform wire contract — server will silently drop it",
+      );
+    }
+  }
+  return { checked, invalid, unknownTypes: [...unknownTypes] };
+}

package/src/telemetry/telemetry-wire.generated.ts

@@ -57,10 +57,12 @@ export const TURN_CLIENT_MAX_JSON_BYTES = 2048;
 // pre-trim a trace it would rather not lose.
 export const TURN_TRACE_MAX_JSON_BYTES = 262144;
 export const WATCHDOG_DETAIL_MAX_JSON_BYTES = 4096;
+export const ONBOARDING_RESEARCH_CLAIMS_MAX_JSON_BYTES = 8192;
+export const ONBOARDING_RESEARCH_SUGGESTIONS_MAX_JSON_BYTES = 8192;
 
 export const llmUsageTelemetryEventSchema = z.object({
   type: z.literal("llm_usage"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   provider: z.string().trim().min(1).max(64),
@@ -93,7 +95,7 @@ export type LlmUsageTelemetryEvent = z.infer<
 export const turnTelemetryEventSchema = z
   .object({
     type: z.literal("turn"),
-    daemon_event_id: z.string().trim().min(1).max(36),
+    daemon_event_id: z.string().trim().min(1).max(128),
     recorded_at: z.number().int(),
     assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
     conversation_type: z.string().trim().min(1).max(32).nullable().optional(),
@@ -160,7 +162,7 @@ export type TurnTelemetryEvent = z.infer<typeof turnTelemetryEventSchema>;
 
 export const lifecycleTelemetryEventSchema = z.object({
   type: z.literal("lifecycle"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   event_name: z.string().trim().min(1).max(64),
@@ -172,7 +174,7 @@ export type LifecycleTelemetryEvent = z.infer<
 export const onboardingTelemetryEventSchema = z
   .object({
     type: z.literal("onboarding"),
-    daemon_event_id: z.string().trim().min(1).max(36),
+    daemon_event_id: z.string().trim().min(1).max(128),
     recorded_at: z.number().int(),
     assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
     screen: z.string().trim().min(1).max(64).optional(),
@@ -218,7 +220,7 @@ export type OnboardingTelemetryEvent = z.infer<
 
 export const authFallbackTelemetryEventSchema = z.object({
   type: z.literal("auth_fallback"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   guard: z.string().trim().min(1).max(64),
@@ -244,7 +246,7 @@ export const toolExecutedTelemetryEventSchema = z.object({
     .nullable()
     .optional(),
   type: z.literal("tool_executed"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   tool_name: z.string().trim().min(1).max(255),
@@ -270,7 +272,7 @@ export const skillLoadedTelemetryEventSchema = z.object({
     .nullable()
     .optional(),
   type: z.literal("skill_loaded"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   skill_name: z.string().trim().min(1).max(255),
@@ -284,7 +286,7 @@ export type SkillLoadedTelemetryEvent = z.infer<
 export const watchdogTelemetryEventSchema = z
   .object({
     type: z.literal("watchdog"),
-    daemon_event_id: z.string().trim().min(1).max(36),
+    daemon_event_id: z.string().trim().min(1).max(128),
     recorded_at: z.number().int(),
     assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
     check_name: z.string().trim().min(1).max(128),
@@ -312,7 +314,7 @@ export type WatchdogTelemetryEvent = z.infer<
 
 export const configSettingTelemetryEventSchema = z.object({
   type: z.literal("config_setting"),
-  daemon_event_id: z.string().trim().min(1).max(36),
+  daemon_event_id: z.string().trim().min(1).max(128),
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   config_key: z.string().trim().min(1).max(128),
@@ -322,6 +324,53 @@ export type ConfigSettingTelemetryEvent = z.infer<
   typeof configSettingTelemetryEventSchema
 >;
 
+export const onboardingResearchTelemetryEventSchema = z
+  .object({
+    type: z.literal("onboarding_research"),
+    daemon_event_id: z.string().trim().min(1).max(128),
+    recorded_at: z.number().int(),
+    assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
+    conversation_id: z.string().trim().min(1).max(64).nullable().optional(),
+    status: z.string().trim().min(1).max(32),
+    claims: z.array(jsonValueSchema).max(20),
+    claim_count: z.number().int().min(0),
+    claims_confident: z.number().int().min(0),
+    claims_maybe: z.number().int().min(0),
+    claims_guessing: z.number().int().min(0),
+    suggestions: z.array(jsonValueSchema).max(20),
+    suggestion_count: z.number().int().min(0),
+    plugins: z.array(z.string().trim().min(1).max(128)).max(20),
+    installed_plugins: z.array(z.string().trim().min(1).max(128)).max(20),
+  })
+  .superRefine((val, ctx) => {
+    // Mirrors the server's OnboardingResearchTelemetryEventSerializer
+    // validate_claims / validate_suggestions — an oversize `claims` or
+    // `suggestions` array is rejected by ingest (the event is silently
+    // dropped, never the whole batch).
+    if (
+      jsonByteLength(val.claims) > ONBOARDING_RESEARCH_CLAIMS_MAX_JSON_BYTES
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["claims"],
+        message: `\`claims\` JSON exceeds ${ONBOARDING_RESEARCH_CLAIMS_MAX_JSON_BYTES} bytes when serialized.`,
+      });
+    }
+    if (
+      jsonByteLength(val.suggestions) >
+      ONBOARDING_RESEARCH_SUGGESTIONS_MAX_JSON_BYTES
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["suggestions"],
+        message: `\`suggestions\` JSON exceeds ${ONBOARDING_RESEARCH_SUGGESTIONS_MAX_JSON_BYTES} bytes when serialized.`,
+      });
+    }
+  });
+export type OnboardingResearchTelemetryEvent = z.infer<
+  typeof onboardingResearchTelemetryEventSchema
+>;
+
 export type WireEventMap = {
   llm_usage: LlmUsageTelemetryEvent;
   turn: TurnTelemetryEvent;
@@ -332,6 +381,7 @@ export type WireEventMap = {
   skill_loaded: SkillLoadedTelemetryEvent;
   watchdog: WatchdogTelemetryEvent;
   config_setting: ConfigSettingTelemetryEvent;
+  onboarding_research: OnboardingResearchTelemetryEvent;
 };
 
 export const telemetryEventSchema = z.discriminatedUnion("type", [
@@ -344,6 +394,7 @@ export const telemetryEventSchema = z.discriminatedUnion("type", [
   skillLoadedTelemetryEventSchema,
   watchdogTelemetryEventSchema,
   configSettingTelemetryEventSchema,
+  onboardingResearchTelemetryEventSchema,
 ]);
 export type TelemetryEvent = z.infer<typeof telemetryEventSchema>;
 

package/src/telemetry/types.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  turnEventSample,
+  wireEventSamples,
+} from "./__tests__/telemetry-event-fixtures.js";
+import { telemetryEventSchema } from "./telemetry-wire.generated.js";
+import type { TurnTelemetryEvent } from "./types.js";
+
+// Runtime contract test: events constructed with the daemon's types (the
+// shared fixtures are annotated with them) must parse against the generated
+// wire schemas — the same validation the platform's ingest serializers
+// apply. A daemon type whose values can't round-trip through
+// `telemetryEventSchema` produces events the server silently drops.
+
+describe("daemon telemetry types against the wire contract", () => {
+  for (const sample of wireEventSamples) {
+    test(`daemon-typed ${sample.type} event parses against the wire schema`, () => {
+      const result = telemetryEventSchema.safeParse(sample);
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+    });
+  }
+
+  test("turn client bag with a nested value fails the wire superRefine", () => {
+    // Structurally valid for the daemon's `TurnTelemetryClientInfo` (extra
+    // properties are allowed outside fresh-literal checks), but the wire
+    // schema mirrors the server's validate_client: nested objects in the
+    // `client` bag reject the event at ingest.
+    const nestedClient = { os: "macos", screen: { width: 1512, height: 982 } };
+    const invalidTurn: TurnTelemetryEvent = {
+      ...turnEventSample,
+      client: nestedClient,
+    };
+    const result = telemetryEventSchema.safeParse(invalidTurn);
+    expect(result.success).toBe(false);
+  });
+});

package/src/telemetry/types.ts

@@ -1,5 +1,7 @@
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { UsageAttributionProfileSource } from "../usage/types.js";
+import type * as wire from "./telemetry-wire.generated.js";
+import type { TurnOutcome } from "./turn-outcome.js";
 
 /** Base fields present on every telemetry event. */
 export interface TelemetryEventBase {
@@ -54,6 +56,18 @@ export interface ModelTelemetryEventBase extends TelemetryEventBase {
   inference_profile_source: UsageAttributionProfileSource | null;
 }
 
+/**
+ * Applies the daemon's record-time guarantee to a wire-derived event type.
+ *
+ * The wire contract marks `assistant_version` optional for back-compat with
+ * old daemons; under the platform's per-event-wins contract a present
+ * per-event value (including explicit `null`) beats the envelope fallback.
+ * This daemon always stamps the field at record time (see
+ * {@link TelemetryEventBase.assistant_version} for the full contract), so
+ * wire-derived event types are re-typed with the field required.
+ */
+type Daemonize<T> = T & { assistant_version: string | null };
+
 /**
  * LLM usage event — one per persisted usage row. The main agent loop
  * persists a single row per turn with token totals summed across every
@@ -329,7 +343,7 @@ export interface TurnTelemetryEvent extends TelemetryEventBase {
    * could land — so `absent + no assistant message in trace` isolates the
    * genuinely anomalous (crashed/unknown) turns.
    */
-  outcome?: "batched" | "failed" | "cancelled";
+  outcome?: TurnOutcome;
   /**
    * For `outcome: "batched"` turns: the `daemon_event_id` of the
    * batch-final turn whose window carries the shared response. Omitted
@@ -358,64 +372,6 @@ export interface TurnTelemetryEvent extends TelemetryEventBase {
   trace?: TurnTrace | null;
 }
 
-/** Lifecycle event — app_open, hatch, etc. */
-export interface LifecycleTelemetryEvent extends TelemetryEventBase {
-  type: "lifecycle";
-  event_name: string;
-}
-
-/** Onboarding event — pre-chat selections and Google connect status. */
-export interface OnboardingTelemetryEvent extends TelemetryEventBase {
-  type: "onboarding";
-  screen: string;
-  tools?: string[];
-  tasks?: string[];
-  tone?: string;
-  google_connected?: boolean;
-  google_scopes?: string[];
-  ab_variant?: string;
-  /**
-   * Activation-funnel fields (mirror the web funnel shape and the platform
-   * serializer). The platform accepts an onboarding event via either the
-   * legacy `screen` path or the all-funnel-fields path (`session_id` +
-   * `step_name` + `step_index` + `completed_at` + `funnel_version` +
-   * `ab_variant`).
-   */
-  session_id?: string;
-  step_name?: string;
-  step_index?: number;
-  completed_at?: string;
-  funnel_version?: string;
-  user_id?: string;
-}
-
-/**
- * Auth-fallback event — aggregated count of requests served via the legacy
- * loopback auth fallback. One event per (guard, path, failure_kind) per flush
- * window. Lets the platform see which deployments still rely on the loopback
- * exemption instead of sending a bearer token.
- */
-export interface AuthFallbackTelemetryEvent extends TelemetryEventBase {
-  type: "auth_fallback";
-  /** Which auth guard fell back: `"edge"` | `"edge-scoped"` | `"edge-guardian"`. */
-  guard: string;
-  /** Request pathname that fell back. */
-  path: string;
-  /**
-   * Why the bearer-token check did not succeed before the fallback:
-   * `"missing_authorization"` | `"malformed_authorization"` |
-   * `"token_validation_failed"` | `"insufficient_scope"` |
-   * `"non_actor_principal"` | `"guardian_mismatch"`.
-   */
-  failure_kind: string;
-  /** Number of requests that fell back for this key during the window. */
-  count: number;
-  /** Window start (epoch ms) the count was accumulated over. */
-  window_start: number;
-  /** Window end (epoch ms) the count was accumulated over. */
-  window_end: number;
-}
-
 /**
  * Tool-executed event — one per tool invocation. Carries NO tool
  * args/inputs or result contents (customer PII per ToS) — payload sizes
@@ -490,27 +446,6 @@ export interface WatchdogTelemetryEvent extends TelemetryEventBase {
   detail: Record<string, unknown> | null;
 }
 
-/**
- * Config-setting event — records a tracked config key's effective value.
- * A single string:string pair on top of the standard envelope, mirroring
- * the platform `ConfigSettingTelemetryEventSerializer`:
- *
- *   - `config_key` — dotted config path (e.g. `"memory.enabled"`).
- *     Bounded server-side at 128 chars.
- *   - `config_value` — the effective value rendered as a string
- *     (`"true"` / `"false"` for booleans). Bounded server-side at 256
- *     chars.
- *
- * Metadata only — emitters record an explicit allowlist of non-sensitive
- * settings, never free-form config content. Dedupe downstream on
- * `daemon_event_id` (the daemon retries a batch on transient POST failure).
- */
-export interface ConfigSettingTelemetryEvent extends TelemetryEventBase {
-  type: "config_setting";
-  config_key: string;
-  config_value: string;
-}
-
 /** One inferred fact from the onboarding research-onboarding web-search turn. */
 export interface OnboardingResearchClaim {
   claim: string;
@@ -553,18 +488,175 @@ export interface OnboardingResearchTelemetryEvent extends TelemetryEventBase {
   installed_plugins: string[];
 }
 
+/**
+ * Wire-derived event types with the daemon's record-time
+ * `assistant_version` guarantee applied. New event types added to the wire
+ * contract flow through here with zero hand edits.
+ */
+type WireDaemonized = {
+  [K in keyof wire.WireEventMap]: Daemonize<wire.WireEventMap[K]>;
+};
+
+/** Events where the daemon's type is intentionally narrower than the wire. */
+type Overrides = {
+  llm_usage: LlmUsageTelemetryEvent;
+  turn: TurnTelemetryEvent;
+  tool_executed: ToolExecutedTelemetryEvent;
+  skill_loaded: SkillLoadedTelemetryEvent;
+  watchdog: WatchdogTelemetryEvent;
+  onboarding_research: OnboardingResearchTelemetryEvent;
+};
+
+/**
+ * Daemon-only event types not (yet) in the platform wire contract — i.e. types
+ * the daemon emits but `POST /v1/telemetry/ingest/` would silently skip because
+ * they have no serializer in the platform's `TELEMETRY_EVENT_SERIALIZERS`.
+ *
+ * Currently EMPTY: every emitted type is in the wire contract. When the daemon
+ * needs to emit a type before the platform accepts it, add it here (keyed by
+ * its wire `type`). Once the platform adds the serializer and the wire sync
+ * lands, the key must leave `Extensions` — into `Overrides` if the daemon type
+ * stays narrower than the wire, or plain wire flow-through otherwise. The
+ * `_extensionsDontCollide` guard below turns red until that move is made.
+ */
+type Extensions = Record<never, never>;
+
+type EventMap = Omit<WireDaemonized, keyof Overrides> & Overrides & Extensions;
+
 /** Discriminated union of all telemetry event types. */
-export type TelemetryEvent =
-  | LlmUsageTelemetryEvent
-  | TurnTelemetryEvent
-  | LifecycleTelemetryEvent
-  | OnboardingTelemetryEvent
-  | AuthFallbackTelemetryEvent
-  | ToolExecutedTelemetryEvent
-  | SkillLoadedTelemetryEvent
-  | WatchdogTelemetryEvent
-  | ConfigSettingTelemetryEvent
-  | OnboardingResearchTelemetryEvent;
+export type TelemetryEvent = EventMap[keyof EventMap];
+
+/**
+ * Lifecycle event — app_open, hatch, etc. 1:1 with the wire contract:
+ * `telemetry-wire.generated.ts` (from the platform's
+ * `LifecycleTelemetryEventSerializer`) is the source of truth.
+ */
+export type LifecycleTelemetryEvent = EventMap["lifecycle"];
+
+/**
+ * Onboarding event — pre-chat selections, Google connect status, and
+ * activation-funnel steps. 1:1 with the wire contract
+ * (`OnboardingTelemetryEventSerializer`); the platform accepts either the
+ * legacy `screen` shape or the complete funnel step field set — see the wire
+ * schema's superRefine.
+ */
+export type OnboardingTelemetryEvent = EventMap["onboarding"];
+
+/**
+ * Auth-fallback event — aggregated count of requests served via the legacy
+ * loopback auth fallback, one event per (guard, path, failure_kind) per
+ * flush window (`count` is a per-window delta, not a running total). 1:1
+ * with the wire contract (`AuthFallbackTelemetryEventSerializer`).
+ */
+export type AuthFallbackTelemetryEvent = EventMap["auth_fallback"];
+
+/**
+ * Config-setting event — a tracked config key's effective value rendered as
+ * a string; emitters record an explicit allowlist of non-sensitive settings,
+ * never free-form config content. 1:1 with the wire contract
+ * (`ConfigSettingTelemetryEventSerializer`).
+ */
+export type ConfigSettingTelemetryEvent = EventMap["config_setting"];
+
+// ---- Compile-time drift guards ----
+// Each `Overrides` entry is pinned to its wire type in BOTH directions, so a
+// wire sync PR that moves the platform contract turns red here instead of
+// drifting silently:
+//
+//   - `_*Narrows` — the daemon type stays assignable to the wire type, i.e.
+//     every daemon field's value is acceptable to the wire. Catches wire-side
+//     tightening (narrowed unions, newly required fields) and daemon-side
+//     loosening.
+//   - `_*KeysExist` — every key the daemon emits still exists on the wire
+//     type. Structural subtyping treats a daemon field the wire dropped as a
+//     harmless extra property, so `_*Narrows` alone stays green when the
+//     platform REMOVES or RENAMES a field; this key-set check is what catches
+//     those.
+//
+// Flow-through (non-override) events need no guards: they use the generated
+// wire types directly, so their construction sites get excess-property /
+// missing-field errors the moment the contract moves.
+type AssertNarrows<_Narrow extends Wide, Wide> = true;
+type AssertNoWireCollision<_Keys extends never> = true;
+
+// `raw_usage` is excluded: the server treats it as an opaque JSONField, so
+// the daemon's `Record<string, unknown>` (not structurally assignable to the
+// wire's recursive `JsonValue`) is wire-safe — any JSON-serializable shape
+// ships fine.
+type _llmUsageNarrows = AssertNarrows<
+  Omit<LlmUsageTelemetryEvent, "raw_usage">,
+  Omit<wire.LlmUsageTelemetryEvent, "raw_usage">
+>;
+// `trace` and `client` are excluded: the server treats both as opaque JSON
+// (JSONField/DictField), so the daemon's richer `TurnTrace`
+// (`content: unknown`) and `TurnTelemetryClientInfo` shapes are wire-safe
+// even though they are not assignable to `JsonValue`. Runtime bounds are
+// enforced by the wire schema's superRefines, not by these types.
+type _turnNarrows = AssertNarrows<
+  Omit<TurnTelemetryEvent, "trace" | "client">,
+  Omit<wire.TurnTelemetryEvent, "trace" | "client">
+>;
+type _toolExecutedNarrows = AssertNarrows<
+  ToolExecutedTelemetryEvent,
+  wire.ToolExecutedTelemetryEvent
+>;
+type _skillLoadedNarrows = AssertNarrows<
+  SkillLoadedTelemetryEvent,
+  wire.SkillLoadedTelemetryEvent
+>;
+// `detail` is excluded: the server treats it as an opaque JSONField, so the
+// daemon's `Record<string, unknown>` bag is wire-safe; the serialized-size
+// bound is enforced by the wire schema's superRefine.
+type _watchdogNarrows = AssertNarrows<
+  Omit<WatchdogTelemetryEvent, "detail">,
+  Omit<wire.WatchdogTelemetryEvent, "detail">
+>;
+// Reverse (key-existence) direction. Unlike the `_*Narrows` guards, the
+// opaque-JSON fields are NOT excluded here: opacity is about a field's
+// SHAPE (the daemon's richer types aren't assignable to `JsonValue`), but
+// key PRESENCE is part of the typed contract — the generated wire types
+// declare `raw_usage`/`trace`/`client`/`detail`, and a platform sync that
+// removed or renamed one of them would otherwise leave every guard green
+// while the daemon kept emitting a field the server discards.
+type _llmUsageKeysExist = AssertNarrows<
+  keyof LlmUsageTelemetryEvent,
+  keyof wire.LlmUsageTelemetryEvent
+>;
+type _turnKeysExist = AssertNarrows<
+  keyof TurnTelemetryEvent,
+  keyof wire.TurnTelemetryEvent
+>;
+type _toolExecutedKeysExist = AssertNarrows<
+  keyof ToolExecutedTelemetryEvent,
+  keyof wire.ToolExecutedTelemetryEvent
+>;
+type _skillLoadedKeysExist = AssertNarrows<
+  keyof SkillLoadedTelemetryEvent,
+  keyof wire.SkillLoadedTelemetryEvent
+>;
+type _watchdogKeysExist = AssertNarrows<
+  keyof WatchdogTelemetryEvent,
+  keyof wire.WatchdogTelemetryEvent
+>;
+// `claims` and `suggestions` are excluded from the narrows: the server types
+// both as opaque JSON arrays (`z.array(jsonValueSchema)`), so the daemon's
+// structured `OnboardingResearchClaim[]` / `OnboardingResearchSuggestion[]`
+// shapes are wire-safe even though they aren't assignable to `JsonValue[]`.
+// Runtime size bounds are enforced by the wire schema's superRefine.
+type _onboardingResearchNarrows = AssertNarrows<
+  Omit<OnboardingResearchTelemetryEvent, "claims" | "suggestions">,
+  Omit<wire.OnboardingResearchTelemetryEvent, "claims" | "suggestions">
+>;
+type _onboardingResearchKeysExist = AssertNarrows<
+  keyof OnboardingResearchTelemetryEvent,
+  keyof wire.OnboardingResearchTelemetryEvent
+>;
+// An `Extensions` key that also exists in the wire map would silently
+// shadow the generated type; this stays `never` only while the key sets
+// are disjoint.
+type _extensionsDontCollide = AssertNoWireCollision<
+  keyof Extensions & keyof wire.WireEventMap
+>;
 
 /**
  * Event names backed by the `telemetry_events` outbox. Each name doubles as

package/src/telemetry/usage-telemetry-reporter.ts

@@ -46,6 +46,7 @@ import {
   watermarkKeysForSource,
 } from "./telemetry-event-sources.js";
 import { useReadOnlyMainDbForTelemetry } from "./telemetry-main-db.js";
+import { validateWireEvents } from "./telemetry-wire-validation.js";
 
 const log = getLogger("usage-telemetry");
 
@@ -405,6 +406,10 @@ export class UsageTelemetryReporter {
       // in cursor order.
       const typedEvents = batches.flatMap(({ batch }) => batch.events);
 
+      // Pre-flush wire validation — observability only: warns about events
+      // the server would silently drop; the batch is POSTed unchanged.
+      validateWireEvents(typedEvents, log);
+
       const organizationId = getPlatformOrganizationId() || undefined;
       const userId = getPlatformUserId() || undefined;
       const payload = {

package/src/telemetry/watchdog-direct-emit.ts

@@ -25,6 +25,7 @@ import { arePlatformFeaturesEnabled } from "../platform/feature-gate.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger } from "../util/logger.js";
 import { APP_VERSION } from "../version.js";
+import { validateWireEvents } from "./telemetry-wire-validation.js";
 import type { WatchdogTelemetryEvent } from "./types.js";
 
 const log = getLogger("watchdog-direct-emit");
@@ -62,6 +63,11 @@ export async function emitWatchdogEventDirect(
       detail,
       assistant_version: APP_VERSION,
     };
+
+    // Pre-flush wire validation — observability only: warns when the server
+    // would silently drop the event; the POST proceeds unchanged.
+    validateWireEvents([event], log);
+
     const organizationId = getPlatformOrganizationId() || undefined;
     const userId = getPlatformUserId() || undefined;
     const resp = await client.fetch(TELEMETRY_INGEST_PATH, {