@prismatic-io/lux 0.0.2-preview.3 → 0.0.2-preview.30

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

@@ -7,12 +7,15 @@ import type { Run } from "./run.js";
 const DEFAULT_ARTIFACT_READ_BYTES = 5 * 1024 * 1024;
 const MAX_ARTIFACT_READ_BYTES = 10 * 1024 * 1024;
 
+export type RunArtifactIssueReason = "absent" | "unreadable";
+
 export type RunArtifactInspection = {
   target: string;
   root: string;
   artifact?: Artifact;
   stats?: Stats;
   issue?: string;
+  reason?: RunArtifactIssueReason;
 };
 
 type RunArtifactEvidence = {
@@ -82,6 +85,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: runArtifactsRoot(run),
       issue: `${authoredPath} contains a null byte`,
+      reason: "unreadable",
     };
   }
   const matching = run.artifacts.filter((candidate) => candidate.path === authoredPath);
@@ -91,6 +95,7 @@ export const inspectRunArtifact = async (
       target: resolve(root, authoredPath),
       root,
       issue: `${authoredPath} was not captured in the frozen artifact index`,
+      reason: "absent",
     };
   }
   if (matching.some((candidate) => candidate.root !== undefined && !isAbsolute(candidate.root))) {
@@ -98,6 +103,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: defaultArtifactsRoot(run),
       issue: `${authoredPath} declares a non-absolute artifact root`,
+      reason: "unreadable",
     };
   }
   const artifact = matching[0];
@@ -108,6 +114,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: defaultArtifactsRoot(run),
       issue: `${authoredPath} is ambiguous across multiple artifact roots`,
+      reason: "unreadable",
     };
   }
   // A non-default root is trusted only for an exact artifact-index entry.
@@ -116,7 +123,12 @@ export const inspectRunArtifact = async (
   const root = matchingRoots[0] ?? defaultArtifactsRoot(run);
   const target = resolve(root, authoredPath);
   if (pathEscapesRoot(root, target)) {
-    return { target, root, issue: `${authoredPath} escapes the captured artifact root` };
+    return {
+      target,
+      root,
+      issue: `${authoredPath} escapes the captured artifact root`,
+      reason: "unreadable",
+    };
   }
 
   const path = relative(root, target);
@@ -134,7 +146,13 @@ export const inspectRunArtifact = async (
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code;
       if (code === "ENOENT" || code === "ENOTDIR") {
-        return { target, root, ...identified, issue: `${authoredPath} not found` };
+        return {
+          target,
+          root,
+          ...identified,
+          issue: `${authoredPath} not found`,
+          reason: "absent",
+        };
       }
       throw error;
     }
@@ -144,16 +162,17 @@ export const inspectRunArtifact = async (
         root,
         ...identified,
         issue: `${authoredPath} resolves through a symlink`,
+        reason: "unreadable",
       };
     }
     if (index < components.length - 1 && !stats.isDirectory()) {
-      return { target, root, ...identified, issue: `${authoredPath} not found` };
+      return { target, root, ...identified, issue: `${authoredPath} not found`, reason: "absent" };
     }
     if (index === components.length - 1) {
       return { target, root, ...identified, stats };
     }
   }
