@hue-run/sdk 0.1.5 → 0.2.1

package/dist/evals/client.d.ts

@@ -1,41 +1,73 @@
 import type { ProjectConnection } from "../types.js";
-import type { CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, JudgeBudget, JudgeJob, Page, PageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, StartExecution, Subject, StoredResult } from "./types.js";
+import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
+import type { CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, SimulationMcpCapability, StartExecution, Subject, StoredResult } from "./types.js";
+/** Connection options for {@link createEvaluationClient}. */
 export interface EvaluationClientOptions {
+    /** Project service key sent as a Bearer token; server side only. */
     apiKey: string;
+    /** Hue origin, `https://app.hue.run` by default; HTTPS except for loopback. */
     baseUrl?: string;
+    /** Per-request budget in milliseconds, 100–60000. Default 10000. */
     timeoutMillis?: number;
 }
+/** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
 export declare class HueApiError extends Error {
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
     readonly status?: number | undefined;
-    constructor(status?: number | undefined);
+    constructor(
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
+    status?: number | undefined);
 }
-/** No implicit mutation retry: callers retain stable idempotency keys for experiments/results. */
+/**
+ * Typed client for Hue's evaluation REST API: datasets, scorers, experiments, executions, runs,
+ * results and hosted judge jobs. No implicit mutation retry: callers retain stable idempotency keys
+ * for experiments and results. Responses are bounded to 4 MiB.
+ */
 export declare class EvaluationClient {
+    /** Validated Hue origin. */
     readonly baseUrl: string;
     private readonly apiKey;
     private readonly timeoutMillis;
     constructor(options: EvaluationClientOptions);
     private request;
     private page;
+    private registryPage;
+    /** Reads the current project to confirm the key and origin. */
     checkConnection(): Promise<ProjectConnection>;
+    /** Creates a dataset with an initial draft version. */
     createDataset(input: Identity): Promise<Dataset>;
+    /** Reads a dataset and its versions. */
     getDataset(id: string): Promise<Dataset>;
-    listDatasets(page?: PageOptions): Promise<Page<Omit<Dataset, "versions">>>;
+    /** Lists datasets without their versions. */
+    listDatasets(page?: RegistryPageOptions): Promise<Page<Omit<Dataset, "versions">>>;
+    /** Creates a new draft version, optionally copying cases from an existing version. */
     createDatasetVersion(id: string, input?: {
         fromVersionId?: string;
     }): Promise<DatasetVersion>;
+    /** Reads a dataset version. */
     getDatasetVersion(id: string): Promise<DatasetVersion>;
+    /** Lists the full cases of a dataset version; use small page limits for large values. */
     listCases(id: string, page?: PageOptions): Promise<Page<DatasetCase>>;
+    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
     addCase(id: string, input: CaseWrite): Promise<{
+        /** The stored case. */
         item: DatasetCase;
+        /** The version with its new revision. */
         version: DatasetVersion;
     }>;
+    /** Freezes a draft version at the given revision; frozen versions are immutable. */
     freezeDatasetVersion(id: string, expectedRevision: number): Promise<DatasetVersion>;
+    /** Creates a scorer identity; publish definitions with {@link publishScorerVersion}. */
     createScorer(input: Identity): Promise<Scorer>;
+    /** Reads a scorer and its published versions. */
     getScorer(id: string): Promise<Scorer>;
-    listScorers(page?: PageOptions): Promise<Page<Scorer>>;
+    /** Lists scorers. */
+    listScorers(page?: RegistryPageOptions): Promise<Page<Scorer>>;
+    /** Publishes an immutable scorer version; the server validates the pinned definition. */
     publishScorerVersion(id: string, definition: ScorerDefinition): Promise<ScorerVersion>;
+    /** Reads a published scorer version. */
     getScorerVersion(id: string): Promise<ScorerVersion>;
+    /** Creates an experiment over a frozen dataset version with pinned scorer versions and a configuration. */
     createExperiment(input: {
         idempotencyKey: string;
         name: string;
@@ -43,38 +75,82 @@ export declare class EvaluationClient {
         scorerVersionIds: string[];
         config: JsonValue;
     }): Promise<{
+        /** Experiment ID. */
         id: string;
+        /** ID of the experiment's evaluation run. */
         evaluationRunId: string;
     }>;
+    /** Reads an experiment with its evaluation run and execution counts. */
     getExperiment(id: string): Promise<Experiment>;
+    /** Lists an experiment's cases with their latest executions. */
     listExperimentItems(id: string, page?: PageOptions): Promise<Page<ExperimentItem>>;
+    /** Reads one frozen case of an experiment. */
     getExperimentCase(id: string, caseId: string): Promise<ExperimentCase>;
+    /** Starts (or, with the same key, replays) a target execution for a case. */
     startExecution(id: string, caseId: string, input: StartExecution): Promise<Execution>;
+    /** Reads an execution. */
     getExecution(id: string): Promise<Execution>;
+    /** Reads the sealed environment evidence linked to an execution. */
+    getEnvironmentEvidence(executionId: string): Promise<EnvironmentEvidenceSnapshot>;
+    /** Pages the sealed environment journal linked to an execution. */
+    getEnvironmentSteps(executionId: string, page?: {
+        after?: number;
+        limit?: number;
+    }): Promise<import("../environment/types.js").StepPage>;
+    /**
+     * Prepares the immutable provider-profile binding for one execution. The route identity is
+     * removed from the JSON body, and credential-bearing responses are validated against the
+     * request before being returned.
+     */
+    prepareAttempt(input: PrepareAttemptRequestV2): Promise<import("./attempt.js").PrepareAttemptResultV2>;
+    /** Reads coupled, secret-free V1 or V2 binding evidence; it never reacquires credentials. */
+    getAttemptBinding(bindingId: string): Promise<import("./attempt.js").AttemptBindingRead>;
+    /** Rotates an unexpired V2 connection while preserving its immutable binding evidence. */
+    refreshAttemptConnection(previous: AttemptConnectionBundleV2, input: {
+        idempotencyKey: string;
+    }): Promise<import("./attempt.js").PrepareAttemptReadyV2>;
+    /** Revokes an attempt binding. A revoked connection must not be reused or refreshed. */
+    revokeAttemptConnection(input: {
+        bindingId: string;
+    }): Promise<import("./attempt.js").RevokeAttemptResult>;
+    /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id: string, input: CompleteExecution): Promise<Completion>;
+    /** Marks an experiment finished. */
     finishExperiment(id: string, idempotencyKey: string): Promise<{
+        /** Experiment ID. */
         id: string;
+        /** When it was finished. */
         finishedAt: string;
     }>;
+    /** Creates a historical evaluation run that rescores existing subjects with pinned scorer versions. */
     createEvaluationRun(input: {
         idempotencyKey: string;
         name: string;
         subjectIds: string[];
         scorerVersionIds: string[];
     }): Promise<{
+        /** Evaluation run ID. */
         id: string;
     }>;
+    /** Reads an evaluation run and its scoring progress. */
     getEvaluationRun(id: string): Promise<EvaluationRun>;
+    /** Lists the subjects of an evaluation run. */
     listEvaluationItems(id: string, page?: PageOptions): Promise<Page<EvaluationItem>>;
+    /** Reads an immutable subject, including output and reference when available. */
     getSubject(id: string): Promise<Subject>;
+    /** Uploads scorer results for an evaluation run; a replayed key returns the same IDs. */
     submitResults(id: string, input: {
         idempotencyKey: string;
         results: Result[];
     }): Promise<{
+        /** Stored result IDs, in input order. */
         ids: string[];
     }>;
+    /** Lists result summaries of an evaluation run. */
     listResults(id: string, page?: PageOptions): Promise<Page<ResultSummary>>;
+    /** Reads a full stored result. */
     getResult(id: string): Promise<StoredResult>;
+    /** Dispatches hosted judge jobs for `llm_judge` pins; check {@link getJudgeBudget} first. */
     createJudgeJobs(id: string, input: {
         idempotencyKey: string;
         jobs: {
@@ -82,15 +158,33 @@ export declare class EvaluationClient {
             scorerVersionId: string;
         }[];
     }): Promise<{
+        /** Created job IDs, in input order. */
         ids: string[];
     }>;
+    /** Lists hosted judge jobs of an evaluation run. */
     listJudgeJobs(id: string, page?: PageOptions): Promise<Page<JudgeJob>>;
+    /** Reads a hosted judge job, including its charge accounting. */
     getJudgeJob(id: string): Promise<JudgeJob>;
+    /** Requests cancellation of a hosted judge job. */
     cancelJudgeJob(id: string, reason: string): Promise<{
+        /** Job ID. */
         id: string;
+        /** Job state after the request. */
         state: JudgeJob["state"];
+        /** Whether a cancellation request was recorded. */
         cancellationRequested?: boolean;
     }>;
+    /** Reads the project's hosted judge budget and admission controls. */
     getJudgeBudget(): Promise<JudgeBudget>;
+    /** Creates the legacy execution-scoped generic MCP capability for one world. */
+    createSimulationMcpCapability(input: {
+        runId: string;
+        executionId: string;
+    }): Promise<SimulationMcpCapability>;
 }
+/**
+ * Creates an {@link EvaluationClient}.
+ *
+ * @throws TypeError for an invalid key, origin or budget.
+ */
 export declare function createEvaluationClient(options: EvaluationClientOptions): EvaluationClient;

package/dist/evals/client.js

@@ -1,15 +1,24 @@
 import { validateOptions } from "../config.js";
-import { json, uuid } from "./json.js";
+import { json, uuid, valueBounds } from "./json.js";
+import { attemptBindingRead, parsePrepareAttemptResultV2, parseRefreshedAttemptResultV2, parseRevocationResult, prepareAttemptInputV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
+/** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
 export class HueApiError extends Error {
     status;
-    constructor(status) {
+    constructor(
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
+    status) {
         super(status ? `Hue API request failed (HTTP ${status})` : "Hue API connection or response failed");
         this.status = status;
         this.name = "HueApiError";
     }
 }
-/** No implicit mutation retry: callers retain stable idempotency keys for experiments/results. */
+/**
+ * Typed client for Hue's evaluation REST API: datasets, scorers, experiments, executions, runs,
+ * results and hosted judge jobs. No implicit mutation retry: callers retain stable idempotency keys
+ * for experiments and results. Responses are bounded to 4 MiB.
+ */
 export class EvaluationClient {
+    /** Validated Hue origin. */
     baseUrl;
     apiKey;
     timeoutMillis;
@@ -23,11 +32,11 @@ export class EvaluationClient {
         this.apiKey = validated.apiKey;
         this.timeoutMillis = validated.timeoutMillis;
     }
-    async request(method, path, body) {
+    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }) {
         // Optional top-level fields are omitted intentionally; nested undefined remains invalid.
         const payload = body === undefined
             ? undefined
-            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), 1024 * 1024));
+            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
         let response;
         try {
             response = await fetch(`${this.baseUrl}/api/v1${path}`, {
@@ -85,111 +94,231 @@ export class EvaluationClient {
         }
         return query.size ? `?${query}` : "";
     }
+    registryPage(options = {}) {
+        const query = new URLSearchParams(this.page(options).slice(1));
+        if (options.includeArchived !== undefined)
+            query.set("includeArchived", String(options.includeArchived));
+        return query.size ? `?${query}` : "";
+    }
+    /** Reads the current project to confirm the key and origin. */
     checkConnection() {
         return this.request("GET", "/projects/current");
     }
+    /** Creates a dataset with an initial draft version. */
     createDataset(input) {
         return this.request("POST", "/datasets", input);
     }
+    /** Reads a dataset and its versions. */
     getDataset(id) {
         return this.request("GET", `/datasets/${uuid(id)}`);
     }
+    /** Lists datasets without their versions. */
     listDatasets(page) {
-        return this.request("GET", `/datasets${this.page(page)}`);
+        return this.request("GET", `/datasets${this.registryPage(page)}`);
     }
+    /** Creates a new draft version, optionally copying cases from an existing version. */
     createDatasetVersion(id, input = {}) {
         return this.request("POST", `/datasets/${uuid(id)}/versions`, input);
     }
+    /** Reads a dataset version. */
     getDatasetVersion(id) {
         return this.request("GET", `/dataset-versions/${uuid(id)}`);
     }
+    /** Lists the full cases of a dataset version; use small page limits for large values. */
     listCases(id, page) {
         return this.request("GET", `/dataset-versions/${uuid(id)}/cases${this.page(page)}`);
     }
+    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
     addCase(id, input) {
         return this.request("POST", `/dataset-versions/${uuid(id)}/cases`, input);
     }
+    /** Freezes a draft version at the given revision; frozen versions are immutable. */
     freezeDatasetVersion(id, expectedRevision) {
         return this.request("POST", `/dataset-versions/${uuid(id)}/freeze`, {
             expectedRevision,
         });
     }
+    /** Creates a scorer identity; publish definitions with {@link publishScorerVersion}. */
     createScorer(input) {
         return this.request("POST", "/scorers", input);
     }
+    /** Reads a scorer and its published versions. */
     getScorer(id) {
         return this.request("GET", `/scorers/${uuid(id)}`);
     }
+    /** Lists scorers. */
     listScorers(page) {
-        return this.request("GET", `/scorers${this.page(page)}`);
+        return this.request("GET", `/scorers${this.registryPage(page)}`);
     }
+    /** Publishes an immutable scorer version; the server validates the pinned definition. */
     publishScorerVersion(id, definition) {
         return this.request("POST", `/scorers/${uuid(id)}/versions`, { definition });
     }
+    /** Reads a published scorer version. */
     getScorerVersion(id) {
         return this.request("GET", `/scorer-versions/${uuid(id)}`);
     }
+    /** Creates an experiment over a frozen dataset version with pinned scorer versions and a configuration. */
     createExperiment(input) {
         return this.request("POST", "/experiments", input);
     }
+    /** Reads an experiment with its evaluation run and execution counts. */
     getExperiment(id) {
         return this.request("GET", `/experiments/${uuid(id)}`);
     }
+    /** Lists an experiment's cases with their latest executions. */
     listExperimentItems(id, page) {
         return this.request("GET", `/experiments/${uuid(id)}/items${this.page(page)}`);
     }
+    /** Reads one frozen case of an experiment. */
     getExperimentCase(id, caseId) {
         return this.request("GET", `/experiments/${uuid(id)}/items/${uuid(caseId)}`);
     }
+    /** Starts (or, with the same key, replays) a target execution for a case. */
     startExecution(id, caseId, input) {
         return this.request("POST", `/experiments/${uuid(id)}/items/${uuid(caseId)}/start`, input);
     }
+    /** Reads an execution. */
     getExecution(id) {
         return this.request("GET", `/experiment-executions/${uuid(id)}`);
     }
+    /** Reads the sealed environment evidence linked to an execution. */
+    getEnvironmentEvidence(executionId) {
+        return this.request("GET", `/experiment-executions/${uuid(executionId)}/environment`);
+    }
+    /** Pages the sealed environment journal linked to an execution. */
+    getEnvironmentSteps(executionId, page = {}) {
+        if (page.after !== undefined && (!Number.isInteger(page.after) || page.after < -1))
+            throw new RangeError("Step cursor must be an integer at least -1");
+        if (page.limit !== undefined &&
+            (!Number.isInteger(page.limit) || page.limit < 1 || page.limit > 100))
+            throw new RangeError("Step page size must be 1–100");
+        const query = new URLSearchParams();
+        if (page.after !== undefined)
+            query.set("after", String(page.after));
+        if (page.limit !== undefined)
+            query.set("limit", String(page.limit));
+        return this.request("GET", `/experiment-executions/${uuid(executionId)}/environment/steps${query.size ? `?${query}` : ""}`);
+    }
+    /**
+     * Prepares the immutable provider-profile binding for one execution. The route identity is
+     * removed from the JSON body, and credential-bearing responses are validated against the
+     * request before being returned.
+     */
+    async prepareAttempt(input) {
+        const request = prepareAttemptInputV2.parse(input);
+        const { executionId, ...body } = request;
+        const response = await this.request("POST", `/experiment-executions/${executionId}/prepare-attempt`, body, { ...valueBounds, bytes: 128_000 });
+        try {
+            return parsePrepareAttemptResultV2(response, request);
+        }
+        catch {
+            // A malformed success response may follow a committed decision. Never expose
+            // credential-bearing response details or imply that replay is automatically safe.
+            throw new HueApiError();
+        }
+    }
+    /** Reads coupled, secret-free V1 or V2 binding evidence; it never reacquires credentials. */
+    async getAttemptBinding(bindingId) {
+        const response = await this.request("GET", `/attempt-bindings/${uuid(bindingId)}`);
+        try {
+            return attemptBindingRead.parse(response);
+        }
+        catch {
+            throw new HueApiError();
+        }
+    }
+    /** Rotates an unexpired V2 connection while preserving its immutable binding evidence. */
+    async refreshAttemptConnection(previous, input) {
+        const source = validateAttemptConnectionBundleV2(previous);
+        const response = await this.request("POST", `/attempt-bindings/${source.bindingId}/refresh`, {
+            idempotencyKey: uuid(input.idempotencyKey),
+            expectedGeneration: source.credentialGeneration,
+        }, { ...valueBounds, bytes: 128_000 });
+        try {
+            return parseRefreshedAttemptResultV2(response, source);
+        }
+        catch {
+            throw new HueApiError();
+        }
+    }
+    /** Revokes an attempt binding. A revoked connection must not be reused or refreshed. */
+    async revokeAttemptConnection(input) {
+        const bindingId = uuid(input.bindingId);
+        const response = await this.request("POST", `/attempt-bindings/${bindingId}/revoke`, {}, { ...valueBounds, bytes: 128_000 });
+        try {
+            return parseRevocationResult(response, bindingId);
+        }
+        catch {
+            throw new HueApiError();
+        }
+    }
+    /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id, input) {
         return this.request("POST", `/experiment-executions/${uuid(id)}/complete`, input);
     }
+    /** Marks an experiment finished. */
     finishExperiment(id, idempotencyKey) {
         return this.request("POST", `/experiments/${uuid(id)}/finish`, { idempotencyKey });
     }
+    /** Creates a historical evaluation run that rescores existing subjects with pinned scorer versions. */
     createEvaluationRun(input) {
         return this.request("POST", "/evaluation-runs", input);
     }
+    /** Reads an evaluation run and its scoring progress. */
     getEvaluationRun(id) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}`);
     }
+    /** Lists the subjects of an evaluation run. */
     listEvaluationItems(id, page) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}/items${this.page(page)}`);
     }
