engineering-behavior-observatory 0.2.1

package/dist/src/contracts.d.ts

@@ -0,0 +1,155 @@
+import type { TaskPacketFreezeRecord } from "./task-packets.js";
+export type Digest = {
+    algorithm: "sha256";
+    value: string;
+};
+export type ArtifactReference = {
+    locator: string;
+    digest: Digest;
+};
+export type AssessmentMode = "observational" | "verified";
+export type BundleRootHandle = {
+    path: string;
+    descriptor: number;
+};
+export type ArchiveEntry = {
+    path: string;
+    kind: string;
+};
+export type TaskArchiveEntry = ArchiveEntry & {
+    bytes: Buffer;
+    mode: number;
+};
+export type ArchiveLimits = {
+    maxCompressedBytes: number;
+    maxExpandedBytes: number;
+    maxMembers: number;
+};
+export type ArchiveMeasurements = {
+    compressedBytes: number;
+    expandedBytes: number;
+    memberCount: number;
+};
+export declare const MAX_CONFIGURATION_BYTES = 1048576;
+export type TaskCondition = {
+    packetRef: {
+        locator: string;
+        digest: Digest;
+    };
+};
+export type TaskConditionSet = Record<string, TaskCondition>;
+export type ControlledPerturbationDeclaration = {
+    status: "referenced";
+    digest: Digest;
+} | {
+    status: "not-applied" | "unsupported";
+};
+export type ReferenceSolutionDeclaration = {
+    status: "referenced";
+    digest: Digest;
+} | {
+    status: "not-provided" | "unsupported";
+};
+export type ResolvedTaskPacket = {
+    assessmentMode: AssessmentMode;
+    /** Packet identity retained by the admission resolver for freeze binding. */
+    packetId?: string;
+    /** Resolved task-packet component digests retained for freeze binding. */
+    promptDigest?: Digest;
+    fixtureDigest?: Digest | null;
+    digest: Digest;
+    preAdmissionDigest: Digest | null;
+    reviewRecordDigest: Digest | null;
+    resolvedReviewRecordDigest: Digest | null;
+    reviewRecordPreAdmissionDigest: Digest | null;
+    controlledPerturbation: {
+        declaration: ControlledPerturbationDeclaration;
+        resolvedDigest: Digest | null;
+    };
+    referenceSolution: {
+        declaration: ReferenceSolutionDeclaration;
+        resolvedDigest: Digest | null;
+    };
+    verifierDigest: Digest | null;
+    resolvedVerifierDigest: Digest | null;
+    admission: {
+        status: "proposed" | "admitted" | "rejected";
+        reviewedAt: string | null;
+    };
+    /** Complete freeze evidence admitted alongside this packet resolution. */
+    freezeRecord?: TaskPacketFreezeRecord;
+};
+export type DeclaredOrder = {
+    taskIds: string[];
+    modelIds: string[];
+    harnessIds: string[];
+};
+export type DeclaredMatrixCell = {
+    taskId: string;
+    modelId: string;
+    harnessId: string;
+    trialIndex: number;
+};
+export type ExperimentOrdering = {
+    seed: string;
+    strategy: "declared";
+    declaredOrder: DeclaredOrder;
+} | {
+    seed: string;
+    strategy: "sequential";
+    declaredOrder?: DeclaredOrder;
+} | {
+    seed: string;
+    strategy: "permuted" | "seeded-shuffle";
+    declaredOrder?: DeclaredOrder;
+    permutationAlgorithmRef?: ArtifactReference;
+} | {
+    seed: string;
+    strategy: "balanced" | "balanced-interleaved" | "interleaved";
+    declaredOrder?: DeclaredOrder;
+    balanceBy?: "task" | "model" | "harness";
+};
+export type ExperimentConfiguration = {
+    schemaVersion: "ebo.experiment/v1";
+    id: string;
+    taskSet: TaskConditionSet;
+    modelSet: Record<string, {
+        configurationRef: ArtifactReference;
+    }>;
+    harnessSet: Record<string, {
+        configurationRef: ArtifactReference;
+        nativeLimitsRef: ArtifactReference;
+        nativeToolPolicyRef: ArtifactReference;
+    }>;
+    trialCount: number;
+    coordinatorBudget: {
+        maxWallClockMs: number;
+    };
+    captureProfile: ArtifactReference;
+    ordering: ExperimentOrdering;
+};
+export declare function assertDeclaredOrder(conditionSets: {
+    taskSet: Record<string, unknown>;
+    modelSet: Record<string, unknown>;
+    harnessSet: Record<string, unknown>;
+}, declaredOrder: DeclaredOrder): void;
+export declare function declaredMatrixCells(declaredOrder: DeclaredOrder, trialCount: number): Generator<DeclaredMatrixCell>;
+export declare function assertNoSelectedSymlinks(entries: readonly ArchiveEntry[], includePaths: readonly string[], archiveEntries?: readonly ArchiveEntry[]): void;
+export declare function assertArchiveMeasurements(limits: ArchiveLimits, measurements: ArchiveMeasurements): void;
+export declare function validateTaskArchive(bytes: Uint8Array, limits: ArchiveLimits, includePaths: readonly string[]): void;
+export declare function readTaskArchive(bytes: Uint8Array, limits: ArchiveLimits, includePaths: readonly string[]): TaskArchiveEntry[];
+export declare function resolveBundleConfiguration(bundleRoot: string, reference: ArtifactReference, maxBytes?: number, rootHandle?: BundleRootHandle): Buffer;
+export declare function resolveTaskArchive(bundleRoot: string, source: ArtifactReference, maxCompressedBytes: number, rootHandle?: BundleRootHandle): Buffer;
+export declare function resolveBundleArtifact(bundleRoot: string, reference: ArtifactReference, maxBytes?: number, rootHandle?: BundleRootHandle): Buffer;
+export declare function resolveBundleArtifactDigest(bundleRoot: string, reference: ArtifactReference, rootHandle?: BundleRootHandle): Digest;
+export declare function openBundleRoot(bundleRoot: string): BundleRootHandle;
+export declare function closeBundleRoot(root: BundleRootHandle): void;
+export declare function openBundleRegularFile(bundleRoot: string, locator: string, label: string, root: BundleRootHandle): number;
+export declare function removeInterruptedPublicationLink(path: string, target: {
+    dev: number;
+    ino: number;
+}): void;
+export declare function assertControlledPerturbationDigest(reference: ArtifactReference, resolvedDigest: Digest): void;
+export declare function assertResolvedExperimentConfigurationDigests(experiment: ExperimentConfiguration, resolvedDigests: Record<string, Digest>): void;
+export declare function assertAdmittedTaskPackets(taskSet: TaskConditionSet, resolvedPackets: Record<string, ResolvedTaskPacket>): void;
+export declare function isSafeArtifactRelativePath(path: string): boolean;