engineering-behavior-observatory 0.2.1

package/dist/src/scheduler.d.ts

@@ -0,0 +1,109 @@
+import { type ArtifactValidationError } from "./artifacts.js";
+import { type ArtifactReference, type DeclaredOrder, type DeclaredMatrixCell, type Digest, type ExperimentConfiguration, type ResolvedTaskPacket } from "./contracts.js";
+import { type TaskPacketFreezeRecord } from "./task-packets.js";
+export type QueueOrderingStrategy = "sequential" | "seeded-shuffle" | "balanced";
+export type PermutationAlgorithm = "fisher-yates-v1";
+export declare const MAX_RUN_QUEUE_ENTRIES = 100000;
+export declare const MAX_RUN_QUEUE_BYTES: number;
+export type FrozenTaskIdentity = {
+    id: string;
+    packetId: string;
+    packetRef: ArtifactReference;
+    freezeLocator: string;
+    aggregateDigest: Digest;
+};
+export type FrozenTaskInput = TaskPacketFreezeRecord | {
+    status?: "frozen";
+    packetId: string;
+    packetLocator?: string;
+    packetDigest: Digest;
+    freezeLocator: string;
+    aggregateDigest: Digest;
+} | {
+    status?: "frozen";
+    packetId: string;
+    packetRef: ArtifactReference;
+    freezeLocator: string;
+    aggregateDigest: Digest;
+};
+export type RunQueueEntry = DeclaredMatrixCell & {
+    runId: string;
+    task: FrozenTaskIdentity;
+    model: {
+        id: string;
+        configurationRef: ArtifactReference;
+    };
+    harness: {
+        id: string;
+        configurationRef: ArtifactReference;
+        nativeLimitsRef: ArtifactReference;
+        nativeToolPolicyRef: ArtifactReference;
+    };
+    configuration: {
+        model: ArtifactReference;
+        harness: ArtifactReference;
+        nativeLimits: ArtifactReference;
+        nativeToolPolicy: ArtifactReference;
+    };
+    trial: {
+        index: number;
+    };
+};
+export type RunQueueMatrix = DeclaredOrder & {
+    trialCount: number;
+};
+export type RunQueue = {
+    schemaVersion: "ebo.run-queue/v1";
+    experimentId: string;
+    experimentDigest: Digest;
+    schedulingDigest: Digest;
+    captureProfile: ArtifactReference;
+    coordinatorBudget: {
+        maxWallClockMs: number;
+    };
+    matrix: RunQueueMatrix;
+    seed: string;
+    ordering: {
+        strategy: QueueOrderingStrategy;
+        balanceBy?: "task" | "model" | "harness";
+        permutationAlgorithm?: PermutationAlgorithm;
+        permutationAlgorithmRef?: ArtifactReference;
+    };
+    entries: RunQueueEntry[];
+};
+export type CompileRunQueueOptions = {
+    bundleRoot?: string;
+    resolvedDigests?: Record<string, Digest>;
+    permutationAlgorithm?: unknown;
+    permutationAlgorithms?: Record<string, unknown>;
+    freezeLocators?: Record<string, string>;
+    frozenTasks?: Record<string, FrozenTaskInput>;
+    taskFreezeRecords?: Record<string, FrozenTaskInput>;
+    taskPackets?: Record<string, FrozenTaskInput>;
+    resolvedPackets?: Record<string, ResolvedTaskPacket>;
+};
+export type ValidateRunQueueOptions = Pick<CompileRunQueueOptions, "bundleRoot" | "resolvedDigests" | "frozenTasks" | "taskFreezeRecords" | "taskPackets" | "permutationAlgorithm" | "permutationAlgorithms" | "freezeLocators" | "resolvedPackets">;
+export type RunQueueInspection = {
+    experimentId: string;
+    seed: string;
+    strategy: QueueOrderingStrategy;
+    entryCount: number;
+    firstRunId: string | null;
+    lastRunId: string | null;
+};
+export declare function expandMatrixCells(experiment: ExperimentConfiguration): DeclaredMatrixCell[];
+export declare function compileRunQueue(experiment: ExperimentConfiguration, options?: CompileRunQueueOptions): RunQueue;
+export declare function writeRunQueue(path: string, queue: RunQueue): Digest;
+export declare function readRunQueue(path: string, experiment?: ExperimentConfiguration, options?: ValidateRunQueueOptions): RunQueue;
+export declare function readBoundedFile(path: string, label?: string, afterOpen?: () => void, maxBytes?: number): Buffer;
+export declare function validateRunQueue(queue: unknown, experiment?: ExperimentConfiguration, artifact?: string, options?: ValidateRunQueueOptions): ArtifactValidationError[];
+export declare function assertValidRunQueue(queue: unknown, experiment?: ExperimentConfiguration, artifact?: string, options?: ValidateRunQueueOptions): asserts queue is RunQueue;
+export declare function inspectRunQueue(queue: RunQueue): RunQueueInspection;
+export declare class LocalRunQueue {
+    private position;
+    private readonly snapshot;
+    constructor(queue: RunQueue);
+    get queue(): RunQueue;
+    get remaining(): number;
+    next(): RunQueueEntry | undefined;
+}