@prismatic-io/lux 0.0.2-preview.4 → 0.0.2-preview.41

package/src/core/agent-events.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { AgentAttributionSchema } from "./events.js";
+
+export const AGENT_SPAWN_KIND = "agent-spawn" as const;
+export const AGENT_COMPLETED_KIND = "agent-completed" as const;
+
+export const AgentSpawnPayloadSchema = z.object({
+  agent: AgentAttributionSchema.extend({ role: z.literal("subagent") }),
+  prompt: z.exactOptional(z.string()),
+});
+export type AgentSpawnPayload = z.infer<typeof AgentSpawnPayloadSchema>;
+
+export const AgentCompletedPayloadSchema = z.object({
+  agentId: z.string().min(1),
+  status: z.enum(["completed", "failed", "cancelled", "unknown"]),
+});
+export type AgentCompletedPayload = z.infer<typeof AgentCompletedPayloadSchema>;

package/src/core/annotation.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { EvaluationMetadataSchema } from "./evaluation-clusters.js";
 import { formatZodIssues } from "./zod.js";
 
 const ExpectedBooleanLabelSchema = z
@@ -35,7 +36,7 @@ export const GraderAnnotationSchema = z
     reviewer: z.string().min(1).optional(),
     /** Human rationale supplied to the rubric optimizer on mismatches. */
     feedback: z.string().optional(),
