Merge: ban as-casts + assertUnreachable + postJson + agent sequential-chain eval

Author: DylanMerigaud

components/onboarding.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
+import { z } from "zod";
 
 import { Badge } from "@/components/ui/badge";
 import {
@@ -14,7 +15,8 @@ import { Card, CardHeader, CardTitle, Eyebrow } from "@/components/ui/card";
 import { WorkflowEditor } from "@/components/workflow-editor";
 import { WorkflowGraph } from "@/components/workflow-graph";
 import { API_ROUTES } from "@/lib/api-routes";
-import type { ApprovalWorkflow } from "@/lib/approval-workflow";
+import { ApprovalWorkflow } from "@/lib/approval-workflow";
+import { postJson, FetchJsonError } from "@/lib/fetch-json";
 
 /**
  * The onboarding discovery screen — the forward-deployed-engineer step.
@@ -30,34 +32,46 @@ import type { ApprovalWorkflow } from "@/lib/approval-workflow";
  * issues before it goes live. (Conversational edits are the next layer.)
  */
 
-type RoleResolution = {
-  role: string;
-  title: string;
-  employeeName: string | null;
-  rationale: string;
-};
-type OrgEmployee = {
-  id: string;
-  name: string;
-  title: string;
-  department: string;
-  division: string;
-  managerId: string | null;
-};
-type OnboardingResponse = {
-  source: string;
-  employeeCount: number;
-  employees: OrgEmployee[];
-  workflow: ApprovalWorkflow;
-  proposal: {
-    directorThreshold: number;
-    roles: RoleResolution[];
-    summary: string;
-  };
-  issues: { employeeName: string; detail: string; note: string }[];
+// The /api/onboarding response, as a Zod schema so we VALIDATE it at the fetch
+// boundary (no `res.json() as T`). Types are derived from the schemas.
+const OrgEmployee = z.object({
+  id: z.string(),
+  name: z.string(),
+  title: z.string(),
+  department: z.string(),
+  division: z.string(),
+  managerId: z.string().nullable(),
+});
+type OrgEmployee = z.infer<typeof OrgEmployee>;
+
+const RoleResolution = z.object({
+  role: z.string(),
+  title: z.string(),
+  employeeName: z.string().nullable(),
+  rationale: z.string(),
+});
+
+const OnboardingResponse = z.object({
+  source: z.string(),
+  employeeCount: z.number(),
+  employees: z.array(OrgEmployee),
+  workflow: ApprovalWorkflow,
+  proposal: z.object({
+    directorThreshold: z.number(),
+    roles: z.array(RoleResolution),
+    summary: z.string(),
+  }),
+  issues: z.array(
+    z.object({
+      employeeName: z.string(),
+      detail: z.string(),
+      note: z.string(),
+    }),
+  ),
   /** Up to three AI-generated next-edit suggestions for the derived workflow. */
-  suggestions: string[];
-};
+  suggestions: z.array(z.string()),
+});
+type OnboardingResponse = z.infer<typeof OnboardingResponse>;
 
 type State =
   | { status: "idle" }
@@ -71,19 +85,14 @@ export const Onboarding = () => {
   const discover = async () => {
     setState({ status: "running" });
     try {
-      const res = await fetch(API_ROUTES.onboarding, { method: "POST" });
-      if (!res.ok) {
-        const msg = await res
-          .json()
-          .then((j: { error?: string }) => j.error)
-          .catch(() => null);
-        setState({ status: "error", message: msg ?? "Discovery failed." });
-        return;
-      }
-      const data = (await res.json()) as OnboardingResponse;
+      const data = await postJson(API_ROUTES.onboarding, OnboardingResponse);
       setState({ status: "done", data });
-    } catch {
-      setState({ status: "error", message: "Could not reach the server." });
+    } catch (err) {
+      setState({
+        status: "error",
+        message:
+          err instanceof FetchJsonError ? err.message : "Discovery failed.",
+      });
     }
   };
 
@@ -213,7 +222,12 @@ const WhatCanIChange = () => {
   useEffect(() => {
     if (!open) return;
     const onDoc = (e: MouseEvent) => {
-      if (ref.current && !ref.current.contains(e.target as globalThis.Node))
+      const target = e.target;
+      if (
+        target instanceof Node &&
+        ref.current &&
+        !ref.current.contains(target)
+      )
         setOpen(false);
     };
     document.addEventListener("mousedown", onDoc);

components/trace-timeline.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+import { z } from "zod";
+
 import { TraceDetail } from "@/components/trace-detail";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -163,14 +165,23 @@ const TraceNode = ({
   );
 };
 
+/** The few summary fields a stage may carry on `data`, for the chip. Validated with
+    Zod (data is `unknown` on the trace) so we read TYPED fields, not `d["verdict"]`. */
+const ChipFields = z.object({
+  verdict: z.string().optional(),
+  tier: z.string().optional(),
+  outcome: z.string().optional(), // posted / awaiting / rejected / blocked
+  posted: z.boolean().optional(),
+});
+
 /** Short chip text summarizing a step's outcome (verdict / tier / posted). */
 const verdictChip = (event: TraceEvent): string => {
-  const d = event.data as Record<string, unknown> | undefined;
+  const d = ChipFields.safeParse(event.data).data;
   if (d) {
-    if (typeof d["verdict"] === "string") return humanize(d["verdict"]);
-    if (typeof d["tier"] === "string") return humanize(d["tier"]);
-    if (typeof d["outcome"] === "string") return humanize(d["outcome"]); // posted/awaiting/rejected/blocked
-    if ("posted" in d) return d["posted"] ? "Posted" : "Not posted";
+    if (d.verdict) return humanize(d.verdict);
+    if (d.tier) return humanize(d.tier);
+    if (d.outcome) return humanize(d.outcome);
+    if (d.posted !== undefined) return d.posted ? "Posted" : "Not posted";
   }
   if (event.status === "running") return "Running";
   return stageLabel(event.stage);

components/workflow-editor.tsx

@@ -1,11 +1,13 @@
 "use client";
 
 import { useMemo, useState } from "react";
+import { z } from "zod";
 
 import { Button } from "@/components/ui/button";
 import { WorkflowGraph } from "@/components/workflow-graph";
 import { API_ROUTES } from "@/lib/api-routes";
-import type { ApprovalWorkflow, StepChange } from "@/lib/approval-workflow";
+import { ApprovalWorkflow, type StepChange } from "@/lib/approval-workflow";
+import { postJson, FetchJsonError } from "@/lib/fetch-json";
 import {
   validateWorkflow,
   isActivatable,
@@ -32,6 +34,26 @@ type Proposal = {
   changes: StepChange[];
 };
 
+// The /api/workflow/edit response, as a Zod schema so we validate it at the fetch
+// boundary instead of asserting `res.json() as …`. The `changes` union mirrors
+// `StepChange` exactly (only "changed" carries `fields`).
+const StepChangeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("added"), id: z.string(), label: z.string() }),
+  z.object({ kind: z.literal("removed"), id: z.string(), label: z.string() }),
+  z.object({
+    kind: z.literal("changed"),
+    id: z.string(),
+    label: z.string(),
+    fields: z.array(z.string()),
+  }),
+  z.object({ kind: z.literal("unchanged"), id: z.string(), label: z.string() }),
+]);
+const EditResponse = z.object({
+  proposed: ApprovalWorkflow,
+  changes: z.array(StepChangeSchema),
+  reason: z.string().nullable().optional(),
+});
+
 export const WorkflowEditor = ({
   initial,
   suggestions = [],
@@ -55,20 +77,10 @@ export const WorkflowEditor = ({
     setBusy(true);
     setError(null);
     try {
-      const res = await fetch(API_ROUTES.workflowEdit, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ workflow: current, instruction: value }),
+      const data = await postJson(API_ROUTES.workflowEdit, EditResponse, {
+        workflow: current,
+        instruction: value,
       });
-      if (!res.ok) {
-        const msg = await res
-          .json()
-          .then((j: { error?: string }) => j.error)
-          .catch(() => null);
-        setError(msg ?? "Edit failed.");
-        return;
-      }
-      const data = (await res.json()) as Proposal & { reason?: string | null };
       const realChanges = data.changes.filter((c) => c.kind !== "unchanged");
       if (realChanges.length === 0) {
         // The agent declined (redundant / off-topic) — say so, don't offer a no-op.
@@ -79,12 +91,12 @@ export const WorkflowEditor = ({
         );
         return;
       }
-      setProposal(data);
+      setProposal({ proposed: data.proposed, changes: data.changes });
       setInstruction("");
       // Drop the chip we just used (if this came from one).
       setChips((cs) => cs.filter((c) => c !== value));
-    } catch {
-      setError("Could not reach the server.");
+    } catch (err) {
+      setError(err instanceof FetchJsonError ? err.message : "Edit failed.");
     } finally {
       setBusy(false);
     }

eslint.config.mts

@@ -88,6 +88,9 @@ export default tseslint.config(
       "@typescript-eslint/no-unnecessary-type-assertion": "error",
       "@typescript-eslint/no-explicit-any": "error",
       "@typescript-eslint/no-non-null-assertion": "error",
+      // No `x as T` assertions — narrow with a guard, validate with a schema, or use
+      // `satisfies`. (Const assertions `as const` are still allowed.)
+      "@typescript-eslint/no-unsafe-type-assertion": "error",
       "@typescript-eslint/no-unnecessary-condition": "error",
 
       // ── Type style ──────────────────────────────────────────────────────────

hooks/use-event-callback.ts

@@ -17,8 +17,13 @@ export const useEventCallback = <
     ref.current = fn;
   });
 
-  return useRef<T>(
-    ((...args: Parameters<T>): ReturnType<T> =>
-      ref.current(...args) as ReturnType<T>) as T,
-  ).current;
+  // The wrapper has T's exact call signature but TS can't infer it's assignable to
+  // the generic T itself — the one boundary assertion unavoidable in this utility.
+  // The return is `any` only because T's return is `any` (same generic-callback
+  // reason as the disable above); args/return are typed via Parameters/ReturnType.
+  const stable = (...args: Parameters<T>): ReturnType<T> =>
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- T's return is `any` by the generic constraint above
+    ref.current(...args);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- generic wrapper → T: the call signature matches; T just can't be proven assignable
+  return useRef<T>(stable as T).current;
 };

lib/api-types.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { TraceEvent } from "@/lib/trace";
+
 /**
  * The typed wire contract for the streaming run endpoint, imported by BOTH the
  * route and the client so a shape change is a compile error on both sides (the
@@ -44,9 +46,21 @@ export type RunRequest = z.infer<typeof RunRequest>;
  */
 export const STREAM_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
 
-/** Terminal marker appended after the last trace event. */
-export type StreamDone = {
-  done: true;
+/** Terminal marker appended after the last trace event. A Zod schema so the client
+    validates it off the wire (no cast) the same way it parses each TraceEvent. */
+export const StreamDone = z.object({
+  done: z.literal(true),
   /** Total wall-clock duration of the run, ms. */
-  durationMs: number;
-};
+  durationMs: z.number(),
+});
+export type StreamDone = z.infer<typeof StreamDone>;
+
+/**
+ * One line of the NDJSON stream: either a trace event or the terminal done marker.
+ * One schema, parsed once; `isStreamDone` discriminates which arrived.
+ */
+export const StreamLine = z.union([TraceEvent, StreamDone]);
+export type StreamLine = z.infer<typeof StreamLine>;
+
+export const isStreamDone = (line: StreamLine): line is StreamDone =>
+  "done" in line;

lib/assert.ts

@@ -14,3 +14,20 @@ export const nonNull = <T>(value: T | null | undefined, why: string): T => {
   }
   return value;
 };
+
+/**
+ * Exhaustiveness guard for a discriminated union. Put it in the `default` of a
+ * switch (or the else of an if-chain): the parameter is typed `never`, so if a new
+ * variant is ever added without a branch, the TYPE CHECK fails — the bug is caught
+ * at compile time. If somehow reached at runtime, it throws clearly.
+ */
+export const assertUnreachable = (value: never): never => {
+  throw new Error(`Unreachable case: ${JSON.stringify(value)}`);
+};
+
+/**
+ * Type guard: a non-null object indexable by string. The honest narrowing of an
+ * `unknown`/`object` to a record so we can read fields off it WITHOUT an `as` cast.
+ */
+export const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null;

lib/fetch-json.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+
+import { isRecord } from "@/lib/assert";
+
+/**
+ * Typed POST → JSON for our own API routes. The `fetch` body is `any`; instead of
+ * asserting its shape (`res.json() as T`), we VALIDATE it against a Zod schema, so
+ * the type is earned at runtime — a malformed response fails loudly here, not as a
+ * mystery `undefined` three components deep.
+ *
+ * On a non-2xx response it reads `{ error }` (our routes' error shape) and throws
+ * `FetchJsonError` with that message + status, so callers show the server's reason.
+ */
+
+export class FetchJsonError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "FetchJsonError";
+  }
+}
+
+const errorMessage = (body: unknown, fallback: string): string => {
+  if (isRecord(body) && typeof body["error"] === "string") return body["error"];
+  return fallback;
+};
+
+/** POST `body` to `url`, parse the response with `schema`, return the typed value. */
+export const postJson = async <T>(
+  url: string,
+  schema: z.ZodType<T>,
+  body?: unknown,
+): Promise<T> => {
+  const res = await fetch(url, {
+    method: "POST",
+    headers:
+      body === undefined ? undefined : { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const json: unknown = await res.json().catch(() => null);
+  if (!res.ok) {
+    throw new FetchJsonError(
+      errorMessage(json, `Request failed (${res.status}).`),
+      res.status,
+    );
+  }
+  return schema.parse(json);
+};