@hue-run/sdk 0.1.5 → 0.2.0

package/dist/evals/environment-json.js

@@ -0,0 +1,76 @@
+function validText(value) {
+    return value.isWellFormed() && !value.includes("\u0000");
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function environmentJson(value, maxBytes = 200_000, maxDepth = 32, maxNodes = 20_000) {
+    const pending = [{ value, depth: 0 }];
+    const seen = new Set();
+    let nodes = 0;
+    while (pending.length) {
+        const current = pending.pop();
+        if (++nodes > maxNodes || current.depth > maxDepth)
+            throw new RangeError("Environment JSON exceeds depth/node limits");
+        const item = current.value;
+        if (item === null || typeof item === "boolean")
+            continue;
+        if (typeof item === "number" && Number.isFinite(item))
+            continue;
+        if (typeof item === "string" && validText(item))
+            continue;
+        if (!item || typeof item !== "object" || seen.has(item))
+            throw new TypeError("Expected finite environment JSON without cycles or invalid Unicode");
+        seen.add(item);
+        const keys = Object.keys(item);
+        if (Array.isArray(item)) {
+            if (keys.length !== item.length)
+                throw new TypeError("Sparse/extended arrays are not JSON");
+        }
+        else if (Object.getPrototypeOf(item) !== Object.prototype &&
+            Object.getPrototypeOf(item) !== null)
+            throw new TypeError("Environment JSON objects must be plain objects");
+        if (Object.getOwnPropertySymbols(item).length)
+            throw new TypeError("Environment JSON cannot contain symbol properties");
+        for (const key of keys) {
+            if (!validText(key))
+                throw new TypeError("Invalid environment JSON key");
+            const descriptor = Object.getOwnPropertyDescriptor(item, key);
+            if (!("value" in descriptor))
+                throw new TypeError("Environment JSON cannot contain accessors");
+            pending.push({ value: descriptor.value, depth: current.depth + 1 });
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > maxBytes)
+        throw new RangeError("Environment JSON exceeds byte limit");
+}
+export function validateEvidenceWorld(value) {
+    environmentJson(value, 200_000, 35, 200_000);
+    if (!record(value) || Object.keys(value).length !== 1 || !record(value.collections))
+        throw new TypeError("Expected an environment world");
+    const collections = Object.entries(value.collections);
+    if (collections.length > 64)
+        throw new RangeError("Environment world exceeds 64 collections");
+    let entities = 0;
+    for (const [name, entries] of collections) {
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(name) || !record(entries))
+            throw new TypeError("Invalid environment collection");
+        for (const [id, entity] of Object.entries(entries)) {
+            if (++entities > 2000)
+                throw new RangeError("Environment world exceeds 2000 entities");
+            if (!id.length || id.length > 200 || id === "__proto__" || !record(entity))
+                throw new TypeError("Invalid environment entity");
+            environmentJson(entity);
+        }
+    }
+}
+export function validateEvidenceArguments(value) {
+    environmentJson(value, 256 * 1024, 33, 256 * 1024);
+    if (!record(value))
+        throw new TypeError("Expected environment argument object");
+    for (const [name, argument] of Object.entries(value)) {
+        if (!name.length || name.length > 64)
+            throw new TypeError("Invalid environment argument name");
+        environmentJson(argument);
+    }
+}

package/dist/evals/json.d.ts

@@ -1,6 +1,14 @@
 import type { JsonValue } from "../types.js";
+export type JsonBounds = {
+    bytes: number;
+    nodes: number;
+    depth: number;
+};
+export declare const valueBounds: JsonBounds;
+export declare function aggregateBounds(bytes: number): JsonBounds;
 /** Reject lossy JSON serialization before creating requests/checkpoints. */
-export declare function json(value: unknown, maxBytes?: number): JsonValue;
+export declare function json(value: unknown, requested?: JsonBounds | number): JsonValue;
 export declare function digest(value: unknown): string;
+/** SHA-256 hex digest of scorer source, as declared in a `local_code` definition. */
 export declare function sourceDigest(source: string | Uint8Array): string;
 export declare function uuid(value: string): string;

package/dist/evals/json.js

@@ -1,16 +1,22 @@
 import { createHash } from "node:crypto";
+export const valueBounds = { bytes: 200_000, nodes: 20_000, depth: 32 };
+export function aggregateBounds(bytes) {
+    return { bytes, nodes: Math.ceil(bytes / 2), depth: valueBounds.depth + 8 };
+}
+const isText = (item) => item.isWellFormed() && !item.includes("\u0000");
 /** Reject lossy JSON serialization before creating requests/checkpoints. */
-export function json(value, maxBytes = 200_000) {
+export function json(value, requested = valueBounds) {
+    const bounds = typeof requested === "number" ? { ...valueBounds, bytes: requested } : requested;
     const ancestors = new Set();
     let nodes = 0;
     const visit = (item, depth) => {
-        if (++nodes > 20_000 || depth > 32)
+        if (++nodes > bounds.nodes || depth > bounds.depth)
             throw new RangeError("JSON exceeds depth/node limits");
         if (item === null || typeof item === "boolean")
             return item;
         if (typeof item === "number" && Number.isFinite(item))
             return item;
-        if (typeof item === "string" && item.isWellFormed() && !item.includes("\u0000"))
+        if (typeof item === "string" && isText(item))
             return item;
         if (!item || typeof item !== "object" || ancestors.has(item))
             throw new TypeError("Expected finite JSON without cycles or invalid Unicode");
@@ -27,7 +33,8 @@ export function json(value, maxBytes = 200_000) {
                 throw new TypeError("JSON cannot contain symbol properties");
             const result = Object.create(null);
             for (const key of Object.keys(item).sort()) {
-                visit(key, depth + 1);
+                if (!isText(key))
+                    throw new TypeError("Expected finite JSON without cycles or invalid Unicode");
                 const descriptor = Object.getOwnPropertyDescriptor(item, key);
                 if (!("value" in descriptor))
                     throw new TypeError("JSON cannot contain accessors");
@@ -41,15 +48,16 @@ export function json(value, maxBytes = 200_000) {
         }
     };
     const result = visit(value, 0);
-    if (Buffer.byteLength(JSON.stringify(result)) > maxBytes)
+    if (Buffer.byteLength(JSON.stringify(result)) > bounds.bytes)
         throw new RangeError("JSON exceeds byte limit");
     return result;
 }
 export function digest(value) {
     return createHash("sha256")
-        .update(JSON.stringify(json(value, 8 * 1024 * 1024)))
+        .update(JSON.stringify(json(value, aggregateBounds(8 * 1024 * 1024))))
         .digest("hex");
 }
+/** SHA-256 hex digest of scorer source, as declared in a `local_code` definition. */
 export function sourceDigest(source) {
     return createHash("sha256").update(source).digest("hex");
 }

package/dist/evals/runner.d.ts

@@ -2,47 +2,106 @@ import type { HueClient } from "../client.js";
 import type { HueSpan } from "../types.js";
 import { EvaluationClient } from "./client.js";
 import type { ExperimentCase, JsonValue, LocalScorer } from "./types.js";
+/**
+ * Thrown when a case has a started attempt without a saved outcome. The runner never reruns the
+ * target; inspect the execution and authorize a new attempt explicitly through `startExecution`.
+ */
 export declare class UncertainExecutionError extends Error {
+    /** The affected case (experiment item) ID. */
     readonly caseId: string;
+    /** The execution without a saved outcome, when known. */
     readonly executionId?: string | undefined;
-    constructor(caseId: string, executionId?: string | undefined);
+    constructor(
+    /** The affected case (experiment item) ID. */
+    caseId: string, 
+    /** The execution without a saved outcome, when known. */
+    executionId?: string | undefined);
 }
+/** Thrown when a completed target's output is not serializable JSON; the target is not invoked again. */
 export declare class OutcomeSerializationError extends Error {
+    /** The execution whose output could not be serialized. */
     readonly executionId: string;
-    constructor(executionId: string);
+    constructor(
+    /** The execution whose output could not be serialized. */
+    executionId: string);
+}
+/** Thrown when cooperative caller cancellation stops target execution. */
+export declare class TargetCancelledError extends Error {
+    constructor();
+}
+/** Thrown when the target or world may have committed but acknowledgement is unavailable. */
+export declare class TargetOutcomeUncertainError extends Error {
+    /** Execution whose target outcome must never be replayed automatically. */
+    readonly executionId: string;
+    constructor(
+    /** Execution whose target outcome must never be replayed automatically. */
+    executionId: string, options?: ErrorOptions);
 }
 interface RunnerOptions {
+    /** Evaluation API client for the same project and origin as `hue`. */
     client: EvaluationClient;
+    /** Dedicated directory (mode 0700) for resumable checkpoints; one per experiment or rescore run. */
     checkpointDirectory: string;
+    /** Whether outputs, error messages, evidence and explanations are stored in Hue and in checkpoints. Required. */
     persistResultContent: boolean;
+    /** Local callbacks bound to `local_code` scorer pins by digest. */
     scorers?: LocalScorer[];
+    /** Cases in flight at once, 1–16. Default 1. */
     concurrency?: number;
+    /** Deadline for JSON Schema scoring in its worker, 100–60000 ms. Default 2000. */
     schemaTimeoutMillis?: number;
+    /** Resolve sealed world evidence for local scoring and historical rescoring. */
+    environmentEvidence?: "required";
 }
+/** Options for {@link runExperiment}. */
 export interface RunExperimentOptions extends RunnerOptions {
+    /** Hue tracing client; each case runs inside a `hue.experiment.case` span. */
     hue: HueClient;
+    /** Experiment to run; its dataset version must be frozen. */
     experimentId: string;
+    /** Whether each case waits for acknowledged trace export or explicitly omits evidence. Required. */
     traceEvidence: {
+        /** Wait for trace and log acknowledgement after the case span ends. */
         mode: "required";
     } | {
+        /** Store the declared trace ID without evidence. */
         mode: "omit";
+        /** Why evidence is omitted, up to 4000 characters. */
         reason: string;
     };
+    /** Runs the application for one frozen case; return the output, or `undefined` when unavailable. */
     target(inputs: JsonValue, context: {
         config: JsonValue;
         item: ExperimentCase;
         span: HueSpan;
+        executionId: string;
     }): JsonValue | undefined | Promise<JsonValue | undefined>;
 }
+/** Options for {@link rescore}. */
 export interface RescoreOptions extends RunnerOptions {
+    /** Evaluation run created with `createEvaluationRun` over existing subjects. */
     runId: string;
 }
+/** Outcome of a runner call. */
 export interface RunnerReport {
+    /** Evaluation run the results belong to. */
     runId: string;
+    /** Subjects created or scored, in completion order. */
     subjectIds: string[];
+    /** Result IDs uploaded by this call. */
     resultIds: string[];
+    /** `llm_judge` and `manual` pins left pending for hosted or human scoring. */
     deferredScorerVersionIds: string[];
 }
+/**
+ * Runs every case of a frozen experiment through `target` on this machine, completes each
+ * execution, scores it with local scorers and uploads the results, checkpointing so an interrupted
+ * run resumes without invoking the target twice.
+ *
+ * @throws UncertainExecutionError when a case has a started attempt without a saved outcome.
+ * @throws OutcomeSerializationError when a completed target's output is not serializable.
+ * @throws HueApiError for evaluation API failures; the checkpoint keeps prepared payloads for a retry.
+ */
 export declare function runExperiment(options: RunExperimentOptions): Promise<RunnerReport>;
 /** Scores existing immutable subjects; this API has no target callback. */
 export declare function rescore(options: RescoreOptions): Promise<RunnerReport>;

package/dist/evals/runner.js

@@ -1,28 +1,60 @@
 import { randomUUID } from "node:crypto";
 import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { HueExportError } from "../transport.js";
+import { loadEnvironmentEvidence } from "./environment-evidence.js";
 import { CheckpointStore } from "./checkpoint.js";
 import { json, uuid } from "./json.js";
 import { persistedScore, scoreLocally, validateScorerBindings } from "./scorers.js";
+/**
+ * Thrown when a case has a started attempt without a saved outcome. The runner never reruns the
+ * target; inspect the execution and authorize a new attempt explicitly through `startExecution`.
+ */
 export class UncertainExecutionError extends Error {
     caseId;
     executionId;
-    constructor(caseId, executionId) {
+    constructor(
+    /** The affected case (experiment item) ID. */
+    caseId, 
+    /** The execution without a saved outcome, when known. */
+    executionId) {
         super("Execution has no saved outcome. The target will not run again. Inspect it and explicitly authorize a new attempt through startExecution if required.");
         this.caseId = caseId;
         this.executionId = executionId;
         this.name = "UncertainExecutionError";
     }
 }
+/** Thrown when a completed target's output is not serializable JSON; the target is not invoked again. */
 export class OutcomeSerializationError extends Error {
     executionId;
-    constructor(executionId) {
+    constructor(
+    /** The execution whose output could not be serialized. */
+    executionId) {
         super("Target completed, but its output could not be serialized. Resolve completion explicitly; the runner will not invoke the target again.");
         this.executionId = executionId;
         this.name = "OutcomeSerializationError";
     }
 }
+/** Thrown when cooperative caller cancellation stops target execution. */
+export class TargetCancelledError extends Error {
+    constructor() {
+        super("Target execution was cancelled");
+        this.name = "TargetCancelledError";
+    }
+}
+/** Thrown when the target or world may have committed but acknowledgement is unavailable. */
+export class TargetOutcomeUncertainError extends Error {
+    executionId;
+    constructor(
+    /** Execution whose target outcome must never be replayed automatically. */
+    executionId, options) {
+        super(`Target outcome or environment finalization is uncertain for execution ${executionId}; resume will not invoke the target again`, options);
+        this.executionId = executionId;
+        this.name = "TargetOutcomeUncertainError";
+    }
+}
 function settings(options) {
+    if (options.environmentEvidence !== undefined && options.environmentEvidence !== "required")
+        throw new TypeError("environmentEvidence must be required when supplied");
     if (typeof options.persistResultContent !== "boolean")
         throw new TypeError("Choose persistResultContent explicitly: true or false");
     const concurrency = options.concurrency ?? 1;
@@ -70,13 +102,27 @@ async function pool(items, concurrency, execute) {
     if (failures.length)
         throw new AggregateError(failures, "Multiple case operations failed; resume uses saved outcomes");
 }
-async function scoresFor(versions, context, options) {
+async function scoresFor(versions, context, options, executionId) {
     const scores = [];
+    let environmentUnavailable = false;
+    if (options.environmentEvidence === "required") {
+        try {
+            context = {
+                ...context,
+                environment: await loadEnvironmentEvidence(options.client, executionId),
+            };
+        }
+        catch {
+            environmentUnavailable = true;
+        }
+    }
     for (const version of versions) {
         // Hosted/manual pins remain pending for their authorized executor.
         if (version.definition.kind === "llm_judge" || version.definition.kind === "manual")
             continue;
-        const score = persistedScore(await scoreLocally(version, context, options), options.persistResultContent);
+        const score = persistedScore(environmentUnavailable && version.definition.kind === "local_code"
+            ? { state: "error", error: { type: "EnvironmentEvidenceUnavailable" } }
+            : await scoreLocally(version, context, options), options.persistResultContent);
         scores.push({
             key: randomUUID(),
             payload: {
@@ -104,6 +150,15 @@ async function uploadScores(options, runId, scores, save) {
         await save();
     }
 }
+/**
+ * Runs every case of a frozen experiment through `target` on this machine, completes each
+ * execution, scores it with local scorers and uploads the results, checkpointing so an interrupted
+ * run resumes without invoking the target twice.
+ *
+ * @throws UncertainExecutionError when a case has a started attempt without a saved outcome.
+ * @throws OutcomeSerializationError when a completed target's output is not serializable.
+ * @throws HueApiError for evaluation API failures; the checkpoint keeps prepared payloads for a retry.
+ */
 export async function runExperiment(options) {
     const concurrency = settings(options);
     if (!options.traceEvidence || !["required", "omit"].includes(options.traceEvidence.mode))
@@ -142,6 +197,7 @@ export async function runExperiment(options) {
         persistResultContent: options.persistResultContent,
         captureContent: options.hue.captureContent,
         traceEvidence: options.traceEvidence,
+        ...(options.environmentEvidence ? { environmentEvidence: options.environmentEvidence } : {}),
     });
     const report = {
         runId: experiment.evaluation.id,
@@ -172,6 +228,8 @@ export async function runExperiment(options) {
                 const frozenCase = await options.client.getExperimentCase(experiment.id, item.id);
                 if (frozenCase.datasetVersionId !== version.id)
                     throw new Error("Case is not from the pinned dataset version");
+                const targetInputs = json(frozenCase.inputs);
+                const targetConfig = json(experiment.config);
                 const failureSequenceBefore = options.hue.transport.getFailureSequence();
                 checkpoint = await options.hue.withSpan("hue.experiment.case", async (span) => {
                     const start = {
@@ -189,14 +247,17 @@ export async function runExperiment(options) {
                     let output;
                     let targetError;
                     try {
-                        output = await options.target(json(frozenCase.inputs), {
-                            config: json(experiment.config),
+                        output = await options.target(targetInputs, {
+                            config: targetConfig,
                             item: structuredClone(frozenCase),
                             span,
+                            executionId: execution.id,
                         });
                     }
                     catch (error) {
-                        state = "error";
+                        if (error instanceof TargetOutcomeUncertainError)
+                            throw error;
+                        state = error instanceof TargetCancelledError ? "cancelled" : "error";
                         targetError = error;
                         options.hue.recordError(span.span, error);
                     }
@@ -223,7 +284,7 @@ export async function runExperiment(options) {
                         hasOutput: output !== undefined,
                         ...(output !== undefined ? { output } : {}),
                         executionState: state,
-                    }, options);
+                    }, options, execution.id);
                     const complete = {
                         idempotencyKey: randomUUID(),
                         state,
@@ -327,6 +388,7 @@ export async function rescore(options) {
             .map(({ id, contentDigest }) => ({ id, contentDigest }))
             .sort((a, b) => a.id.localeCompare(b.id)),
         persistResultContent: options.persistResultContent,
+        ...(options.environmentEvidence ? { environmentEvidence: options.environmentEvidence } : {}),
     });
     const report = {
         runId: run.id,
@@ -350,7 +412,7 @@ export async function rescore(options) {
                     ...(subject.hasExpected ? { expected: subject.expected } : {}),
                     metadata: subject.metadata,
                     executionState: subject.executionState,
-                }, options);
+                }, options, subject.executionId);
                 for (const score of scores)
                     score.payload.evaluationItemId = item.id;
                 saved = { scores };

package/dist/evals/scorer-publication.d.ts

@@ -0,0 +1,2 @@
+import type { ScorerDefinition } from "./types.js";
+export declare function normalizeScorerDefinitionForPublication(definition: unknown): ScorerDefinition;

package/dist/evals/scorer-publication.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { json } from "./json.js";
+const metricName = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/);
+const metric = z.discriminatedUnion("type", [
+    z.strictObject({ name: metricName, type: z.literal("boolean") }),
+    z.strictObject({ name: metricName, type: z.literal("text") }),
+    z.strictObject({
+        name: metricName,
+        type: z.literal("number"),
+        min: z.number().finite().optional(),
+        max: z.number().finite().optional(),
+    }),
+    z.strictObject({
+        name: metricName,
+        type: z.literal("category"),
+        categories: z.array(z.string()).min(1),
+    }),
+]);
+const metrics = z.array(metric).min(1);
+const jsonValue = z.custom((value) => {
+    try {
+        json(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+});
+const judgeConfig = z.strictObject({
+    model: z.string(),
+    provider: z.string(),
+    rubric: z.string().trim(),
+    bindings: z.array(z.strictObject({
+        name: z.string(),
+        path: z.string(),
+        required: z.boolean().default(true),
+    })),
+    maxOutputTokens: z.number().default(1024),
+    timeoutMs: z.number().default(60_000),
+    temperature: z.number().optional(),
+});
+/** Closed client-side publication contract. The server remains authoritative for
+ * full validation; this parser only applies defaults that affect immutable content
+ * identity and rejects server-only scorer kinds before any write. A differential
+ * test against the server schema guards this deliberately duplicated boundary.
+ */
+const sdkScorerPublication = z.union([
+    z.strictObject({
+        kind: z.literal("builtin"),
+        entry: z.literal("hue.exact_match.v1"),
+        config: z.strictObject({}).default({}),
+    }),
+    z.strictObject({
+        kind: z.literal("builtin"),
+        entry: z.literal("hue.includes.v1"),
+        config: z
+            .strictObject({ caseSensitive: z.boolean().default(true) })
+            .default({ caseSensitive: true }),
+    }),
+    z.strictObject({
+        kind: z.literal("builtin"),
+        entry: z.literal("hue.json_schema.v1"),
+        config: z.strictObject({ schema: jsonValue }),
+    }),
+    z.strictObject({
+        kind: z.literal("local_code"),
+        language: z.enum(["typescript", "python"]),
+        entrypoint: z.string(),
+        sourceDigest: z.string(),
+        metrics,
+    }),
+    z.strictObject({ kind: z.literal("manual"), metrics }),
+    z.strictObject({ kind: z.literal("llm_judge"), config: judgeConfig, metrics }),
+]);
+export function normalizeScorerDefinitionForPublication(definition) {
+    const normalized = sdkScorerPublication.safeParse(definition);
+    if (!normalized.success)
+        throw new TypeError("Unsupported or invalid SDK scorer definition");
+    return json(normalized.data);
+}

package/dist/evals/scorers.d.ts

@@ -1,7 +1,11 @@
 import type { JsonValue, LocalScorer, MetricDefinition, Score, ScoreContext, ScorerDefinition, ScorerVersion } from "./types.js";
+/** Definitions for Hue's built-in scorers, ready to publish with `publishScorerVersion`. */
 export declare const builtins: {
+    /** Exact typed JSON equality with the reference output; key order is ignored. */
     exactMatch: () => ScorerDefinition;
+    /** The string reference output is contained in the string output. */
     includes: (caseSensitive?: boolean) => ScorerDefinition;
+    /** The output satisfies a JSON Schema (draft 2020-12), validated with the optional `ajv` peer in a worker. */
     jsonSchema: (schema: JsonValue) => ScorerDefinition;
 };
 /** The source hash is a caller declaration; closures and installed dependencies are not attested. */
@@ -13,6 +17,13 @@ export declare function defineLocalScorer(options: {
 }): LocalScorer;
 /** Check local callbacks before target invocation; never execute downloaded source code. */
 export declare function validateScorerBindings(versions: ScorerVersion[], scorers?: LocalScorer[]): void;
+/**
+ * Scores one subject with a pinned scorer version on this machine: built-ins run here, `local_code`
+ * pins run the matching callback from `options.scorers`, `manual` pins are skipped. Failures are
+ * returned as sanitized error scores.
+ *
+ * @throws TypeError for an `llm_judge` pin, which must be dispatched through `createJudgeJobs`.
+ */
 export declare function scoreLocally(version: ScorerVersion, context: ScoreContext, options?: {
     scorers?: LocalScorer[];
     schemaTimeoutMillis?: number;

package/dist/evals/scorers.js

@@ -1,17 +1,23 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { Worker } from "node:worker_threads";
-import { digest, json, sourceDigest } from "./json.js";
+import { aggregateBounds, digest, json, sourceDigest } from "./json.js";
+import { environmentIncompleteReason, validateEnvironmentEvidence, } from "./environment-evidence.js";
+/** Definitions for Hue's built-in scorers, ready to publish with `publishScorerVersion`. */
 export const builtins = {
+    /** Exact typed JSON equality with the reference output; key order is ignored. */
     exactMatch: () => ({
         kind: "builtin",
         entry: "hue.exact_match.v1",
         config: {},
     }),
+    /** The string reference output is contained in the string output. */
     includes: (caseSensitive = true) => ({
         kind: "builtin",
         entry: "hue.includes.v1",
         config: { caseSensitive },
     }),
+    /** The output satisfies a JSON Schema (draft 2020-12), validated with the optional `ajv` peer in a worker. */
     jsonSchema: (schema) => ({
         kind: "builtin",
         entry: "hue.json_schema.v1",
@@ -31,7 +37,25 @@ export function defineLocalScorer(options) {
         score: options.score,
     };
 }
+/** ajv is an optional peer dependency: only JSON Schema scoring loads it, inside a worker. */
+function schemaValidatorAvailable() {
+    try {
+        createRequire(import.meta.url).resolve("ajv/dist/2020.js");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function schemaScore(schema, output, timeoutMillis) {
+    if (!schemaValidatorAvailable())
+        return Promise.resolve({
+            state: "error",
+            error: {
+                type: "SchemaValidatorUnavailable",
+                message: "JSON Schema scoring requires the optional ajv peer dependency: npm install ajv",
+            },
+        });
     return new Promise((resolve) => {
         const compiled = new URL("./schema-worker.js", import.meta.url);
         const file = existsSync(compiled) ? compiled : new URL("./schema-worker.ts", import.meta.url);
@@ -75,6 +99,13 @@ export function validateScorerBindings(versions, scorers = []) {
             throw new Error("A pinned local scorer has no matching language/source/entrypoint/metric binding");
     }
 }
+/**
+ * Scores one subject with a pinned scorer version on this machine: built-ins run here, `local_code`
+ * pins run the matching callback from `options.scorers`, `manual` pins are skipped. Failures are
+ * returned as sanitized error scores.
+ *
+ * @throws TypeError for an `llm_judge` pin, which must be dispatched through `createJudgeJobs`.
+ */
 export async function scoreLocally(version, context, options = {}) {
     const definition = version.definition;
     if (definition.kind === "llm_judge")
@@ -82,13 +113,25 @@ export async function scoreLocally(version, context, options = {}) {
     const timeout = options.schemaTimeoutMillis ?? 2000;
     if (!Number.isInteger(timeout) || timeout < 100 || timeout > 60_000)
         throw new RangeError("schemaTimeoutMillis must be 100–60000");
-    if (!context.hasOutput)
+    if (context.environment?.validity === "environment_incomplete") {
+        try {
+            validateEnvironmentEvidence(context.environment);
+            return skip(environmentIncompleteReason);
+        }
+        catch {
+            return { state: "error", error: { type: "LocalScorerError" } };
+        }
+    }
+    if (!context.hasOutput && !(definition.kind === "local_code" && context.environment))
         return skip("Output evidence is unavailable");
-    if (context.output === undefined)
+    if (context.hasOutput && context.output === undefined)
         throw new TypeError("hasOutput requires a present JSON output");
     try {
         // Clone and validate inputs so a scorer cannot mutate another scorer's evidence.
-        json(context, 1024 * 1024);
+        const { environment, ...ordinaryEvidence } = context;
+        json(ordinaryEvidence, aggregateBounds(1024 * 1024));
+        if (environment !== undefined)
+            validateEnvironmentEvidence(environment);
         const owned = structuredClone(context);
         if (definition.kind === "manual")
             return skip("Manual scoring requires a human session");
@@ -195,9 +238,17 @@ export function persistedScore(score, persistResultContent) {
             explanation: "Local scoring completed; result content storage disabled",
         };
     if (score.state === "error")
-        return { state: "error", error: { type: "LocalScorerError" } };
+        return {
+            state: "error",
+            error: {
+                type: score.error.type === "EnvironmentEvidenceUnavailable"
+                    ? "EnvironmentEvidenceUnavailable"
+                    : "LocalScorerError",
+            },
+        };
     // Preserve fixed unavailable reasons, never arbitrary caller explanations.
     const safeReasons = [
+        environmentIncompleteReason,
         "Output evidence is unavailable",
         "Reference evidence is unavailable",
         "Includes requires string output and reference",