-    meta: z.record(z.string(), z.unknown()).optional(),
+    meta: EvaluationMetadataSchema.optional(),
   })
   .strict()
   .superRefine((annotation, ctx) => {

package/src/core/answerer.ts

@@ -73,3 +73,12 @@ export type AnswererPlugin<Cfg = unknown> = {
   configSchema?: z.ZodTypeAny;
   create: (config: Cfg) => Answerer | Promise<Answerer>;
 };
+
+export const defineAnswerer = <S extends z.ZodType>(
+  definition: Omit<AnswererPlugin<z.output<S>>, "configSchema"> & { configSchema: S },
+): Omit<AnswererPlugin<z.output<S>>, "configSchema"> & { configSchema: S } => definition;
+
+export const answererRef = <S extends z.ZodType>(
+  plugin: { name: string; configSchema: S },
+  config: z.input<S>,
+): { name: string; config: z.input<S> } => ({ name: plugin.name, config });

package/src/core/artifact-evidence.ts

@@ -188,6 +188,7 @@ export const readInspectedFileBytes = async (
   expected: Stats,
   maxBytes: number,
   label: string,
+  prefixOnly = false,
 ): Promise<Buffer> => {
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > MAX_ARTIFACT_READ_BYTES) {
     throw new RangeError(
@@ -195,7 +196,7 @@ export const readInspectedFileBytes = async (
     );
   }
   if (!expected.isFile()) throw new Error(`${label} is not a file`);
-  if (expected.size > maxBytes) {
+  if (!prefixOnly && expected.size > maxBytes) {
     throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
   }
 
@@ -210,23 +211,24 @@ export const readInspectedFileBytes = async (
       if (opened.size !== expected.size) {
         throw new Error(`${label} changed while it was being inspected`);
       }
-      if (opened.size > maxBytes) {
+      if (!prefixOnly && opened.size > maxBytes) {
         throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
       }
       // Allocate for the inspected file, not the caller's ceiling. Reading one
       // extra byte detects same-inode growth after fstat without making many
       // tiny artifact reads reserve the maximum concurrently.
-      const bytes = Buffer.alloc(expected.size + 1);
+      const size = Math.min(expected.size, maxBytes);
+      const bytes = Buffer.alloc(size + 1);
       let offset = 0;
       while (offset < bytes.length) {
         const read = await handle.read(bytes, offset, bytes.length - offset, offset);
         if (read.bytesRead === 0) break;
         offset += read.bytesRead;
       }
-      if (offset !== expected.size) {
+      if (offset !== Math.min(expected.size, bytes.length)) {
         throw new Error(`${label} changed while it was being inspected`);
       }
-      return bytes.subarray(0, offset);
+      return bytes.subarray(0, Math.min(offset, size));
     } finally {
       await handle.close();
     }
@@ -238,6 +240,39 @@ export const readInspectedFileBytes = async (
   }
 };
 
+/** Read a bounded prefix for presentation without weakening full-evidence reads. */
+export const readRunArtifactExcerpt = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  maxChars: number,
+): Promise<{ text: string; truncated: boolean }> => {
+  if (!Number.isSafeInteger(maxChars) || maxChars < 0 || maxChars > 80_000) {
+    throw new RangeError("artifact excerpt maxChars must be an integer from 0 to 80000");
+  }
+  const inspected = await inspectRunArtifact(run, authoredPath);
+  if (!inspected.stats?.isFile()) {
+    throw new Error(inspected.issue ?? `${authoredPath} is not a file`);
+  }
+  // An extra character distinguishes an exact fit from an omitted suffix.
+  const bytes = await readInspectedFileBytes(
+    inspected.target,
+    inspected.stats,
+    (maxChars + 1) * 4,
+    authoredPath,
+    true,
+  );
+  const text = bytes.toString("utf8");
+  let end = Math.min(maxChars, text.length);
+  if (
+    end > 0 &&
+    end < text.length &&
+    /[\uD800-\uDBFF]/.test(text[end - 1] ?? "") &&
+    /[\uDC00-\uDFFF]/.test(text[end] ?? "")
+  )
+    end--;
+  return { text: text.slice(0, end), truncated: text.length > end };
+};
+
 export const readRunArtifactBytes = async (
   run: RunArtifactEvidence,
   authoredPath: string,

package/src/core/assertion.ts

@@ -9,6 +9,8 @@ export const AssertionResultSchema = z.object({
   score: z.number().min(0).max(1),
   comment: z.exactOptional(z.string()),
   detail: z.unknown().optional(),
+  /** The evaluator ran successfully but lacked evidence for a verdict. */
+  abstention: z.exactOptional(z.literal("insufficient-evidence")),
   /** Present when the assertion could not produce a judgment. */
   errorMessage: z.exactOptional(z.string()),
   /** Tokens the assertion itself spent. Only LLM-judge assertions report this. */
@@ -105,6 +107,7 @@ export const baseAssertionFields = {
   weight: z.number().positive().optional(),
   threshold: z.number().min(0).max(1).optional(),
   name: z.string().optional(),
+  informational: z.boolean().optional(),
 } as const;
 
 export const defineAssertion = <S extends z.ZodObject>(
@@ -135,14 +138,17 @@ export const GradingAssertionEntrySchema = z.object({
   id: z.exactOptional(z.string()),
   type: z.string(),
   name: z.string(),
-  passed: z.boolean(),
+  passed: z.boolean().nullable(),
+  informational: z.exactOptional(z.boolean()),
   score: z.number(),
   weight: z.number(),
-  threshold: z.number(),
+  /** Acceptance floor; absent for informational measurements. */
+  threshold: z.exactOptional(z.number()),
   /** Wall-clock the assertion took to evaluate. A `rubric` costs seconds; a file check, none. */
   durationMs: z.number(),
   comment: z.exactOptional(z.string()),
   detail: z.unknown().optional(),
+  abstention: z.exactOptional(z.literal("insufficient-evidence")),
   errorMessage: z.exactOptional(z.string()),
   usage: z.exactOptional(TokenUsageSchema),
 });

package/src/core/case-defaults.ts

@@ -0,0 +1,65 @@
+import type { Assertion, EvalCase } from "./case.js";
+import { mergePluginConfig } from "./harness-matrix.js";
+import { mergeAnswererReference, mergeDriverReference } from "./reference-defaults.js";
+
+type DeepPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T;
+
+export type AssertionDefaults<A extends Assertion = Assertion> = {
+  [Type in A["type"]]?: DeepPartial<Omit<Extract<A, { type: Type }>, "type" | "id">>;
+};
+
+export type EvalCaseDefaults<A extends Assertion = Assertion> = Omit<
+  Partial<EvalCase>,
+  "id" | "prompt" | "assertions"
+> & { assertions?: A[] | undefined };
+
+/** Named assertions replace inherited checks; unnamed checks append in declaration order. */
+const mergeAssertions = (base: Assertion[], local: Assertion[]): Assertion[] => {
+  const seen = new Set<string>();
+  for (const assertion of local) {
+    if (!assertion.id) continue;
+    if (seen.has(assertion.id)) throw new Error(`duplicate assertion id '${assertion.id}'`);
+    seen.add(assertion.id);
+  }
+  const result = [...base];
+  for (const assertion of local) {
+    const index = assertion.id ? result.findIndex((entry) => entry.id === assertion.id) : -1;
+    if (index < 0) result.push(assertion);
+    else result[index] = assertion;
+  }
+  return result;
+};
+
+export const mergeCaseDefaults = (
+  base: EvalCaseDefaults,
+  local: EvalCaseDefaults,
+): EvalCaseDefaults => ({
+  ...base,
+  ...local,
+  ...(base.driver || local.driver
+    ? { driver: mergeDriverReference(base.driver, local.driver) }
+    : {}),
+  ...(base.answerer || local.answerer
+    ? { answerer: mergeAnswererReference(base.answerer, local.answerer) }
+    : {}),
+  ...(base.meta || local.meta
+    ? { meta: mergePluginConfig(base.meta, local.meta) as EvalCase["meta"] }
+    : {}),
+  ...(base.assertions || local.assertions
+    ? { assertions: mergeAssertions(base.assertions ?? [], local.assertions ?? []) }
+    : {}),
+});
+
+export const applyAssertionDefaults = (
+  assertions: Assertion[],
+  defaults: AssertionDefaults,
+): Assertion[] =>
+  assertions.map((assertion) => ({
+    ...(mergePluginConfig(defaults[assertion.type], assertion) as Assertion),
+  }));

package/src/core/case.ts

@@ -1,6 +1,16 @@
 import { z } from "zod";
 import type { AssertionPlugin } from "./assertion.js";
 import { collectEvalCaseExtensions, setEvalCaseExtensions } from "./case-authoring-state.js";
+import {
+  type AssertionDefaults,
+  applyAssertionDefaults,
+  type EvalCaseDefaults,
+  mergeCaseDefaults,
+} from "./case-defaults.js";
+import { DriverCapabilitySchema } from "./driver.js";
+import { DriverExecutionSchema } from "./driver-execution.js";
+import { EvaluationMetadataSchema } from "./evaluation-clusters.js";
+import { HarnessMatrixSchema, mergePluginConfig } from "./harness-matrix.js";
 import type { LifecycleHooksPlugin } from "./lifecycle-hooks.js";
 import { formatZodIssues } from "./zod.js";
 
@@ -17,7 +27,13 @@ export type FixturesRef = z.infer<typeof FixturesRefSchema>;
 // `defineEvalCase` discriminate the config type on `name`.
 export const DriverRefSchema = z.union([
   z.string(),
-  z.object({ name: z.string(), config: z.unknown().optional() }).strict(),
+  z
+    .object({
+      name: z.string(),
+      config: z.unknown().optional(),
+      execution: DriverExecutionSchema.optional(),
+    })
+    .strict(),
 ]);
 export type DriverRef = z.infer<typeof DriverRefSchema>;
 
@@ -35,6 +51,7 @@ export const AssertionSchema = z
     name: z.string().optional(),
     weight: z.number().positive().optional(),
     threshold: z.number().min(0).max(1).optional(),
+    informational: z.boolean().optional(),
   })
   .loose();
 export type Assertion = z.infer<typeof AssertionSchema>;
@@ -44,10 +61,13 @@ const EvalCaseObjectSchema = z.object({
   prompt: z.string().min(1, "prompt is required"),
   persona: z.string().min(1).optional(),
   driver: DriverRefSchema.optional(),
+  /** Harness permutations this case runs through instead of the project matrix. */
+  matrix: HarnessMatrixSchema.optional(),
   answerer: AnswererRefSchema.optional(),
   fixtures: FixturesRefSchema.optional(),
+  requires: z.array(DriverCapabilitySchema).optional(),
   assertions: z.array(AssertionSchema).optional(),
-  meta: z.record(z.string(), z.unknown()).optional(),
+  meta: EvaluationMetadataSchema.optional(),
 });
 
 export const EvalCaseSchema = EvalCaseObjectSchema
@@ -70,7 +90,10 @@ export const EvalCaseSchema = EvalCaseObjectSchema
   });
 export type EvalCase = z.infer<typeof EvalCaseSchema>;
 
-type AssertionPlanFields = Pick<Assertion, "id" | "name" | "threshold" | "weight">;
+type AssertionPlanFields = Pick<
+  Assertion,
+  "id" | "name" | "threshold" | "weight" | "informational"
+>;
 type AssertionInputOf<Plugin> =
   Plugin extends AssertionPlugin<Assertion, infer Input> ? Input & AssertionPlanFields : never;
 
@@ -79,13 +102,19 @@ export type EvalCaseInput<AllowedAssertion extends Assertion = Assertion> = Omit
   "assertions"
 > & {
   assertions?: AllowedAssertion[];
+  assertionDefaults?: AssertionDefaults<AllowedAssertion>;
+  /** Remove named inherited checks without replacing the rest of the suite plan. */
+  omitAssertions?: string[];
 };
 
 export type EvalCaseAuthoringOptions<
   Plugins extends readonly AssertionPlugin[] = readonly AssertionPlugin[],
+  AllowedAssertion extends Assertion = Assertion,
 > = {
   assertions?: Plugins;
   fixtures?: readonly LifecycleHooksPlugin[];
+  defaults?: EvalCaseDefaults<AllowedAssertion | AssertionInputOf<Plugins[number]>>;
+  assertionDefaults?: AssertionDefaults<AllowedAssertion | AssertionInputOf<Plugins[number]>>;
 };
 
 export type EvalCaseDefinition<AllowedAssertion extends Assertion = Assertion> = {
@@ -95,16 +124,49 @@ export type EvalCaseDefinition<AllowedAssertion extends Assertion = Assertion> =
    * Further calls to `extend` append fixtures in setup order.
    */
   extend<const Plugins extends readonly AssertionPlugin[] = readonly []>(
-    options: EvalCaseAuthoringOptions<Plugins>,
+    options: EvalCaseAuthoringOptions<Plugins, AllowedAssertion>,
   ): EvalCaseDefinition<AllowedAssertion | AssertionInputOf<Plugins[number]>>;
 };
 
 export const createEvalCaseDefinition = <AllowedAssertion extends Assertion = Assertion>(
   inheritedAssertions: readonly AssertionPlugin[] = [],
   inheritedFixtures: readonly LifecycleHooksPlugin[] = [],
+  defaults: EvalCaseDefaults = {},
+  assertionDefaults: AssertionDefaults = {},
 ): EvalCaseDefinition<AllowedAssertion> => {
   const define = ((input: EvalCaseInput<AllowedAssertion>): EvalCase => {
-    const parsed = EvalCaseSchema.safeParse(input);
+    const { omitAssertions = [], assertionDefaults: localAssertionDefaults = {}, ...local } = input;
+    for (const id of omitAssertions) {
+      if (!defaults.assertions?.some((assertion) => assertion.id === id)) {
+        throw new Error(`cannot omit unknown inherited assertion '${id}'`);
+      }
+    }
+    const resolved = mergeCaseDefaults(
+      {
+        ...defaults,
+        ...(defaults.assertions
+          ? {
+              assertions: defaults.assertions.filter(
+                (assertion) => !omitAssertions.includes(assertion.id ?? ""),
+              ),
+            }
+          : {}),
+      },
+      local,
+    );
+    const parsed = EvalCaseSchema.safeParse({
+      ...resolved,
+      ...("id" in local ? { id: local.id } : {}),
+      prompt: local.prompt,
+      ...(resolved.assertions
+        ? {
+            assertions: applyAssertionDefaults(
+              resolved.assertions,
+              mergePluginConfig(assertionDefaults, localAssertionDefaults) as AssertionDefaults,
+            ),
+          }
+        : {}),
+    });
     if (!parsed.success) {
       throw new Error(`Invalid eval case: ${formatZodIssues(parsed.error)}`);
     }
@@ -116,11 +178,19 @@ export const createEvalCaseDefinition = <AllowedAssertion extends Assertion = As
     setEvalCaseExtensions(parsed.data, extensions);
     return parsed.data;
   }) as EvalCaseDefinition<AllowedAssertion>;
-  define.extend = (({ assertions = [], fixtures = [] }: EvalCaseAuthoringOptions) =>
-    createEvalCaseDefinition(
+  define.extend = ((options: EvalCaseAuthoringOptions) => {
+    const { assertions = [], fixtures = [] } = options;
+    const inherited = EvalCaseObjectSchema.omit({ id: true, prompt: true })
+      .partial()
+      .strict()
+      .parse(options.defaults ?? {});
+    return createEvalCaseDefinition(
       [...inheritedAssertions, ...assertions],
       [...inheritedFixtures, ...fixtures],
-    )) as EvalCaseDefinition<AllowedAssertion>["extend"];
+      mergeCaseDefaults(defaults, inherited),
+      mergePluginConfig(assertionDefaults, options.assertionDefaults ?? {}) as AssertionDefaults,
+    );
+  }) as EvalCaseDefinition<AllowedAssertion>["extend"];
   return define;
 };
 
@@ -149,6 +219,7 @@ export const PersistedCaseSchema = EvalCaseObjectSchema.partial()
     driver: PersistedDriverRefSchema.optional(),
     answerer: PersistedAnswererRefSchema.optional(),
     fixtures: PersistedFixturesRefSchema.optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
   })
   .loose();
 export type PersistedCase = z.infer<typeof PersistedCaseSchema>;

package/src/core/command-verification.ts

@@ -0,0 +1,74 @@
+import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rm, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { Run } from "./run.js";
+import { copyRegularFileNoFollow } from "./secure-copy.js";
+
+const executionWorkspaces = new WeakMap<Run, string>();
+
+/** Internal: live execution state is deliberately absent from persisted run evidence. */
+export const bindRunExecutionWorkspace = (run: Run, root: string): void => {
+  executionWorkspaces.set(run, resolve(root));
+};
+
+export const runExecutionWorkspace = (run: Run): string | undefined => executionWorkspaces.get(run);
+
+const within = (root: string, path: string): boolean => {
+  const rel = relative(root, path);
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+
+/** A disposable command tree preserves dependencies without exposing host symlink targets. */
+export const copyCommandWorkspace = async (
+  source: string,
+  signal?: AbortSignal,
+): Promise<{
+  root: string;
+  close: () => Promise<void>;
+}> => {
+  const sourceRoot = await realpath(source);
+  if (!(await lstat(source)).isDirectory() || (await lstat(source)).isSymbolicLink()) {
+    throw new Error(`verification workspace must be a real directory: ${source}`);
+  }
+  const root = await mkdtemp(join(tmpdir(), "lux-command-verification-"));
+  const close = () => rm(root, { recursive: true, force: true });
+  let entries = 0;
+  const copy = async (directory: string): Promise<void> => {
+    if (!within(sourceRoot, await realpath(directory))) {
+      throw new Error(`verification directory escapes its workspace: ${directory}`);
+    }
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      signal?.throwIfAborted();
+      if (++entries > 100_000) throw new Error("verification workspace exceeds 100000 entries");
+      if (directory === sourceRoot && entry.name === ".lux-claude") continue;
+      const path = join(directory, entry.name);
+      const target = join(root, relative(sourceRoot, path));
+      const metadata = await lstat(path);
+      if (metadata.isSymbolicLink()) {
+        const resolved = await realpath(path);
+        if (!within(sourceRoot, resolved)) {
+          throw new Error(`verification symlink escapes its workspace: ${path}`);
+        }
+        await symlink(
+          relative(dirname(target), join(root, relative(sourceRoot, resolved))),
+          target,
+        );
+      } else if (metadata.isDirectory()) {
+        await mkdir(target, { mode: (metadata.mode & 0o777) | 0o700 });
+        await copy(path);
+        await chmod(target, metadata.mode & 0o777);
+      } else if (metadata.isFile()) {
+        await copyRegularFileNoFollow(sourceRoot, path, target);
+      } else {
+        throw new Error(`verification workspace contains an unsupported entry: ${path}`);
+      }
+    }
+  };
+  try {
+    await copy(sourceRoot);
+    return { root, close };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+};

package/src/core/driver-execution.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+const homePath = z
+  .string()
+  .min(1)
+  .refine(
+    (value) =>
+      !value.startsWith("/") &&
+      !value.includes("\\") &&
+      value.split("/").every((part) => part !== ".." && part !== "." && part !== ""),
+    "must be a relative path within the container home",
+  );
+
+export const ContainerExecutionSchema = z
+  .object({
+    kind: z.literal("container"),
+    /** A locally available image containing Lux and the selected Linux harness. */
+    image: z.string().min(1),
+    command: z.string().min(1).optional(),
+    /** The worker shipped with the same Lux build as the host. */
+    worker: z.string().min(1).optional(),
+    /** Optional module in the image exporting a custom DriverPlugin as default. */
+    driverModule: z.string().min(1).optional(),
+    mounts: z
+      .array(
+        z
+          .object({
+            source: z.string().min(1),
+            target: z.string().min(1).optional(),
+            readOnly: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    /** Only these host environment variables enter the container. */
+    passEnv: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).optional(),
+    env: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string()).optional(),
+    /** Private copies, never host-home mounts; deleted after the run. */
+    homeFiles: z
+      .array(
+        z
+          .object({
+            destination: homePath,
+            source: z.discriminatedUnion("kind", [
+              z.object({ kind: z.literal("file"), path: z.string().min(1) }).strict(),
+              z
+                .object({
+                  kind: z.literal("keychain"),
+                  service: z.string().min(1),
+                  account: z.string().min(1),
+                  encoding: z.enum(["utf8", "go-keyring-base64"]).optional(),
+                })
+                .strict(),
+            ]),
+          })
+          .strict(),
+      )
+      .max(32)
+      .optional(),
+    network: z.enum(["bridge", "none"]).optional(),
+    user: z.string().min(1).optional(),
+    memory: z
+      .string()
+      .regex(/^[1-9][0-9]*[bkmgt]?$/i)
+      .optional(),
+    cpus: z.number().positive().optional(),
+    pidsLimit: z.number().int().positive().optional(),
+    startupTimeoutMs: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export const DriverExecutionSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("host") }).strict(),
+  ContainerExecutionSchema,
+]);
+export type DriverExecution = z.infer<typeof DriverExecutionSchema>;
+export type ContainerExecution = z.infer<typeof ContainerExecutionSchema>;
+
+export const driverExecutionOf = (reference: unknown): DriverExecution | undefined => {
+  if (!reference || typeof reference !== "object" || !("execution" in reference)) return undefined;
+  return reference.execution === undefined
+    ? undefined
+    : DriverExecutionSchema.parse(reference.execution);
+};

package/src/core/driver-metrics.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+export const DriverMetricUnitSchema = z.enum([
+  "number",
+  "count",
+  "milliseconds",
+  "bytes",
+  "tokens",
+  "usd",
+  "ratio",
+  "percent",
+  "score",
+]);
+export type DriverMetricUnit = z.infer<typeof DriverMetricUnitSchema>;
+
+export const DriverMetricDescriptorSchema = z
+  .object({
+    unit: DriverMetricUnitSchema.default("number"),
+    label: z.string().min(1).max(120).optional(),
+    better: z.enum(["lower", "higher", "neutral"]).default("neutral"),
+  })
+  .strict();
+export type DriverMetricDescriptor = z.infer<typeof DriverMetricDescriptorSchema>;
+
+export const DriverMetricSchema = DriverMetricDescriptorSchema.extend({
+  value: z.number().finite(),
+}).strict();
+export type DriverMetric = z.infer<typeof DriverMetricSchema>;
+
+export const DriverMetricsSchema = z.record(z.string().min(1).max(120), DriverMetricSchema);
+export type DriverMetrics = z.infer<typeof DriverMetricsSchema>;
+
+const ReportedDriverMetricSchema = z.union([z.number().finite(), DriverMetricSchema]);
+export const ReportedDriverMetricsSchema = z.record(
+  z.string().min(1).max(120),
+  ReportedDriverMetricSchema,
+);
+export type ReportedDriverMetrics = z.input<typeof ReportedDriverMetricsSchema>;
+
+export const normalizeDriverMetrics = (value: unknown): DriverMetrics => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([name, metric]) => {
+      if (name.length === 0 || name.length > 120) return [];
+      const parsed = DriverMetricSchema.safeParse(
+        typeof metric === "number" ? { value: metric } : metric,
+      ).data;
+      return parsed ? [[name, parsed]] : [];
+    }),
+  );
+};