@mycadet/assistant 0.12.9 → 0.12.11

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

@@ -1,157 +0,0 @@
-/**
- * Tests for pre-flush telemetry wire validation.
- *
- * Validation is observability only — it must count and warn, never mutate,
- * filter, or block — and its warn payloads must carry the event type and
- * issue `{ path, code }` shapes only, never field values. `daemon_event_id`
- * is a field value too: activation-funnel ids embed the onboarding session
- * id (traces/claims can hold PII). Issue paths are sanitized as well: dynamic
- * record keys (e.g. `client` bag keys) are redacted to `*` before logging.
- */
-import { beforeEach, describe, expect, test } from "bun:test";
-
-import type { Logger } from "pino";
-
-import {
-  turnEventSample,
-  wireEventSamples,
-} from "./__tests__/telemetry-event-fixtures.js";
-import { telemetryEventSchema } from "./telemetry-wire.generated.js";
-import {
-  resetUnknownTypeWarningsForTests,
-  validateWireEvents,
-} from "./telemetry-wire-validation.js";
-
-let warnCalls: unknown[][] = [];
-const stubLog = {
-  warn: (...args: unknown[]) => {
-    warnCalls.push(args);
-  },
-} as unknown as Logger;
-
-describe("validateWireEvents", () => {
-  beforeEach(() => {
-    warnCalls = [];
-    resetUnknownTypeWarningsForTests();
-  });
-
-  test("a valid event of each wire type passes with no warnings", () => {
-    // Fixture coverage: one sample per generated union discriminator (with a
-    // floor of the 9 shipped types), so a new wire type without a fixture —
-    // or a shrunken union — turns this red.
-    const discriminators = telemetryEventSchema.options.map(
-      (option) => option.shape.type.value,
-    );
-    expect(discriminators.length).toBeGreaterThanOrEqual(9);
-    expect(new Set(wireEventSamples.map((event) => event.type))).toEqual(
-      new Set(discriminators),
-    );
-
-    const result = validateWireEvents(wireEventSamples, stubLog);
-    expect(result).toEqual({
-      checked: wireEventSamples.length,
-      invalid: 0,
-      unknownTypes: [],
-    });
-    expect(warnCalls).toHaveLength(0);
-  });
-
-  test("invalid events are counted and warned with {path, code} issues and no field values", () => {
-    const sentinel = "SENTINEL_PII_VALUE_do_not_log";
-    const invalidTurn = {
-      ...turnEventSample,
-      // Nested object values violate the wire contract's client bounds; the
-      // sentinel must never appear in any warn payload.
-      client: { nested: { secret: sentinel } },
-    };
-    const invalidLifecycle = {
-      type: "lifecycle",
-      // An id embedding the onboarding session id and padded past the wire
-      // schema's 128-char daemon_event_id bound — the id value itself must
-      // never be logged, only its (redacted) issue path.
-      daemon_event_id: `activation_v1_2026_06:${sentinel}:${"x".repeat(100)}`,
-      recorded_at: 1_700_000_000_011,
-      assistant_version: sentinel,
-      // event_name is missing.
-    };
-
-    const result = validateWireEvents([invalidTurn, invalidLifecycle], stubLog);
-    expect(result).toEqual({ checked: 2, invalid: 2, unknownTypes: [] });
-    expect(warnCalls).toHaveLength(2);
-
-    for (const call of warnCalls) {
-      const bag = call[0] as {
-        eventType: string;
-        issues: Array<Record<string, unknown>>;
-      };
-      // The bag carries the event type and issues only — no daemon_event_id
-      // (it is a payload value; activation ids embed the session id).
-      expect(Object.keys(bag).sort()).toEqual(["eventType", "issues"]);
-      expect(bag.issues.length).toBeGreaterThan(0);
-      for (const issue of bag.issues) {
-        // Issues carry path + code only — never messages or field values.
-        expect(Object.keys(issue).sort()).toEqual(["code", "path"]);
-        expect(issue.path).toBeString();
-        expect(issue.code).toBeString();
-      }
-    }
-    expect(
-      (warnCalls[0][0] as { issues: Array<{ path: string }> }).issues[0].path,
-    ).toStartWith("client");
-    const lifecyclePaths = (
-      warnCalls[1][0] as { issues: Array<{ path: string }> }
-    ).issues.map((issue) => issue.path);
-    expect(lifecyclePaths).toContain("daemon_event_id");
-    expect(lifecyclePaths).toContain("event_name");
-
-    // The planted sentinel (a field value) must be absent from all log args.
-    expect(JSON.stringify(warnCalls)).not.toInclude(sentinel);
-  });
-
-  test("dynamic record keys in issue paths are redacted to *", () => {
-    const sentinel = "sentinel-user@example.com";
-    const invalidTurn = {
-      ...turnEventSample,
-      // The client bag's keys come from an uncontrolled JSON metadata column;
-      // the superRefine emits issues at ['client', <key>], so a key carrying
-      // user text must be redacted from the logged path. The nested object
-      // value makes the bag invalid.
-      client: { [sentinel]: { nested: true } },
-    };
-
-    const result = validateWireEvents([invalidTurn], stubLog);
-    expect(result).toEqual({ checked: 1, invalid: 1, unknownTypes: [] });
-    expect(warnCalls).toHaveLength(1);
-
-    const bag = warnCalls[0][0] as { issues: Array<{ path: string }> };
-    // The dynamic key component is replaced with a literal `*`; the
-    // schema-defined depth-0 component (`client`) is kept.
-    expect(bag.issues.map((issue) => issue.path)).toContain("client.*");
-    expect(JSON.stringify(warnCalls)).not.toInclude(sentinel);
-  });
-
-  test("unknown event types are reported and warned once per process per type", () => {
-    // A type the cloud ingest endpoint has no serializer for: the server
-    // silently skips it. Uses a synthetic never-shipped discriminant so the
-    // test stays valid as real event types graduate into the wire contract.
-    const unknownEvent = {
-      type: "speculative_future_event",
-      daemon_event_id: "evt-unknown-1",
-      recorded_at: 1_700_000_000_020,
-      assistant_version: "1.2.3",
-    };
-    const first = validateWireEvents([unknownEvent], stubLog);
-    const second = validateWireEvents([unknownEvent], stubLog);
-
-    expect(first).toEqual({
-      checked: 0,
-      invalid: 0,
-      unknownTypes: ["speculative_future_event"],
-    });
-    expect(second.unknownTypes).toEqual(["speculative_future_event"]);
-
-    // Rate-limited: the warn fires exactly once across both calls.
-    expect(warnCalls).toHaveLength(1);
-    expect(warnCalls[0][0]).toEqual({ eventType: "speculative_future_event" });
-  });
-});

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

