pome-sh 0.6.6

package/node_modules/@pome-sh/shared-types/src/otel/span-event.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * otel/span-event — the `OtelSpanEvent` Zod schema (M1.1 / FDRS-480).
+ *
+ * The canonical internal representation of a single OpenTelemetry span, mapped
+ * onto Pome's event union. From M1 on, OTel spans are the canonical model;
+ * legacy `TwinHttpEvent` / `LlmCallEvent` / `ToolUseEvent` rows are shimmed *up*
+ * into this shape (M1.2). `OtelSpanEvent` is a non-breaking `kind` extension of
+ * the event union (composed in `./event-schema.ts`, cloud-only).
+ *
+ * Invariants enforced (review finding #4 — the schema was too weak):
+ *   - `*_unix_nano` are uint64 decimal strings WITHIN range (no overflow that
+ *     could throw a RangeError downstream).
+ *   - IDs are real W3C trace context (32-/16-char lowercase hex, non-zero) OR
+ *     an explicit `legacy:<source-id>` (the shim's namespace). Nothing else.
+ *   - `end_time_unix_nano >= start_time_unix_nano` (no reversed spans).
+ *   - `event_id === span_id` and `parent_id === parent_span_id` (the base
+ *     event-union chain mirrors span context).
+ *   - `ts` is exactly `nanosToIso(start_time_unix_nano)`.
+ *   - the typed `gen_ai_*` / `http_*` / `url_*` / `server_*` / `error_type`
+ *     fields EQUAL `projectAttributes(attributes)` — they are projections of
+ *     the verbatim bag and cannot drift from it.
+ *
+ * Field conventions: snake_case, flat. `attributes` holds the FULL verbatim
+ * attribute bag; the typed fields above are projections of it (see `project.ts`).
+ */
+
+import { z } from "zod";
+
+import { compareUint64, isUint64, nanosToIso } from "./nano.js";
+import {
+  OTEL_PROJECTION_KEYS,
+  otelAttributeValueSchema,
+  projectAttributes,
+} from "./project.js";
+
+// OTel SpanKind, by name. OTLP encodes these as ints 0–5; the mapper normalizes
+// numeric input onto these names. Order matches the OTLP enum (index == int).
+export const OTEL_SPAN_KINDS = [
+  "UNSPECIFIED",
+  "INTERNAL",
+  "SERVER",
+  "CLIENT",
+  "PRODUCER",
+  "CONSUMER",
+] as const;
+export const otelSpanKindSchema = z.enum(OTEL_SPAN_KINDS);
+export type OtelSpanKind = z.infer<typeof otelSpanKindSchema>;
+
+// OTel status code, by name. OTLP encodes these as ints 0–2 (index == int).
+export const OTEL_STATUS_CODES = ["UNSET", "OK", "ERROR"] as const;
+export const otelStatusCodeSchema = z.enum(OTEL_STATUS_CODES);
+export type OtelStatusCode = z.infer<typeof otelStatusCodeSchema>;
+
+// uint64 nanoseconds-since-epoch as a decimal string, WITHIN the uint64 range.
+export const unixNanoSchema = z
+  .string()
+  .refine(isUint64, "expected a uint64 decimal string (unix nanoseconds) within range");
+
+// ── W3C trace-context identifiers ────────────────────────────────────────────
+// Real OTel IDs are lowercase hex, fixed-width, and never all-zero (the
+// all-zero id is the "invalid" sentinel). The shim namespaces non-OTel legacy
+// ids as `legacy:<source-id>` so a stored span always declares its provenance.
+const NON_ZERO = (hex: string) => /[1-9a-f]/.test(hex);
+export const w3cTraceIdSchema = z
+  .string()
+  .regex(/^[0-9a-f]{32}$/, "expected a 32-char lowercase-hex W3C trace id")
+  .refine(NON_ZERO, "trace id must not be all-zero");
+export const w3cSpanIdSchema = z
+  .string()
+  .regex(/^[0-9a-f]{16}$/, "expected a 16-char lowercase-hex W3C span id")
+  .refine(NON_ZERO, "span id must not be all-zero");
+const legacyIdSchema = z
+  .string()
+  .regex(/^legacy:.+$/, "expected a `legacy:<source-id>` namespaced id");
+
+// A canonical stored id: either real W3C trace context or an explicit
+// `legacy:` id. Used for the `OtelSpanEvent` (which may originate from the shim).
+export const canonicalTraceIdSchema = z.union([w3cTraceIdSchema, legacyIdSchema]);
+export const canonicalSpanIdSchema = z.union([w3cSpanIdSchema, legacyIdSchema]);
+
+const otelSpanEventObjectSchema = z.object({
+  // ── shared event-union base (mirrors `eventBaseShape` in recorder-events.ts) ─
+  ts: z.string().datetime(),
+  event_id: canonicalSpanIdSchema,
+  parent_id: canonicalSpanIdSchema.nullable(),
+  kind: z.literal("OtelSpanEvent"),
+
+  // ── W3C trace context — real span parentage (M3 correlation reads these) ────
+  trace_id: canonicalTraceIdSchema,
+  span_id: canonicalSpanIdSchema,
+  parent_span_id: canonicalSpanIdSchema.nullable(),
+
+  // ── span identity / timing / status ────────────────────────────────────────
+  name: z.string().min(1),
+  span_kind: otelSpanKindSchema,
+  start_time_unix_nano: unixNanoSchema,
+  end_time_unix_nano: unixNanoSchema.nullable(),
+  status_code: otelStatusCodeSchema,
+  status_message: z.string().nullable(),
+
+  // ── GenAI projections (flat; null when the span lacks the attribute) ────────
+  gen_ai_provider_name: z.string().nullable(),
+  gen_ai_operation_name: z.string().nullable(),
+  gen_ai_request_model: z.string().nullable(),
+  gen_ai_agent_name: z.string().nullable(),
+  gen_ai_agent_id: z.string().nullable(),
+  gen_ai_tool_name: z.string().nullable(),
+  gen_ai_usage_input_tokens: z.number().int().min(0).nullable(),
+  gen_ai_usage_output_tokens: z.number().int().min(0).nullable(),
+
+  // ── HTTP / core projections (flat; null when the span lacks the attribute) ──
+  http_request_method: z.string().nullable(),
+  http_response_status_code: z.number().int().nullable(),
+  url_full: z.string().nullable(),
+  url_path: z.string().nullable(),
+  server_address: z.string().nullable(),
+  server_port: z.number().int().min(0).nullable(),
+  error_type: z.string().nullable(),
+
+  // ── full, verbatim attribute bag (lossless; typed fields project from this) ─
+  attributes: z.record(z.string(), otelAttributeValueSchema),
+});
+
+export const otelSpanEventSchema = otelSpanEventObjectSchema.superRefine((event, ctx) => {
+  // Base-union chain mirrors span context.
+  if (event.event_id !== event.span_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["event_id"],
+      message: "event_id must equal span_id",
+    });
+  }
+  if (event.parent_id !== event.parent_span_id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["parent_id"],
+      message: "parent_id must equal parent_span_id",
+    });
+  }
+
+  // `ts` is the human-sortable mirror of the span start time.
+  if (event.ts !== nanosToIso(event.start_time_unix_nano)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["ts"],
+      message: "ts must equal nanosToIso(start_time_unix_nano)",
+    });
+  }
+
+  // No reversed spans.
+  if (
+    event.end_time_unix_nano !== null &&
+    compareUint64(event.end_time_unix_nano, event.start_time_unix_nano) < 0
+  ) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["end_time_unix_nano"],
+      message: "end_time_unix_nano must be >= start_time_unix_nano",
+    });
+  }
+
+  // Projection-drift guard: typed fields must equal the attribute bag's
+  // projection. The mapper and shim both build them via `projectAttributes`,
+  // so a mismatch means a hand-constructed (or corrupted) event.
+  const projected = projectAttributes(event.attributes);
+  for (const key of OTEL_PROJECTION_KEYS) {
+    if (event[key] !== projected[key]) {
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: `${key} must equal projectAttributes(attributes).${key}`,
+      });
+    }
+  }
+});
+export type OtelSpanEvent = z.infer<typeof otelSpanEventObjectSchema>;

