@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/validate/render-js-syntax.ts

@@ -0,0 +1,188 @@
+/**
+ * scripts/validate/render-js-syntax.ts
+ * W12-02 (P7 / propose PR-050): Inline-JS syntax gate for RENDERED HTML.
+ *
+ * Data-shape gates (completeness-check, findings-contract) cannot catch
+ * interactivity-breaking JavaScript — a single asymmetric-escape in a template
+ * literal (W12-01: `/\r?\\n/` emitting a literal-CR regex) produces a
+ * SyntaxError that silently kills the whole live-preview IIFE, so check/uncheck
+ * + Copy go dead while every data gate still passes.
+ *
+ * This gate extracts every executable `<script>` body from a rendered HTML file
+ * and parses each with `new Function(body)` — which throws on SyntaxError
+ * WITHOUT executing the body (no DOM, no side effects). Non-executable scripts
+ * (external `src=`, `application/ld+json`, `text/plain` payloads) are skipped.
+ *
+ * Export: `checkRenderJsSyntax(html): RenderJsSyntaxResult` (pure function).
+ * CLI: `if (import.meta.main)` — exit 0 on all-parse, exit 1 + offending
+ *   script index/snippet on any parse error.
+ *
+ * Type A — Pure Script (deterministic; CLI file read only).
+ */
+
+// ── Result shapes ─────────────────────────────────────────────────────────────
+
+/** One inline-JS parse error, keyed to the script's position in the document. */
+export interface RenderJsSyntaxError {
+  /** 0-based index of the executable script among all parsed scripts. */
+  scriptIndex: number;
+  /** The SyntaxError message from `new Function`. */
+  message: string;
+  /** A short snippet of the offending body (first ~200 chars, single-lined). */
+  snippet: string;
+}
+
+/** Outcome of the inline-JS syntax gate. */
+export interface RenderJsSyntaxResult {
+  /** True when every executable `<script>` body parses. */
+  pass: boolean;
+  /** Count of executable `<script>` bodies that were parsed. */
+  scriptsChecked: number;
+  /** Parse errors (empty when pass). */
+  errors: RenderJsSyntaxError[];
+}
+
+// ── Script extraction ─────────────────────────────────────────────────────────
+
+/**
+ * `type` attribute values that mark a `<script>` as NON-executable data, not JS.
+ * These bodies are intentionally not valid JS (JSON-LD, plain-text payloads) and
+ * must NOT be parsed by this gate.
+ */
+const NON_JS_SCRIPT_TYPES: ReadonlySet<string> = new Set([
+  "application/ld+json",
+  "application/json",
+  "text/plain",
+  "text/template",
+  "text/html",
+]);
+
+/** Matches a whole `<script ...>...</script>` element (greedy-safe, non-nested). */
+const SCRIPT_ELEMENT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+/** Extracts a `src="..."` / `src='...'` attribute value. */
+const SRC_ATTR_RE = /\bsrc\s*=\s*["']([^"']*)["']/i;
+/** Extracts a `type="..."` / `type='...'` attribute value. */
+const TYPE_ATTR_RE = /\btype\s*=\s*["']([^"']*)["']/i;
+
+/**
+ * Extract every EXECUTABLE inline-script body from a rendered HTML string.
+ *
+ * Skips:
+ *   - external scripts (`<script src=...>`) — no inline body to parse
+ *   - data scripts (`type` in NON_JS_SCRIPT_TYPES) — intentionally non-JS
+ *   - empty / whitespace-only bodies
+ *
+ * Returns the bodies in document order.
+ */
+export function extractInlineScriptBodies(html: string): string[] {
+  const bodies: string[] = [];
+  SCRIPT_ELEMENT_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = SCRIPT_ELEMENT_RE.exec(html)) !== null) {
+    const attrs = match[1] ?? "";
+    const body = match[2] ?? "";
+
+    // External script — no inline body to parse.
+    if (SRC_ATTR_RE.test(attrs)) continue;
+
+    // Non-executable data script (JSON-LD, text/plain payload, etc.).
+    const typeMatch = TYPE_ATTR_RE.exec(attrs);
+    if (typeMatch) {
+      const declaredType = typeMatch[1].trim().toLowerCase();
+      // Anything that isn't an explicit JS module/classic type is treated as
+      // data when it appears in the NON_JS set; module/text-javascript fall
+      // through to be parsed.
+      if (NON_JS_SCRIPT_TYPES.has(declaredType)) continue;
+    }
+
+    if (body.trim().length === 0) continue;
+
+    bodies.push(body);
+  }
+  return bodies;
+}
+
+// ── Gate ──────────────────────────────────────────────────────────────────────
+
+/** Single-line, length-bounded snippet for error reporting. */
+function snippetOf(body: string): string {
+  const flat = body.replace(/\s+/g, " ").trim();
+  return flat.length > 200 ? `${flat.slice(0, 200)}…` : flat;
+}
+
+/**
+ * W12-02: Parse every executable inline-script body in a rendered HTML document.
+ * Pure function — same input, same output. Uses `new Function(body)` which
+ * throws on SyntaxError WITHOUT executing the body.
+ */
+export function checkRenderJsSyntax(html: string): RenderJsSyntaxResult {
+  const bodies = extractInlineScriptBodies(html);
+  const errors: RenderJsSyntaxError[] = [];
+
+  bodies.forEach((body, scriptIndex) => {
+    try {
+      // `new Function(body)` parses the body and throws on SyntaxError WITHOUT
+      // executing it (no call site) — exactly the parse-only check we want.
+      new Function(body);
+    } catch (err) {
+      errors.push({
+        scriptIndex,
+        message: err instanceof Error ? err.message : String(err),
+        snippet: snippetOf(body),
+      });
+    }
+  });
+
+  return {
+    pass: errors.length === 0,
+    scriptsChecked: bodies.length,
+    errors,
+  };
+}
+
+// ── CLI entrypoint ─────────────────────────────────────────────────────────────
+
+if (import.meta.main) {
+  const { readFileSync } = await import("fs");
+  const { resolve } = await import("path");
+
+  const argv = process.argv.slice(2);
+  const htmlPath = argv[0];
+
+  if (!htmlPath) {
+    process.stderr.write(
+      "Usage: bun scripts/validate/render-js-syntax.ts <rendered-report.html>\n" +
+        "\n" +
+        "Parses every executable inline <script> body in a rendered HTML report\n" +
+        "(via new Function — no execution). Exit 0 = all parse, Exit 1 = SyntaxError.\n"
+    );
+    process.exit(1);
+  }
+
+  let html: string;
+  try {
+    html = readFileSync(resolve(htmlPath), "utf8");
+  } catch (err) {
+    process.stderr.write(`Error reading ${htmlPath}: ${err}\n`);
+    process.exit(1);
+  }
+
+  const result = checkRenderJsSyntax(html);
+
+  if (result.pass) {
+    process.stdout.write(
+      `[render-js-syntax] PASS — ${result.scriptsChecked} inline script(s) parse cleanly.\n`
+    );
+    process.exit(0);
+  } else {
+    process.stderr.write(
+      `[render-js-syntax] FAIL — ${result.errors.length} inline script(s) failed to parse ` +
+        `(of ${result.scriptsChecked} checked):\n`
+    );
+    result.errors.forEach((e) => {
+      process.stderr.write(`  script #${e.scriptIndex}: ${e.message}\n`);
+      process.stderr.write(`    ${e.snippet}\n`);
+    });
+    process.exit(1);
+  }
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/validate/report-checklist.yaml

@@ -0,0 +1,217 @@
+# scripts/validate/report-checklist.yaml
+# W14 (F1) — OUTPUT-side finalization checklist.
+#
+# WHAT THIS IS
+#   A declarative, one-row-per-section completeness contract for the *rendered*
+#   `report.html` string. The INPUT side is already gated by
+#   `scripts/validate/completeness-check.ts` (RenderInput JSON, the D-6 render-contract
+#   pass). THIS file drives the OUTPUT side: `scripts/validate/finalize-gate.ts` parses
+#   the produced HTML and asserts, per section, that the data actually LANDED in the
+#   document — catching the bug class where the renderer emitted a soft fallback
+#   (`RANK n/a`, `cost:n/a`), a raw `undefined`/`NaN`, a raw-JSON entity prompt, or an
+#   internal node that survived the client strip.
+#
+# WHY DETERMINISTIC-ONLY
+#   No LLM, no spend, runs every render. DOM/regex/string assertions only (operator
+#   decision 2). Each row is a pure predicate over the HTML body.
+#
+# SELF-HEAL (operator decision 3)
+#   Each row carries `source` (the producer to backtrace to — from
+#   references/script-index.md, the backtrace table) and `heal` (the re-run action).
+#   On a CRIT gap the orchestrator (Step 9.9) backtraces via `source`, re-runs that
+#   producer, re-builds render-input, re-renders, and re-checks. Bounded: max 2 rounds,
+#   then escalate LOUD. NEVER infinite-loop, NEVER silently emit an incomplete report.
+#
+# SCHEMA (per row)
+#   section : stable id (one of the section ids below)
+#   require : tokens/markers that MUST be present AND non-empty in the section's HTML
+#   forbid  : tokens that MUST NOT appear (e.g. 'undefined', 'NaN', 'RANK n/a')
+#   tier    : CRIT (blocks "done") | WARN (loud banner, still emit)
+#   okEmpty : a condition string naming WHEN absence is LEGITIMATE (prevents false-block)
+#   source  : the producer/step to backtrace to (matches script-index.md `Step` column)
+#   heal    : the self-heal action to run when this row's data is missing
+#
+# SCOPING NOTE (forbid tokens)
+#   `forbid` scanning runs over the rendered body with <code>, <pre>, and diff blocks
+#   (.r-diff-grid) STRIPPED first — those legitimately contain literal `undefined` /
+#   `NaN` / `{"prompt"` as quoted evidence/diff content. The finalize-gate strips them
+#   before applying body-level forbids; section-scoped forbids run on the section slice
+#   with the same strip.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# GLOBAL CRIT ROWS — whole-body invariants (operator decision F1: "Global CRIT rows")
+# ─────────────────────────────────────────────────────────────────────────────
+
+# SD-8: `null` is scoped to STRUCTURAL slots only. The finalize-gate forbid scan is a
+# literal substring match (`surface.includes(token)`), so a bare `null` token CRIT-fails
+# on prose like "the tool returned null" — observability-hygiene language, not a render
+# bug. `undefined`/`NaN` keep their bare form (they never appear in legitimate prose).
+# For `null` we instead enumerate the token flanked by each structural delimiter
+# (`>` `<` `:` `,` `=` `"`) on either side, so a structural-slot leak (text node
+# `>null<`, JSON `:null,`, attribute `="null"`) still fires while a prose mention does
+# not. Inline JS / <pre> / <code> are already stripped before the scan (stripQuotedRegions).
+- section: global-no-undefined
+  require: []
+  forbid:
+    - "undefined"
+    - "NaN"
+    # `null` in a structural slot — flanked by a structural delimiter on either side.
+    - ">null"
+    - "null<"
+    - ":null"
+    - "null:"
+    - ",null"
+    - "null,"
+    - "=null"
+    - "null="
+    - '"null'
+    - 'null"'
+    - "<null"
+    - "null>"
+  tier: CRIT
+  okEmpty: never
+  source: "8.5 build-render-input.ts (enricher backfills the field a producer forgot)"
+  heal: "re-run Step 8.5 enrich → re-render → re-check (the literal is a forgotten field; the enricher is the backfill point)"
+
+- section: global-client-no-internal
+  require: []
+  # When audience=client, the renderer must emit ZERO internal nodes (it builds them
+  # as "" — NODE-STRIP by omission). Any surviving internal marker is a leak.
+  forbid: ['class="internal"', 'class="internal-banner"', 'class="internal active"', "Methodology [INTERNAL]", "INTERNAL-ONLY"]
+  tier: CRIT
+  okEmpty: "audience=internal (internal reports legitimately carry these nodes)"
+  source: "9 render.ts (audience gate — methodologyPanelHtml/internalBannerHtml must be '' for client)"
+  heal: "re-render with the resolved audience (Step 9 --audience); a client leak means audience was mis-resolved — re-run resolveEffectiveAudience and re-render"
+
+- section: global-remedy-triad
+  require: []
+  # Every remedy header badge triad must be real, not the badgeField() 'n/a' fallback.
+  forbid: ["RANK n/a", "cost:n/a", "correct:n/a", "cost:undefined", "RANK undefined", "b-cost-na"]
+  tier: CRIT
+  okEmpty: "no findings (clean run — no remedy cards exist)"
+  source: "8.5 rank-remedies.ts (enricher derives rank from cost×correctness; cost/correctness are analyzer-supplied, gated at Step 7.1)"
+  heal: "re-run Step 7.1 findings-contract → Step 8.5 rank-remedies → re-render (missing rank/cost/correctness on a remedy)"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PER-SECTION ROWS
+# ─────────────────────────────────────────────────────────────────────────────
+
+- section: entity-card
+  require: ['class="entity"', "DIAGNOSED ENTITY", "Type"]
+  # Entity prompt must be humanized prose, never a raw analyzer JSON blob.
+  forbid: ['{"prompt"', '{"messages"', '"role":"system"']
+  tier: CRIT
+  # The entity card lives in the Overview tab, only built on findings-bearing runs
+  # (mirrors completeness-check.ts: zero-finding runs are exempt from section checks).
+  okEmpty: "no findings (entity card only built on findings-bearing runs)"
+  source: "3.7 normalize/platforms/*.ts → EntityContext (deterministic extraction, no LLM)"
+  heal: "re-run Step 3.7 normalize (--out-entity) → Step 8.5a build EntityContext → re-render (entity card starved or prompt not humanized)"
+
+- section: big-stat
+  require: ['class="big-stat"', 'class="s"']
+  forbid: ["undefined", "NaN"]
+  tier: CRIT
+  okEmpty: "no findings (Overview big-stat row only built on findings-bearing runs)"
+  source: "8.5 build-render-input.ts (derives the 6-tile bigStat from tier0 + deepRead)"
+  heal: "re-run Step 8.5 enrich (bigStat derivation) → re-render"
+
+- section: deep-read-tile
+  require: ['class="deep-read-tile"', "coverage confidence"]
+  forbid: ["undefined", "NaN"]
+  tier: WARN
+  okEmpty: "runMeta.deepRead absent (pre-Wave-9 / backward-compat run — tile omitted)"
+  source: "6 deep-read-gate.ts → runMeta.deepRead (escalation telemetry)"
+  heal: "re-run Step 6 deep-read-gate → assign runMeta.deepRead → re-render"
+
+- section: signal-census
+  require: ["Signal / failure-mode", "Present?", "Measure", "Decision"]
+  forbid: ["undefined", "NaN"]
+  tier: CRIT
+  okEmpty: "no findings (census table only built on findings-bearing runs)"
+  source: "8.5 build-render-input.ts (signal-census reconciliation from tier0 + primarySignal)"
+  heal: "re-run Step 8.5 enrich (signal census) → re-render"
+
+- section: heatmap
+  require: ['class="heat"', "timeline heatmap"]
+  forbid: ["undefined", "NaN"]
+  tier: WARN
+  okEmpty: "no findings OR methodologyAudit (no runtime traces → no latency heatmap)"
+  source: "8.5 build-render-input.ts (24h heatmap from trace timestamps)"
+  heal: "re-run Step 8.5 enrich (heatmap derivation) → re-render"
+
+- section: funnel
+  require: ['class="funnel"']
+  forbid: ["undefined", "NaN"]
+  tier: WARN
+  okEmpty: "scanFunnel absent (backward-compat — funnel falls back to 3-segment or omits)"
+  source: "5 slicer.ts / representative.ts → scanFunnel (total→tier0→sample→deep-read)"
+  heal: "re-run Step 5 sampling → assign scanFunnel → re-render"
+
+- section: finding-panel
+  # Finding panels carry the WHAT/WHY/WHERE taxonomy strip + a Problem block.
+  require: ['class="taxonomy"', "WHAT", "Problem"]
+  forbid: ["undefined", "NaN"]
+  tier: CRIT
+  okEmpty: "0 findings on a clean run (legitimate zero-finding diagnosis — no panels expected)"
+  source: "6 analyzer dispatch → 7 aggregate/sort-findings.ts → Finding[]"
+  heal: "re-run Step 6 analyzer dispatch → Step 7 aggregate → Step 8.5 enrich → re-render (findings lost between aggregate and render)"
+
+- section: remedy-card
+  # NB: `class="remedy` (no closing quote) matches both `class="remedy"` and the
+  # recommended-variant `class="remedy recommended"`.
+  require: ['class="remedy', "rank-pill", "remedy-meta"]
+  forbid: ["RANK n/a", "cost:n/a", "correct:n/a", "RANK undefined"]
+  tier: CRIT
+  okEmpty: "no findings (no remedy cards on a clean run)"
+  source: "8.5 rank-remedies.ts (rank derived) + Step 7.1 findings-contract (cost/correctness present)"
+  heal: "re-run Step 7.1 findings-contract → Step 8.5 rank-remedies → re-render"
+
+# ── Methodology sub-sections (INTERNAL audience only) ────────────────────────
+# These rows are scoped to the Methodology [INTERNAL] tab. They are evaluated ONLY
+# when audience=internal (okEmpty covers the client case — the whole tab is stripped).
+# The renderer emits a LOUD `loud-missing-widget` marker when a widget's data was not
+# threaded into runMeta; that marker is itself a CRIT forbid (a forgotten-data tell).
+
+- section: methodology-tier-pie
+  require: []
+  forbid: ['data-widget="tier-coverage pie (tierBreakdown)"']
+  tier: CRIT
+  okEmpty: "audience=client (Methodology tab stripped) OR runMeta.tierBreakdown threaded (widget rendered, no loud marker)"
+  source: "8.5 build-render-input.ts F4 widget-threading → runMeta.tierBreakdown"
+  heal: "thread runMeta.tierBreakdown at Step 8.5 (F4 table) → re-render"
+
+- section: methodology-selection
+  require: []
+  forbid: ['data-widget="signal-selection trace (signalSelectionTrace)"']
+  tier: CRIT
+  okEmpty: "audience=client OR runMeta.signalSelectionTrace threaded"
+  source: "8.5 build-render-input.ts F4 widget-threading → runMeta.signalSelectionTrace / selectionRules"
+  heal: "thread runMeta.signalSelectionTrace + selectionRules at Step 8.5 (F4 table) → re-render"
+
+- section: methodology-awareness
+  require: []
+  forbid: ['data-widget="awareness sample + blind-spots"']
+  tier: CRIT
+  okEmpty: "audience=client OR awareness threaded OR awareness SKIPPED under documented exemption (library priors)"
+  source: "3.5 awareness/llm-sample.ts + blind-spots.ts → runMeta.awarenessSample / blindSpots"
+  heal: "re-run Step 3.5 awareness → assign runMeta.awarenessSample + blindSpots at Step 8.5 → re-render"
+
+- section: methodology-blind-spots
+  require: []
+  # blind-spots share the awareness widget marker; kept as a distinct row so a gap
+  # backtraces to the blind-spots producer specifically.
+  forbid: ['data-widget="awareness sample + blind-spots"']
+  tier: WARN
+  okEmpty: "audience=client OR blindSpots threaded OR awareness SKIPPED (priors)"
+  source: "3.5 awareness/blind-spots.ts → runMeta.blindSpots"
+  heal: "re-run Step 3.5 blind-spots → assign runMeta.blindSpots at Step 8.5 → re-render"
+
+# ── Decisions / copy-back tab (always emitted) ───────────────────────────────
+
+- section: decisions-copyback
+  require: ["Decisions", 'id="lp-body"', 'id="general-feedback"']
+  forbid: ["undefined", "NaN"]
+  tier: CRIT
+  okEmpty: never
+  source: "9 render.ts renderDecisionsTab + renderLivePreviewScript (copy-back HITL surface — PR-014)"
+  heal: "re-render (the Decisions tab is template-stamped; absence means a render/template regression — re-run Step 9 render)"

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/validate/trace-shape.ts

@@ -0,0 +1,262 @@
+/**
+ * scripts/validate/trace-shape.ts
+ * F-SELF-08: Validate that raw trace data conforms to TraceMetadata shape before
+ * feeding into tier0-scan or per-platform normalizers.
+ *
+ * This is NOT a normalizer — it validates that objects already normalized by a
+ * per-platform module (or manually constructed) meet the structural contract
+ * required by the rest of the diagnostics pipeline.
+ *
+ * Usage: bun scripts/cli/run.sh scripts/validate/trace-shape.ts <traces.json>
+ *
+ * Exit 0 = all traces valid.
+ * Exit 1 = one or more traces have structural violations (details on stderr).
+ *
+ * Type A — Pure Script (deterministic, no I/O except argument file)
+ */
+
+import { readFileSync } from "fs";
+import type { TraceMetadata } from "../normalize/trace.ts";
+
+export interface TraceShapeViolation {
+  traceIndex: number;
+  traceId?: string;
+  field: string;
+  message: string;
+}
+
+export interface TraceShapeResult {
+  valid: boolean;
+  totalTraces: number;
+  invalidCount: number;
+  violations: TraceShapeViolation[];
+}
+
+/**
+ * Validate a single trace object against the TraceMetadata structural contract.
+ * Returns a list of violations (empty = valid).
+ */
+export function validateTraceShape(
+  raw: unknown,
+  index: number
+): TraceShapeViolation[] {
+  const violations: TraceShapeViolation[] = [];
+
+  // Must be a non-null object
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    violations.push({
+      traceIndex: index,
+      field: "(root)",
+      message: `Expected object, got ${Array.isArray(raw) ? "array" : typeof raw}`,
+    });
+    return violations; // No point checking fields on non-objects
+  }
+
+  const t = raw as Record<string, unknown>;
+
+  // ── Required fields ────────────────────────────────────────────────────────
+
+  if (typeof t.traceId !== "string" || t.traceId.trim() === "") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "traceId",
+      message: "Required string field is missing or empty",
+    });
+  }
+
+  if (typeof t.sessionId !== "string" || t.sessionId.trim() === "") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "sessionId",
+      message: "Required string field is missing or empty",
+    });
+  }
+
+  if (typeof t.hasError !== "boolean") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "hasError",
+      message: `Required boolean field is ${t.hasError === undefined ? "missing" : `type "${typeof t.hasError}"`}`,
+    });
+  }
+
+  if (typeof t.hasFeedback !== "boolean") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "hasFeedback",
+      message: `Required boolean field is ${t.hasFeedback === undefined ? "missing" : `type "${typeof t.hasFeedback}"`}`,
+    });
+  }
+
+  const validPlatforms = new Set(["langfuse", "otel", "local-jsonl", "claude-code", "codex"]);
+  if (typeof t.sourcePlatform !== "string" || !validPlatforms.has(t.sourcePlatform)) {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "sourcePlatform",
+      message: `Expected one of ${[...validPlatforms].join(", ")}, got ${JSON.stringify(t.sourcePlatform)}`,
+    });
+  }
+
+  // ── Optional fields — type-check only if present ───────────────────────────
+
+  if (t.latencyMs !== undefined && typeof t.latencyMs !== "number") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "latencyMs",
+      message: `Optional field present but wrong type: expected number, got "${typeof t.latencyMs}"`,
+    });
+  }
+
+  if (t.rawScore !== undefined && typeof t.rawScore !== "number") {
+    violations.push({
+      traceIndex: index,
+      traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+      field: "rawScore",
+      message: `Optional field present but wrong type: expected number, got "${typeof t.rawScore}"`,
+    });
+  }
+
+  if (t.normalizedScore !== undefined) {
+    if (typeof t.normalizedScore !== "number") {
+      violations.push({
+        traceIndex: index,
+        traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+        field: "normalizedScore",
+        message: `Optional field present but wrong type: expected number, got "${typeof t.normalizedScore}"`,
+      });
+    } else if (t.normalizedScore < 0 || t.normalizedScore > 1) {
+      violations.push({
+        traceIndex: index,
+        traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+        field: "normalizedScore",
+        message: `normalizedScore must be in [0, 1], got ${t.normalizedScore}`,
+      });
+    }
+  }
+
+  if (t.tags !== undefined) {
+    if (!Array.isArray(t.tags)) {
+      violations.push({
+        traceIndex: index,
+        traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+        field: "tags",
+        message: `Optional field present but wrong type: expected string[], got "${typeof t.tags}"`,
+      });
+    } else if (t.tags.some((tag: unknown) => typeof tag !== "string")) {
+      violations.push({
+        traceIndex: index,
+        traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+        field: "tags",
+        message: "tags array contains non-string elements",
+      });
+    }
+  }
+
+  // R-SELF-06-a: validate apiErrors shape if present
+  if (t.apiErrors !== undefined) {
+    if (!Array.isArray(t.apiErrors)) {
+      violations.push({
+        traceIndex: index,
+        traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+        field: "apiErrors",
+        message: `Expected array, got "${typeof t.apiErrors}"`,
+      });
+    } else {
+      for (let i = 0; i < t.apiErrors.length; i++) {
+        const e = t.apiErrors[i] as Record<string, unknown>;
+        if (typeof e.retryAttempt !== "number") {
+          violations.push({
+            traceIndex: index,
+            traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+            field: `apiErrors[${i}].retryAttempt`,
+            message: `Expected number, got "${typeof e.retryAttempt}"`,
+          });
+        }
+        if (typeof e.maxRetries !== "number") {
+          violations.push({
+            traceIndex: index,
+            traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+            field: `apiErrors[${i}].maxRetries`,
+            message: `Expected number, got "${typeof e.maxRetries}"`,
+          });
+        }
+        if (typeof e.timestamp !== "string") {
+          violations.push({
+            traceIndex: index,
+            traceId: typeof t.traceId === "string" ? t.traceId : undefined,
+            field: `apiErrors[${i}].timestamp`,
+            message: `Expected string, got "${typeof e.timestamp}"`,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Validate an array of raw trace objects.
+ * Returns a summary result with all violations.
+ */
+export function validateTraceShapes(raws: unknown[]): TraceShapeResult {
+  const allViolations: TraceShapeViolation[] = [];
+  for (let i = 0; i < raws.length; i++) {
+    const v = validateTraceShape(raws[i], i);
+    allViolations.push(...v);
+  }
+  const invalidSet = new Set(allViolations.map((v) => v.traceIndex));
+  return {
+    valid: allViolations.length === 0,
+    totalTraces: raws.length,
+    invalidCount: invalidSet.size,
+    violations: allViolations,
+  };
+}
+
+/**
+ * Guard: throws if any violations found. Useful at normalizer output boundaries.
+ */
+export function assertTraceShapes(traces: unknown[]): asserts traces is TraceMetadata[] {
+  const result = validateTraceShapes(traces);
+  if (!result.valid) {
+    const lines = result.violations.map(
+      (v) => `  [trace #${v.traceIndex}${v.traceId ? ` (${v.traceId})` : ""}] ${v.field}: ${v.message}`
+    );
+    throw new Error(`TraceMetadata shape validation failed (${result.invalidCount} invalid traces):\n${lines.join("\n")}`);
+  }
+}
+
+// CLI entrypoint
+if (import.meta.main) {
+  const inputPath = process.argv[2];
+  if (!inputPath) {
+    process.stderr.write("Usage: bun scripts/cli/run.sh scripts/validate/trace-shape.ts <traces.json>\n");
+    process.exit(1);
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(inputPath, "utf8"));
+    if (!Array.isArray(raw)) {
+      process.stderr.write("Error: input file must contain a JSON array\n");
+      process.exit(1);
+    }
+    const result = validateTraceShapes(raw);
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    if (!result.valid) {
+      process.stderr.write(`Validation failed: ${result.invalidCount}/${result.totalTraces} traces have violations\n`);
+      process.exit(1);
+    }
+    process.stderr.write(`Validation passed: ${result.totalTraces} traces OK\n`);
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Error: ${err}\n`);
+    process.exit(1);
+  }
+}