-  return { target, root, ...identified, issue: `${authoredPath} not found` };
+  return { target, root, ...identified, issue: `${authoredPath} not found`, reason: "absent" };
 };
 
 export type ReadRunArtifactTextOptions = {
@@ -247,3 +266,27 @@ export const readRunArtifactText = async (
 ): Promise<string> => {
   return (await readRunArtifactBytes(run, authoredPath, options)).toString("utf8");
 };
+
+/**
+ * Read optional artifact evidence. Returns null when the artifact was never
+ * captured, and still throws when one exists but is unsafe to consume, so a
+ * traversal or symlink violation is never mistaken for missing evidence.
+ */
+export const readRunArtifactTextIfPresent = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  options: ReadRunArtifactTextOptions = {},
+): Promise<string | null> => {
+  const inspected = await inspectRunArtifact(run, authoredPath);
+  if (inspected.reason === "absent") return null;
+  if (!inspected.stats?.isFile()) {
+    throw new Error(
+      inspected.issue ??
+        (inspected.stats ? `${authoredPath} is not a file` : `${authoredPath} not found`),
+    );
+  }
+  const maxBytes = options.maxBytes ?? DEFAULT_ARTIFACT_READ_BYTES;
+  return (
+    await readInspectedFileBytes(inspected.target, inspected.stats, maxBytes, authoredPath)
+  ).toString("utf8");
+};

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. */
@@ -100,6 +102,13 @@ export const assertionPluginIssue = (definition: {
  * Define a schema-validated assertion plugin while inferring the config passed
  * to `evaluate` from the schema.
  */
+export const baseAssertionFields = {
+  id: z.string().min(1).optional(),
+  weight: z.number().positive().optional(),
+  threshold: z.number().min(0).max(1).optional(),
+  name: z.string().optional(),
+} as const;
+
 export const defineAssertion = <S extends z.ZodObject>(
   definition: AssertionPluginDefinition<S>,
 ): AssertionPlugin<SchemaAssertion<S>, SchemaAssertionInput<S>> => {
@@ -136,16 +145,25 @@ export const GradingAssertionEntrySchema = z.object({
   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),
 });
 export type GradingAssertionEntry = z.infer<typeof GradingAssertionEntrySchema>;
 
+const SkippedGradingAssertionSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  name: z.string(),
+  reason: z.literal("judge-disabled"),
+});
+
 export const GradingReportSchema = z.object({
   schemaVersion: z.literal(1),
   casePassed: z.boolean().nullable(),
   caseScore: z.number().nullable(),
   assertions: z.array(GradingAssertionEntrySchema),
+  skippedAssertions: z.array(SkippedGradingAssertionSchema).optional(),
   /**
    * Present when the subject run or grading did not complete. Assertions may
    * still contain partial diagnostics, but the report is not a clean verdict.

package/src/core/case.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import type { AssertionPlugin } from "./assertion.js";
 import { collectEvalCaseExtensions, setEvalCaseExtensions } from "./case-authoring-state.js";
+import { DriverCapabilitySchema } from "./driver.js";
+import { DriverExecutionSchema } from "./driver-execution.js";
+import { EvaluationMetadataSchema } from "./evaluation-clusters.js";
+import { HarnessMatrixSchema } from "./harness-matrix.js";
 import type { LifecycleHooksPlugin } from "./lifecycle-hooks.js";
 import { formatZodIssues } from "./zod.js";
 
@@ -17,7 +21,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>;
 
@@ -44,10 +54,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
@@ -149,6 +162,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]] : [];
+    }),
+  );
+};

package/src/core/driver.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
+import type { DriverExecution } from "./driver-execution.js";
 import type { EventHandler } from "./emitter.js";
 import type { Answer, Done, ErrorEvent, Interrupt, Progress, ReadyState } from "./events.js";
+import type { ReasoningEffort } from "./harness-catalog.js";
 import type { FixtureValueBinding } from "./lifecycle-hooks.js";
 
 export const ArtifactSchema = z.object({
@@ -11,6 +13,8 @@ export const ArtifactSchema = z.object({
    * Consumers resolve `path` against this before falling back to the default.
    */
   root: z.exactOptional(z.string()),
+  /** Assigned by Lux against fixture bytes frozen before the subject starts. */
+  origin: z.exactOptional(z.enum(["generated", "modified", "fixture"])),
   contentType: z.exactOptional(z.string()),
   size: z.exactOptional(z.number()),
   meta: z.exactOptional(z.record(z.string(), z.unknown())),
@@ -27,6 +31,8 @@ export type ResolvedFixtures = z.infer<typeof ResolvedFixturesSchema>;
 export type StartContext = {
   /** Stable selected case id, available to drivers that multiplex scenarios. */
   caseId?: string;
+  /** Private home owned by an outer execution boundary; never the caller’s home. */
+  isolatedHome?: string;
   prompt: string;
   fixtures?: ResolvedFixtures | undefined;
   /** Authored fixture values selected for this case. */
@@ -68,11 +74,81 @@ export interface AgentDriver {
    * responsible for stopping background writers before this promise resolves.
    */
   collect(): Promise<Artifact[]>;
+  /** Optional quiesced full execution tree for private command verification, until close. */
+  verificationWorkspace?(): Promise<string | undefined>;
   close(): Promise<void>;
 }
 
+export const DriverCapabilitySchema = z.enum([
+  "interactive",
+  "tool-calls",
+  "tool-results",
+  "artifacts",
+  "subagents",
+  "usage",
+  "cost",
+  "isolation",
+]);
+export type DriverCapability = z.infer<typeof DriverCapabilitySchema>;
+
+export type DriverRuntime = {
+  commands: string[];
+  /** Missing keys mean unknown; false means the adapter cannot provide the capability. */
+  capabilities: Partial<Record<DriverCapability, boolean>>;
+};
+
+export type DriverExperiment<Cfg> = {
+  version: string;
+  /** Bind a configuration to the experiment environment; Lux validates the returned config. */
+  prepare(config: Cfg): unknown;
+  /** Fingerprint behavior outside authored cases/configuration and the reported executables. */
+  identity(config: Cfg, context: { rootDir: string }): unknown | Promise<unknown>;
+};
+
+/** Model and reasoning effort chosen by a harness matrix permutation. */
+export type HarnessSelection = {
+  model?: string | undefined;
+  effort?: ReasoningEffort | undefined;
+};
+
 export type DriverPlugin<Cfg = unknown> = {
   name: string;
   configSchema?: z.ZodTypeAny;
   create: (config: Cfg) => AgentDriver | Promise<AgentDriver>;
+  runtime?: (config: Cfg) => DriverRuntime;
+  /** Ordinary runs remain supported when controlled experiments are not declared. */
+  experiment?: DriverExperiment<Cfg>;
+  /**
+   * Apply a matrix selection to raw (unvalidated) configuration. Drivers
+   * without a model concept leave this undefined and reject selection.
+   */
+  selectHarness?: (config: unknown, selection: HarnessSelection) => unknown;
 };
+
+/** Selection for drivers whose configuration uses `model` and `reasoningEffort`. */
+export const selectModelAndReasoningEffort = (
+  config: unknown,
+  selection: HarnessSelection,
+): unknown => ({
+  ...(config && typeof config === "object" && !Array.isArray(config)
+    ? (config as Record<string, unknown>)
+    : {}),
+  ...(selection.model !== undefined ? { model: selection.model } : {}),
+  ...(selection.effort !== undefined || selection.model !== undefined
+    ? { reasoningEffort: selection.effort }
+    : {}),
+});
+
+export const defineDriver = <S extends z.ZodType>(
+  definition: Omit<DriverPlugin<z.output<S>>, "configSchema"> & { configSchema: S },
+): Omit<DriverPlugin<z.output<S>>, "configSchema"> & { configSchema: S } => definition;
+
+export const driverRef = <S extends z.ZodType>(
+  plugin: { name: string; configSchema: S },
+  config: z.input<S>,
+  execution?: DriverExecution,
+): { name: string; config: z.input<S>; execution?: DriverExecution } => ({
+  name: plugin.name,
+  config,
+  ...(execution ? { execution } : {}),
+});

package/src/core/duration.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+const UNITS: Record<string, number> = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60_000,
+  minute: 60_000,
+  minutes: 60_000,
+  h: 3_600_000,
+  hour: 3_600_000,
+  hours: 3_600_000,
+  d: 86_400_000,
+  day: 86_400_000,
+  days: 86_400_000,
+};
+const MAX_TIMER_MS = 2_147_483_647;
+const INVALID_DURATION =
+  'Expected a positive duration such as "20 minutes", "1.5 hours", or "500 ms", up to 2147483647 milliseconds';
+
+/** Explicit units prevent ambiguous numeric configuration and Node timer overflow. */
+export const durationMs = (value: string): number => {
+  if (value.length > 80) throw new Error(INVALID_DURATION);
+  const match =
+    /^(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|seconds?|m|minutes?|h|hours?|d|days?)$/i.exec(
+      value.trim(),
+    );
+  const amount = match?.[1];
+  const multiplier = match?.[2] ? UNITS[match[2].toLowerCase()] : undefined;
+  if (!amount || !multiplier) throw new Error(INVALID_DURATION);
+  const [whole, fraction = ""] = amount.split(".");
+  const scale = 10n ** BigInt(fraction.length);
+  const numerator = BigInt(`${whole}${fraction}`) * BigInt(multiplier);
+  const milliseconds = numerator / scale;
+  if (numerator % scale !== 0n || milliseconds <= 0n || milliseconds > BigInt(MAX_TIMER_MS)) {
+    throw new Error(INVALID_DURATION);
+  }
+  return Number(milliseconds);
+};
+
+// Keep strings in validated configs: schema validation may run again during
+// experiment preparation or replay. Conversion belongs at the timer boundary.
+export const DurationSchema = z.string().superRefine((value, ctx) => {
+  try {
+    durationMs(value);
+  } catch {
+    ctx.addIssue({ code: "custom", message: INVALID_DURATION });
+  }
+});

package/src/core/environment.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/** Author-declared execution conditions. Lux records these without enforcing or verifying them. */
+export const EnvironmentDeclarationSchema = z
+  .object({
+    imageDigest: z
+      .string()
+      .regex(/^(?:[^@\s]+@)?sha256:[a-f0-9]{64}$/)
+      .optional(),
+    toolchains: z.record(z.string().min(1), z.string().min(1)).optional(),
+    network: z.enum(["disabled", "restricted", "unrestricted"]).optional(),
+    resources: z
+      .object({
+        cpuCount: z.number().positive().optional(),
+        memoryBytes: z.number().int().positive().optional(),
+        diskBytes: z.number().int().positive().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type EnvironmentDeclaration = z.infer<typeof EnvironmentDeclarationSchema>;

package/src/core/evaluation-clusters.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+export const EvaluationMetadataSchema = z
+  .object({
+    /** Related perturbations share one independent statistical unit. */
+    cluster: z.string().trim().min(1).optional(),
+  })
+  .catchall(z.unknown());
+
+export const clusterKey = (id: string, cluster: string | undefined): string =>
+  JSON.stringify(cluster === undefined ? ["case", id] : ["cluster", cluster]);
+
+export const independentClusterCount = (
+  items: readonly { id: string; cluster?: string | undefined }[],
+): number => new Set(items.map((item) => clusterKey(item.id, item.cluster))).size;
+
+export const assertDisjointClusters = (
+  splits: readonly {
+    name: string;
+    items: readonly { id: string; cluster?: string | undefined }[];
+  }[],
+): void => {
+  const owners = new Map<string, string>();
+  for (const split of splits) {
+    for (const item of split.items) {
+      if (item.cluster === undefined) continue;
+      const owner = owners.get(item.cluster);
+      if (owner !== undefined && owner !== split.name)
+        throw new Error(
+          `evaluation cluster '${item.cluster}' appears in both ${owner} and ${split.name} splits`,
+        );
+      owners.set(item.cluster, split.name);
+    }
+  }
+};