package/node_modules/@pome-sh/shared-types/src/recorder-events.ts

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * recorder-events — twin runtime trace format
+ *
+ * Single source of truth for the per-request event a twin runtime emits into
+ * its recorder ring buffer. Consumed by:
+ *   - twin runtimes (`@pome-sh/twin-github`, `@pome-sh/twin-stripe`) — emit shape
+ *   - `@pome-sh/sdk` — read shape for post-run analysis
+ *   - `@pome-sh/correlator` — input to `correlateAdapterRich` / `correlateHeuristic`
+ *   - `pome-cloud` recorder writers — persisted shape for events.jsonl S3 blob
+ *
+ * v1.0 freeze of the twin runtime trace format. Breaking changes go through a
+ * documented deprecation policy.
+ */
+
+import { z } from "zod";
+
+// `twin` is an open string at the schema level so SDK-based community twins
+// can set their own id without forcing a shared-types schema bump. Dashboard
+// rendering pattern-matches against `KNOWN_TWIN_IDS` and falls back to
+// generic rendering for unknown values — losing a recording to parse failure
+// would be worse than rendering it generically. First-party twins SHOULD use
+// the canonical values for type-aware UI.
+export const KNOWN_TWIN_IDS = ["github", "stripe", "slack"] as const;
+export type KnownTwinId = (typeof KNOWN_TWIN_IDS)[number];
+
+export const twinIdSchema = z.string().min(1);
+export type TwinId = z.infer<typeof twinIdSchema>;
+
+export const recorderFidelitySchema = z.enum(["semantic", "unsupported"]);
+export type RecorderFidelity = z.infer<typeof recorderFidelitySchema>;
+
+// stateDelta captures the row-level before/after for a mutation. State-inspector
+// renders these as a key/value diff. `before: null` = row was inserted (no prior
+// state); `after: null` = row was deleted. Parent `null` = no mutation (read-only
+// call — should also have `state_mutation: false`). Per-twin types are NOT
+// enforced — each twin owns its row shape, and forcing a strong type here would
+// couple shared-types to twin schemas.
+export const stateDeltaSchema = z
+  .object({
+    before: z.record(z.string(), z.unknown()).nullable(),
+    after: z.record(z.string(), z.unknown()).nullable(),
+  })
+  .nullable();
+export type StateDelta = z.infer<typeof stateDeltaSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Legacy single-shape recorder event (pre-FDRS-398).
+//
+// Kept exported as-is for the 58 callers across twin runtimes, SDK, correlator,
+// CLI, and cloud control plane that still emit/consume this shape on disk.
+// Their migration to the unified discriminated-union `eventSchema` below is
+// owned by downstream M0 tickets (FDRS-402 / 403 / 412 / 415 / 417).
+// `isLegacyEventRow` lets readers detect this shape during the rollout.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Internal plain-object shape. Kept as a `ZodObject` so `twinHttpEventSchema`
+// can `.extend` it and stay a discriminated-union member; the exported
+// `recorderEventSchema` wraps it with the FDRS-653 task-vocab normalization.
+const recorderEventObjectSchema = z.object({
+  ts: z.string().datetime(),
+  run_id: z.string().min(1),
+  twin: twinIdSchema,
+  request_id: z.string().min(1),
+  correlation_id: z.string().min(1).optional(),
+  // task_step_id is set by the task author in .yaml (static expectation:
+  // "this HTTP call is expected at step 2"). step_id below is set post-hoc by
+  // the correlator (dynamic grouping: "this event landed in Step stp_xyz").
+  // 90% of events use only one; both can coexist.
+  //
+  // W3 vocab (FDRS-653): `task_step_id` is canonical; `scenario_step_id` is
+  // the 0.3.0-era spelling. BOTH stay in the schema for the tolerant-reader
+  // window — this row shape is the frozen v1 trace format and its emitters
+  // (twin runtimes, shipped CLIs on vendored 0.3.0) still write the old key.
+  // The exported reader schemas normalize: when only `scenario_step_id` is
+  // present, `task_step_id` is populated from it at parse time. New emitters
+  // write `task_step_id`.
+  task_step_id: z.string().min(1).nullable().optional(),
+  scenario_step_id: z.string().min(1).nullable().optional(),
+  step_id: z.string().nullable(),
+  // tool_call_id is set by the `@pome-sh/adapter-claude-sdk` adapter when active.
+  // Null for the heuristic-correlator path (no adapter signal available).
+  tool_call_id: z.string().nullable(),
+  method: z.string().min(1),
+  path: z.string(),
+  request_body: z.unknown(),
+  status: z.number().int(),
+  response_body: z.unknown(),
+  latency_ms: z.number().int().min(0),
+  fidelity: recorderFidelitySchema,
+  state_mutation: z.boolean(),
+  state_delta: stateDeltaSchema,
+  // True iff the twin's idempotency layer replayed a cached response without
+  // re-invoking the handler. Optional + additive so existing recordings parse
+  // unchanged; dashboards/SDKs can render dedupe hits distinctly without
+  // inferring from request_body. Absent on the original mutation, present and
+  // true on the replayed event.
+  idempotency_dedupe: z.boolean().optional(),
+  error: z.string().nullable(),
+});
+
+// FDRS-653 tolerant reader: populate the canonical `task_step_id` from the
+// 0.3.0-era `scenario_step_id` when only the old key was written. The old key
+// is preserved as-sent (additive normalization — a re-serialized row still
+// parses under a 0.3.0 reader, which treats both keys as optional).
+function normalizeTaskStepVocab<
+  T extends { task_step_id?: string | null; scenario_step_id?: string | null },
+>(event: T): T {
+  if (event.task_step_id == null && event.scenario_step_id != null) {
+    return { ...event, task_step_id: event.scenario_step_id };
+  }
+  return event;
+}
+
+export const recorderEventSchema = recorderEventObjectSchema.transform(normalizeTaskStepVocab);
+export type RecorderEvent = z.infer<typeof recorderEventSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FDRS-398 — unified events.jsonl discriminated-union schema (v1).
+//
+// Hard-cut from the legacy single-shape `RecorderEvent`. The on-disk row is
+// now a tagged union over `kind`. Every variant carries:
+//   - `event_id`  — unique row id (uuid/nanoid, set by emitter)
+//   - `parent_id` — points at the spawning row's `event_id`, or null at the
+//                   root of a parent chain (e.g. top-level twin HTTP calls,
+//                   the first LLM call in a turn).
+//   - `kind`      — the discriminator literal (see each schema below)
+//
+// Provenance:
+//   - PR/FAQ: linear.app/pome-sh/project/agent-trace-v1-af8924d607f0
+//   - Milestone M0 "Universal Floor"
+//   - /plan-eng-review 2026-05-26 amendments:
+//       • Dropped OtelSpanEvent from this frozen v1 union (FDRS-400 cancelled).
+//         It later shipped additively (FDRS-480): the schema + mapper live in
+//         `./otel/` and are composed into `otelEventSchema` (= eventSchema ∪
+//         OtelSpanEvent). This v1 union is intentionally left unchanged.
+//       • LlmCallEvent per-call token/model/cost reclassified
+//         "TLS-terminate-only" — they are `nullable()` across both baseline
+//         CONNECT-tunnel mode AND CAS adapter mode in v1. CAS surfaces those
+//         at the per-turn aggregate level on the run summary, NOT here.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Common fields on every event variant. Spread (not extend) so the resulting
+// Zod object types stay readable.
+const eventBaseShape = {
+  ts: z.string().datetime(),
+  event_id: z.string().min(1),
+  parent_id: z.string().min(1).nullable(),
+} as const;
+
+// `TwinHttpEvent` is the legacy RecorderEvent shape extended with the union
+// discriminator + parent-chain fields. `extend` keeps it in lockstep with
+// the RecorderEvent object shape so updates to the underlying HTTP-call shape
+// flow through automatically. NOTE: as a discriminated-union member this stays
+// a plain `ZodObject` — the FDRS-653 task-vocab normalization is applied by
+// the exported `recorderEventSchema` / `eventSchema` readers, not here.
+export const twinHttpEventSchema = recorderEventObjectSchema.extend({
+  kind: z.literal("TwinHttpEvent"),
+  event_id: z.string().min(1),
+  parent_id: z.string().min(1).nullable(),
+});
+export type TwinHttpEvent = z.infer<typeof twinHttpEventSchema>;
+
+// `LlmCallEvent` baseline fields are populated by the HTTP_PROXY CONNECT
+// tunnel `pome capture-server` (M0). TLS-terminate-only fields stay null in
+// baseline mode and in CAS adapter mode; they get populated only by the v2
+// opt-in TLS-terminate proxy. Per-turn aggregate cost/model from CAS lives
+// on the run summary, not on individual LlmCallEvent rows.
+export const llmCallEventSchema = z.object({
+  ...eventBaseShape,
+  kind: z.literal("LlmCallEvent"),
+  // Baseline (always populated)
+  host: z.string().min(1),
+  port: z.number().int().min(1).max(65535),
+  latency_ms: z.number().int().min(0),
+  bytes_in: z.number().int().min(0),
+  bytes_out: z.number().int().min(0),
+  // TLS-terminate-only — nullable, not optional. Writers must emit explicit
+  // null in baseline/CAS mode so the on-disk JSON shape is stable.
+  url: z.string().nullable(),
+  method: z.string().nullable(),
+  status: z.number().int().nullable(),
+  model: z.string().nullable(),
+  prompt_tokens: z.number().int().min(0).nullable(),
+  completion_tokens: z.number().int().min(0).nullable(),
+  cost_usd: z.number().nullable(),
+});
+export type LlmCallEvent = z.infer<typeof llmCallEventSchema>;
+
+// `ToolUseEvent` — emitted by the CAS adapter (FDRS-408) for each tool_use
+// content block in an `SDKAssistantMessage`. `input` is opaque (already
+// redactor-scrubbed by the writer) so we type it as `unknown`.
+export const toolUseEventSchema = z.object({
+  ...eventBaseShape,
+  kind: z.literal("ToolUseEvent"),
+  tool_use_id: z.string().min(1),
+  tool_name: z.string().min(1),
+  input: z.unknown(),
+});
+export type ToolUseEvent = z.infer<typeof toolUseEventSchema>;
+
+// `ToolResultEvent` — emitted by the CAS adapter (FDRS-408) for each
+// tool_result content block in a user message. `tool_use_id` matches the
+// originating `ToolUseEvent.tool_use_id`; `parent_id` typically points at
+// that ToolUseEvent's `event_id`.
+export const toolResultEventSchema = z.object({
+  ...eventBaseShape,
+  kind: z.literal("ToolResultEvent"),
+  tool_use_id: z.string().min(1),
+  output: z.unknown(),
+  is_error: z.boolean(),
+});
+export type ToolResultEvent = z.infer<typeof toolResultEventSchema>;
+
+// `SubagentSpawnEvent` — emitted once per sub-agent (FDRS-409), the first
+// time the adapter sees a non-null `parent_tool_use_id` on an
+// `SDKAssistantMessage`.
+export const subagentSpawnEventSchema = z.object({
+  ...eventBaseShape,
+  kind: z.literal("SubagentSpawnEvent"),
+  parent_tool_use_id: z.string().min(1),
+});
+export type SubagentSpawnEvent = z.infer<typeof subagentSpawnEventSchema>;
+
+// `HookEvent` — thin audit-trail row written by the adapter for each of the
+// SDK's 25 hook invocations (FDRS-407). `tool_name` is null when the hook
+// isn't tool-scoped (e.g. SessionStarted, PreCompact, PermissionGranted on a
+// non-tool resource).
+export const hookEventSchema = z.object({
+  ...eventBaseShape,
+  kind: z.literal("HookEvent"),
+  hook_name: z.string().min(1),
+  tool_name: z.string().min(1).nullable(),
+});
+export type HookEvent = z.infer<typeof hookEventSchema>;
+
+// The unified event row. Discriminated on `kind` — adding a future variant
+// (e.g. `OtelSpanEvent` in v2) is a non-breaking extension. The exported
+// reader applies the FDRS-653 task-vocab normalization to `TwinHttpEvent`
+// rows (the only variant carrying the step-expectation key).
+const eventUnionSchema = z.discriminatedUnion("kind", [
+  twinHttpEventSchema,
+  llmCallEventSchema,
+  toolUseEventSchema,
+  toolResultEventSchema,
+  subagentSpawnEventSchema,
+  hookEventSchema,
+]);
+export const eventSchema = eventUnionSchema.transform((event) =>
+  event.kind === "TwinHttpEvent" ? normalizeTaskStepVocab(event) : event,
+);
+export type Event = z.infer<typeof eventSchema>;
+
+// Detect a pre-FDRS-398 legacy row on disk. A new-shape row always carries a
+// string `kind` discriminator; a legacy row does not. Non-object inputs
+// (`null`, arrays, primitives) are not event rows at all — return false so
+// the caller surfaces the underlying type error rather than treating them as
+// legacy.
+//
+// A row whose `kind` is present but not a string also routes through the
+// legacy path: the discriminated union will reject it with a clear error,
+// which is more useful than silently treating it as new-shape.
+export function isLegacyEventRow(row: unknown): boolean {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) {
+    return false;
+  }
+  return typeof (row as Record<string, unknown>).kind !== "string";
+}