+    /** Reads an immutable subject, including output and reference when available. */
     getSubject(id) {
         return this.request("GET", `/evaluation-subjects/${uuid(id)}`);
     }
+    /** Uploads scorer results for an evaluation run; a replayed key returns the same IDs. */
     submitResults(id, input) {
         return this.request("POST", `/evaluation-runs/${uuid(id)}/results`, input);
     }
+    /** Lists result summaries of an evaluation run. */
     listResults(id, page) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}/results${this.page(page)}`);
     }
+    /** Reads a full stored result. */
     getResult(id) {
         return this.request("GET", `/evaluation-results/${uuid(id)}`);
     }
+    /** Dispatches hosted judge jobs for `llm_judge` pins; check {@link getJudgeBudget} first. */
     createJudgeJobs(id, input) {
         return this.request("POST", `/evaluation-runs/${uuid(id)}/judge-jobs`, input);
     }
+    /** Lists hosted judge jobs of an evaluation run. */
     listJudgeJobs(id, page) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}/judge-jobs${this.page(page)}`);
     }
+    /** Reads a hosted judge job, including its charge accounting. */
     getJudgeJob(id) {
         return this.request("GET", `/judge-jobs/${uuid(id)}`);
     }
+    /** Requests cancellation of a hosted judge job. */
     cancelJudgeJob(id, reason) {
         return this.request("POST", `/judge-jobs/${uuid(id)}/cancel`, { reason });
     }