@@ -1,162 +0,0 @@
-/**
- * Pre-flush validation of outgoing telemetry events against the
- * platform-generated wire schemas (`telemetry-wire.generated.ts`).
- *
- * The cloud 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 { 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.ZodObject> = new Map(
-  telemetryEventSchema.options.map((option) => [
-    option.shape.type.value,
-    option,
-  ]),
-);
-
-/**
- * Base fields stamped by the daemon at record time, never supplied by a client.
- * Stripped when deriving the client-facing `fields` schema for a wire type.
- */
-const TELEMETRY_BASE_FIELD_KEYS = {
-  type: true,
-  daemon_event_id: true,
-  recorded_at: true,
-  assistant_version: true,
-} as const;
-
-/**
- * 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();
-}
-
-/**
- * Per-event-type wire schema for one `type` discriminant, or undefined when the
- * platform contract has no serializer for it. Lets the client-ingest boundary
- * (`POST /v1/telemetry/ingest`) reject a malformed payload up front with the
- * same schema pre-flush validation would have logged a silent drop for.
- */
-export function getWireSchemaForType(type: string): z.ZodObject | undefined {
-  return wireSchemaByType.get(type);
-}
-
-/**
- * Client-facing `fields` schema for a wire type: the wire object minus the
- * daemon-stamped base fields. Rebuilt from `.shape` because `.omit()` rejects
- * the refined wire schemas; this drops the claims/suggestions byte-bound
- * superRefines, which aren't expressible in the request type anyway — the
- * handler still validates the assembled event against the full wire schema
- * ({@link getWireSchemaForType}) for those bounds. Undefined when the cloud
- * contract has no serializer for `type`.
- */
-export function getWireFieldsSchema(type: string): z.ZodObject | undefined {
-  const schema = wireSchemaByType.get(type);
-  return schema
-    ? z.object(schema.shape).omit(TELEMETRY_BASE_FIELD_KEYS)
-    : undefined;
-}
-
-/**
- * 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 cloud 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] };
-}