package/node_modules/@pome-sh/shared-types/src/run.ts

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * run — completed-run shape, criterion result, lane/step correlator output
+ *
+ * Consumed by:
+ *   - `@pome-sh/evaluator` — produces CriterionResult, satisfaction_score
+ *   - `@pome-sh/correlator` — produces `{ lanes, steps }` from RecorderEvent[]
+ *   - `pome-cloud` `runs` table writer — persists the full Run row
+ *   - dashboard `/runs/:id` — renders lane-timeline + state-inspector + handoff card
+ *
+ * Lane/Step are flat parallel arrays on Run (not nested), aligning with the
+ * `runs.lanes jsonb` + `runs.steps jsonb` two-column DB shape from FDRS-327.
+ * Cross-reference: `Lane.step_id` → `Step.id`; `Lane.request_ids[]` →
+ * `RecorderEvent.request_id`.
+ */
+
+import { z } from "zod";
+import { twinIdSchema } from "./recorder-events.js";
+import { LEGACY_CRITERION_KIND_MAP, normalizeTaskVocabKeys } from "./task-vocab.js";
+
+// Judge model is a free-form string (BYOK Flavor #1, OpenAI-compatible endpoint
+// passes through); not constrained at the schema level because the customer's
+// gateway decides what model identifiers it accepts.
+export const judgeModelSchema = z.string().min(1);
+export type JudgeModel = z.infer<typeof judgeModelSchema>;
+
+// Which server-side correlator produced a run's lanes/steps. Reconciled from
+// pome-cloud /v1 (FDRS-613): OTEL M4/M6 clients distinguish heuristic legacy
+// timelines from exact span-context timelines.
+export const correlatorKindSchema = z.enum([
+  "heuristic",
+  "adapter_rich",
+  "span_context",
+]);
+export type CorrelatorKind = z.infer<typeof correlatorKindSchema>;
+
+// Criterion kind — W3 vocab (FDRS-653): `code` = deterministic/code-checked
+// predicate (formerly `D`), `model` = LLM-judged (formerly `P`). The canonical
+// enum is `code | model`; the INPUT schema below additionally accepts the
+// 0.3.0-era `D` / `P` spellings and normalizes them at parse time (tolerant
+// reader — shipped CLIs vendor 0.3.0 and keep sending D/P).
+export const CRITERION_KINDS = ["code", "model"] as const;
+export const criterionKindSchema = z.enum(CRITERION_KINDS);
+export type CriterionKind = z.infer<typeof criterionKindSchema>;
+
+// Single source of truth for the D/P→code/model rename is
+// LEGACY_CRITERION_KIND_MAP in ./task-vocab.ts.
+const criterionKindInputSchema = z
+  .enum(["D", "P", "code", "model"])
+  .transform((kind): CriterionKind =>
+    kind === "D" || kind === "P" ? LEGACY_CRITERION_KIND_MAP[kind] : kind,
+  );
+
+export const criterionSchema = z.object({
+  // Accepts D | P | code | model; parsed output is always code | model.
+  type: criterionKindInputSchema,
+  text: z.string().min(1),
+});
+export type Criterion = z.infer<typeof criterionSchema>;
+
+// CriterionResult shape matches OSS evaluator's emit. The full Criterion is
+// included by reference (not just text) so consumers render type-aware UI
+// without rejoining. Discriminate on `criterion.type` (no separate `kind`
+// field) — normalized to `code` / `model` (0.3.0 artifacts carrying `D` / `P`
+// parse and normalize).
+const baseCriterionResultSchema = z.object({
+  criterion: criterionSchema,                  // full {type, text} object
+  passed: z.boolean(),
+  skipped: z.boolean(),                        // true if [code] fell back to [model] but the judge was unreachable, etc.
+  reason: z.string(),                          // human-readable evidence
+});
+
+export const deterministicCriterionResultSchema = baseCriterionResultSchema.extend({
+  // [code] adds nothing further; criterion.type === "code" identifies it.
+});
+export type DeterministicCriterionResult = z.infer<typeof deterministicCriterionResultSchema>;
+
+export const probabilisticCriterionResultSchema = baseCriterionResultSchema.extend({
+  confidence: z.number().min(0).max(1),
+  judge_model: judgeModelSchema,
+});
+export type ProbabilisticCriterionResult = z.infer<typeof probabilisticCriterionResultSchema>;
+
+// Probabilistic FIRST: it's the strict superset (requires confidence +
+// judge_model). z.union tries branches in order and picks the first match.
+// If deterministic were first, [model] payloads would parse cleanly but
+// .extend({}) would silently strip the [model]-only fields — we'd persist them
+// as null in runs.criteria_results JSON, breaking dashboard rendering of
+// confidence + per-criterion judge_model. [code] payloads (no confidence /
+// judge_model) fail probabilistic on the required fields and fall through.
+export const criterionResultSchema = z.union([
+  probabilisticCriterionResultSchema,
+  deterministicCriterionResultSchema,
+]);
+export type CriterionResult = z.infer<typeof criterionResultSchema>;
+
+// Step is the correlator's top-level grouping: one Step per agent assistant
+// turn (adapter-rich path) or per heuristic-clustered HTTP burst (heuristic
+// path). started_at/ended_at bound the contained events. label is null when
+// heuristic-only (no assistant message to seed it from).
+export const stepSchema = z.object({
+  id: z.string(),                              // matches RecorderEvent.step_id
+  started_at: z.string().datetime(),
+  ended_at: z.string().datetime(),
+  label: z.string().nullable(),
+  lane_ids: z.array(z.string()),               // child lanes, render order
+});
+export type Step = z.infer<typeof stepSchema>;
+
+// Lane is the correlator's per-step sub-grouping by twin + endpoint pattern.
+// One lane = one horizontal track in lane-timeline UI. request_ids reference
+// RecorderEvent.request_id back into events.jsonl (events are the source of
+// truth; Lane just records which events belong here, time-ordered).
+export const laneSchema = z.object({
+  id: z.string(),
+  step_id: z.string(),                         // parent Step.id
+  twin: twinIdSchema,                          // matches RecorderEvent.twin
+  label: z.string().nullable(),                // e.g. "POST /v1/refunds (3 calls)"
+  request_ids: z.array(z.string()),            // RecorderEvent.request_id, time-ordered
+});
+export type Lane = z.infer<typeof laneSchema>;
+
+// Canonical Run row. W3 vocab (FDRS-653): `task_name` / `task_hash` /
+// `promoted_task_id` are the canonical wire keys (cloud DB: `tasks` table,
+// `runs.task_name`). The exported `runSchema` below wraps this object in the
+// tolerant-reader preprocess so 0.3.0-era rows carrying `scenario_name` /
+// `scenario_hash` / `promoted_scenario_id` parse and normalize.
+const runObjectSchema = z.object({
+  id: z.string(),                              // run_<nanoid>
+  session_id: z.string(),
+  team_id: z.string(),
+  task_name: z.string(),                       // 0.3.0 alias: scenario_name
+  task_hash: z.string(),                       // sha256 of source markdown; 0.3.0 alias: scenario_hash
+  satisfaction_score: z.number().int().min(0).max(100),  // CLI-computed (BYOK Flavor #1)
+  criteria_results: z.array(criterionResultSchema),
+  trace_s3_key: z.string().nullable(),         // s3 key for tool_calls.jsonl (hosted only)
+  state_s3_key: z.string().nullable(),         // s3 key for state_final.json
+  meta_s3_key: z.string().nullable(),
+  duration_ms: z.number().int(),
+  agent_model: z.string(),                     // which model the agent used (informational)
+  judge_model: judgeModelSchema,               // which model judged [P] (free-form)
+  judge_tokens_in: z.number().int().min(0).nullable(),
+  judge_tokens_out: z.number().int().min(0).nullable(),
+  // ── FDRS-613: reconciled from pome-cloud /v1 wire truth (all additive with
+  // defaults so pre-existing Run constructors stay valid) ────────────────────
+  // Sim deep-telemetry — per-run agent telemetry rollup, computed at finalize
+  // from the agent's independently-correlated `gen_ai` span tree. Null = no
+  // instrumentation / legacy / twin-only sim (dashboard renders `·`, never `0`).
+  agent_tokens_in: z.number().int().min(0).nullable().default(null),
+  agent_tokens_out: z.number().int().min(0).nullable().default(null),
+  agent_latency_p50_ms: z.number().int().min(0).nullable().default(null),
+  agent_latency_p95_ms: z.number().int().min(0).nullable().default(null),
+  agent_latency_max_ms: z.number().int().min(0).nullable().default(null),
+  agent_error_count: z.number().int().min(0).nullable().default(null),
+  agent_telemetry_span_count: z.number().int().min(0).nullable().default(null),
+  // Which server-side correlator produced lanes/steps.
+  correlator_kind: correlatorKindSchema.default("heuristic"),
+  // M0.2 (FDRS-509) — which surface this run belongs to. 'simulation' =
+  // CLI/staging scenario run (default for every legacy row); 'production' = an
+  // ingested OTLP production trace (M2).
+  environment: z.enum(["production", "simulation"]).default("simulation"),
+  // M0.5 (FDRS-512) — replay loop linkage (prod-run → task → replay-run).
+  // W3 vocab: canonical key; 0.3.0 alias: promoted_scenario_id.
+  promoted_task_id: z.string().nullable().default(null),
+  replay_run_id: z.string().nullable().default(null),
+  // Storage key for the tar-and-upload state archive the replay engine seeds a
+  // sandbox from. Null when no archive was captured.
+  state_archive_s3_key: z.string().nullable().default(null),
+  // Correlator output. Empty arrays for legacy runs (pre-M3i / pre-M4-1).
+  lanes: z.array(laneSchema).default([]),
+  steps: z.array(stepSchema).default([]),
+  // Server-generated by the managed judge (ADR-013). 1-2 sentence concise
+  // narrative of the run. Null for pre-ADR-013 rows / legacy /result runs.
+  summary: z.string().nullable().default(null),
+  // Originally CLI-generated (BYOK Flavor #1). Null on --no-fix-prompt opt-out,
+  // LLM endpoint failure, or legacy pre-M4-1 runs.
+  fix_prompt: z.string().nullable().default(null),
+  // Storage KEY (path) of the raw events.jsonl blob — NOT a URL (dashboard mints
+  // a signed GET URL on read). FDRS-613: relaxed from `.url()` to match the
+  // pome-cloud shape, since persisted storage keys are not URLs. Null in
+  // self-host mode, on upload failure, --no-upload opt-out, or legacy runs.
+  events_jsonl_url: z.string().nullable().default(null),
+  created_at: z.string().datetime(),
+  finished_at: z.string().datetime().nullable(),
+});
+
+// Tolerant reader (FDRS-653): accepts both the 0.3.0 `scenario_*` and the
+// canonical `task_*` keys and normalizes to the new vocabulary. When both are
+// present, the canonical key wins. The parsed output carries `task_*` only.
+export const runSchema = z.preprocess(normalizeTaskVocabKeys, runObjectSchema);
+export type Run = z.infer<typeof runSchema>;