+    /** Reads the project's hosted judge budget and admission controls. */
     getJudgeBudget() {
         return this.request("GET", "/judge-budget");
     }
+    /** Creates the legacy execution-scoped generic MCP capability for one world. */
+    createSimulationMcpCapability(input) {
+        return this.request("POST", "/local-agent-worker/mcp-capability", input);
+    }
 }
+/**
+ * Creates an {@link EvaluationClient}.
+ *
+ * @throws TypeError for an invalid key, origin or budget.
+ */
 export function createEvaluationClient(options) {
     return new EvaluationClient(options);
 }

package/dist/evals/environment-evidence.d.ts

@@ -0,0 +1,6 @@
+import type { EvaluationClient } from "./client.js";
+import type { EnvironmentEvidence } from "./types.js";
+export declare const MAX_ENVIRONMENT_STEPS = 500;
+export declare const environmentIncompleteReason = "Environment incomplete: provider behavior is not implemented.";
+export declare function validateEnvironmentEvidence(evidence: EnvironmentEvidence): void;
+export declare function loadEnvironmentEvidence(client: EvaluationClient, executionId: string): Promise<EnvironmentEvidence>;

package/dist/evals/environment-evidence.js

@@ -0,0 +1,123 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { HueApiError } from "./client.js";
+import { json, uuid, valueBounds } from "./json.js";
+import { environmentJson, validateEvidenceArguments, validateEvidenceWorld, } from "./environment-json.js";
+const maxBytes = 8 * 1024 * 1024;
+const hexDigest = /^[a-f0-9]{64}$/;
+export const MAX_ENVIRONMENT_STEPS = 500;
+async function readEvidence(operation) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const retryable = error instanceof HueApiError &&
+                (error.status === undefined ||
+                    error.status === 408 ||
+                    error.status === 429 ||
+                    error.status >= 500);
+            if (!retryable || attempt >= 4)
+                throw error;
+            await wait(25 * 2 ** (attempt - 1));
+        }
+    }
+}
+export const environmentIncompleteReason = "Environment incomplete: provider behavior is not implemented.";
+function validateCoverage(evidence) {
+    const validity = evidence.validity === undefined ? "not_assessed" : evidence.validity;
+    const gap = evidence.coverageGap ?? null;
+    if (validity === "not_assessed" && gap === null)
+        return;
+    if (validity !== "environment_incomplete" || !gap || typeof gap !== "object")
+        throw new TypeError("Invalid environment coverage evidence");
+    const { args, ...metadata } = gap;
+    json(metadata);
+    json(args, { ...valueBounds, bytes: 16_000 });
+    if (!args ||
+        typeof args !== "object" ||
+        Array.isArray(args) ||
+        Object.keys(gap).sort().join(",") !==
+            "args,code,description,operation,provider,reportedAt,reportedBy" ||
+        [
+            [gap.provider, 128],
+            [gap.operation, 256],
+            [gap.code, 128],
+            [gap.description, 2000],
+        ].some(([value, maximum]) => typeof value !== "string" || !value.length || value.length > Number(maximum)) ||
+        typeof gap.reportedAt !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(gap.reportedAt) ||
+        !Number.isFinite(Date.parse(gap.reportedAt)) ||
+        !gap.reportedBy ||
+        !["project_key", "user"].includes(gap.reportedBy.kind) ||
+        Object.keys(gap.reportedBy).sort().join(",") !== "id,kind")
+        throw new TypeError("Invalid environment coverage gap");
+    uuid(gap.reportedBy.id);
+}
+export function validateEnvironmentEvidence(evidence) {
+    validateCoverage(evidence);
+    uuid(evidence.runId);
+    uuid(evidence.executionId);
+    uuid(evidence.environmentVersionId);
+    if (!hexDigest.test(evidence.definitionDigest) ||
+        !hexDigest.test(evidence.stateDigest) ||
+        !/^[a-f0-9]{32}$/.test(evidence.seed) ||
+        !["completed", "abandoned", "expired"].includes(evidence.status) ||
+        !Number.isInteger(evidence.stepCount) ||
+        evidence.stepCount < 0 ||
+        evidence.stepCount > MAX_ENVIRONMENT_STEPS ||
+        !Array.isArray(evidence.steps) ||
+        evidence.steps.length !== evidence.stepCount)
+        throw new TypeError("Invalid sealed environment evidence");
+    validateEvidenceWorld(evidence.initialState);
+    validateEvidenceWorld(evidence.finalState);
+    for (const [ordinal, step] of evidence.steps.entries()) {
+        const { args, observation, effects, ...header } = step;
+        json(header);
+        validateEvidenceArguments(args);
+        environmentJson(observation, 256 * 1024, 35, 256 * 1024);
+        environmentJson(effects, 256 * 1024, 35, 256 * 1024);
+        if (step.ordinal !== ordinal || !hexDigest.test(step.stateDigest))
+            throw new TypeError("Environment history is incomplete or unordered");
+    }
+    if (evidence.steps.length && evidence.steps.at(-1).stateDigest !== evidence.stateDigest)
+        throw new TypeError("Environment history does not end at the sealed state");
+    if (Buffer.byteLength(JSON.stringify(evidence)) > maxBytes)
+        throw new RangeError("Environment evidence exceeds 8 MiB; no history was truncated");
+}
+export async function loadEnvironmentEvidence(client, executionId) {
+    const snapshot = await readEvidence(() => client.getEnvironmentEvidence(executionId));
+    if (snapshot.executionId !== executionId)
+        throw new TypeError("Environment execution differs");
+    if (!Number.isInteger(snapshot.stepCount) ||
+        snapshot.stepCount < 0 ||
+        snapshot.stepCount > MAX_ENVIRONMENT_STEPS)
+        throw new TypeError("Invalid environment step count");
+    const evidence = {
+        validity: "not_assessed",
+        coverageGap: null,
+        ...snapshot,
+        steps: [],
+    };
+    let size = Buffer.byteLength(JSON.stringify(evidence));
+    let after;
+    for (;;) {
+        const page = await readEvidence(() => client.getEnvironmentSteps(executionId, { after, limit: 5 }));
+        if (!Array.isArray(page.items))
+            throw new TypeError("Invalid environment history page");
+        for (const step of page.items) {
+            if (step.ordinal !== evidence.steps.length || evidence.steps.length >= snapshot.stepCount)
+                throw new TypeError("Environment history is incomplete or unordered");
+            size += Buffer.byteLength(JSON.stringify(step));
+            if (size > maxBytes)
+                throw new RangeError("Environment evidence exceeds 8 MiB");
+            evidence.steps.push(step);
+        }
+        if (page.nextCursor === null)
+            break;
+        if (!page.items.length || page.nextCursor !== evidence.steps.length - 1)
+            throw new TypeError("Environment history repeated or skipped a cursor");
+        after = page.nextCursor;
+    }
+    validateEnvironmentEvidence(evidence);
+    return evidence;
+}

package/dist/evals/environment-json.d.ts

@@ -0,0 +1,3 @@
+export declare function environmentJson(value: unknown, maxBytes?: number, maxDepth?: number, maxNodes?: number): void;
+export declare function validateEvidenceWorld(value: unknown): void;
+export declare function validateEvidenceArguments(value: unknown): void;