@markstanden/opencode-test-container 0.0.0-stage → 0.1.0

package/dist/campaign/judge.d.ts

@@ -0,0 +1,209 @@
+import type { ToolIdentity } from "../contracts/version.ts";
+import type { Slot } from "../contracts/types.ts";
+import { type ContainerPlan } from "../adapters/podman/container.ts";
+import type { CommandResult } from "../adapters/process.ts";
+import { type RecoveryPolicy, type SelectionRecord } from "../evaluators/docs/analysis/recovery.ts";
+import { type DocState, type DocumentationOutcome, type JudgeFailureClass } from "../evaluators/docs/scoring.ts";
+import { type PreparedManifest } from "./prepare.ts";
+/** The terminal state of one judge attempt. */
+export type JudgeAttemptStatus = "judged" | "invalid-verdict" | "judge-error";
+/** A judge attempt's recorded state, including an unfinished dispatch. */
+export type JudgeMetaStatus = JudgeAttemptStatus | "started";
+/** One immutable judge attempt record. */
+export interface JudgeAttemptMeta {
+    /** The schema version value. */
+    schemaVersion: 1;
+    /** The campaign id value. */
+    campaignId: string;
+    /** The slot id value. */
+    slotId: string;
+    /** The case id value. */
+    caseId: string;
+    /** The arm id value. */
+    armId: string;
+    /** The attempt id value. */
+    attemptId: string;
+    /** The judge model route. */
+    judgeModel: string;
+    /** The packet sha256 value; every recovery attempt must match it. */
+    packetSha256: string;
+    /** The attempt status value. */
+    judgementStatus: JudgeMetaStatus;
+    /** The failure class, or null on a usable judgement. */
+    failureClass: JudgeFailureClass | null;
+    /** Whether the capture proves a complete final response. */
+    complete: boolean;
+    /** The started at value. */
+    startedAt: string;
+    /** The completed at value. */
+    completedAt: string;
+    /** The exit value. */
+    exit: number | null;
+    /** The timed out value. */
+    timedOut: boolean;
+    /** The capture problems value. */
+    captureProblems: string[];
+    /** The judgement sha256 value, or null. */
+    judgementSha256: string | null;
+}
+/** One stored judgement. */
+export interface StoredJudgement {
+    /** The schema version value. */
+    schemaVersion: 1;
+    /** The slot id value. */
+    slotId: string;
+    /** The attempt id value. */
+    attemptId: string;
+    /** The judged value, when usable. */
+    status: JudgeAttemptStatus;
+    /** The documentation outcome, when usable. */
+    documentationOutcome: DocumentationOutcome | null;
+    /** The utility score, when usable. */
+    utility: number | null;
+    /** The judgement payload. */
+    value: Record<string, unknown> | null;
+    /** The problems, empty on a usable judgement. */
+    problems: string[];
+}
+/** Everything one judge invocation did. */
+export interface JudgeSummary {
+    /** Whether every selected slot produced a usable judgement or was skipped. */
+    ok: boolean;
+    /** Slots with a usable judgement, including idempotent skips. */
+    judged: string[];
+    /** Slots skipped because a checked selection already existed. */
+    skipped: string[];
+    /** Slots that produced no usable judgement. */
+    refused: string[];
+    /** The problems value. */
+    problems: string[];
+}
+/** Dependencies the judge accepts, so ordinary tests need no Podman. */
+export interface JudgeDeps {
+    /** The run container value. */
+    runContainer?: (plan: ContainerPlan) => Promise<CommandResult>;
+    /** The now value. */
+    now?: () => string;
+    /** The executing tool identity, injected for drift tests. */
+    tool?: ToolIdentity;
+}
+/** The path of one slot's judgement evidence. */
+export declare function judgeDirectory(root: string, slotId: string): string;
+/** The one canonical claims location: the campaign evidence root. */
+export declare function claimsRoot(root: string): string;
+/** The path of one slot's checked selection. */
+export declare function selectionPath(root: string, slotId: string): string;
+/** The path of one slot's immutable packet. */
+export declare function packetPath(root: string, slotId: string): string;
+/** The registered recovery policy, or a parse refusal. */
+export declare function policyOf(manifest: PreparedManifest): {
+    ok: true;
+    policy: RecoveryPolicy | null;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** One checked per-slot selection and the evidence it names. */
+export interface CheckedSelection {
+    /** The checked selection record. */
+    selection: SelectionRecord;
+    /** The selected attempt's metadata. */
+    meta: JudgeAttemptMeta;
+    /** The selected attempt's stored judgement. */
+    judgement: StoredJudgement;
+}
+/**
+ * Re-derive the packet evidence for one slot: every recorded attempt's packet
+ * must hash to its registered identity, the slot and attempt copies must agree,
+ * and every copy must equal the packet reconstructed from current evidence.
+ * @param root The campaign root.
+ * @param manifest The prepared manifest.
+ * @param slot The scheduled slot.
+ * @returns Packet integrity problems; empty means the packet is bound.
+ */
+export declare function packetIntegrityProblems(root: string, manifest: PreparedManifest, slot: Slot): string[];
+/**
+ * Re-derive one slot's selection from evidence. A readable object is not a
+ * selection: attempt identity, packet identity, the selected judgement's hash,
+ * its outcome/utility and its agreement with the documented mutation state are
+ * all checked before status, closure, reporting or the judge trust it.
+ * @param options The campaign root, manifest, slot and registered policy.
+ * @returns The checked selection, or every inconsistency found.
+ * @param options.root The campaign root.
+ * @param options.manifest The prepared manifest.
+ * @param options.slot The scheduled slot.
+ * @param options.policy The parsed recovery policy, or null.
+ */
+export declare function checkedSelection(options: {
+    root: string;
+    manifest: PreparedManifest;
+    slot: Slot;
+    policy: RecoveryPolicy | null;
+}): {
+    ok: true;
+    value: CheckedSelection;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * Load the manifest and policy, then check one slot's selection.
+ * @param root The campaign root.
+ * @param slotId The scheduled slot.
+ * @returns The checked selection, or every inconsistency.
+ */
+export declare function checkedSelectionForSlot(root: string, slotId: string): {
+    ok: true;
+    value: CheckedSelection;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * Build the exact judge packet for one slot without dispatching.
+ * @param root The campaign root.
+ * @param slotId The scheduled slot.
+ * @returns The packet and mutation state, or the refusal.
+ */
+export declare function buildJudgePacketForSlot(root: string, slotId: string): {
+    ok: true;
+    packet: string;
+    state: DocState;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * Judge every selected slot from checked evidence. A usable selection is
+ * idempotent; a complete `json-syntax` failure is recovered once when a policy
+ * is registered, from the same packet bytes and against durable ceilings.
+ * @param root The frozen campaign root.
+ * @param options Slot selection and dry-run choice.
+ * @param options.slotIds The selected slots.
+ * @param options.dryRun Build and check the packet without dispatching.
+ * @param deps Injected process runner and clock.
+ * @returns What was judged, skipped or refused.
+ */
+export declare function judgeCampaign(root: string, options?: {
+    slotIds?: readonly string[];
+    dryRun?: boolean;
+}, deps?: JudgeDeps): Promise<JudgeSummary>;
+/** Read a slot's attempt metadata, sorted by attempt id. */
+export declare function readJudgeAttempts(root: string, slotId: string): JudgeAttemptMeta[];
+/** One selected judgement and the attempt that produced it. */
+export interface SelectedJudgement {
+    /** The checked selection record. */
+    selection: SelectionRecord;
+    /** The selected attempt's metadata. */
+    meta: JudgeAttemptMeta;
+    /** The stored judgement. */
+    judgement: StoredJudgement;
+}
+/**
+ * Read the selected judgement for one slot, or null when no usable selection
+ * exists. The selection is evidence, so callers validate it separately.
+ * @param root The campaign root.
+ * @param slotId The slot id.
+ * @returns The selected attempt's stored judgement, or null.
+ */
+export declare function readSelectedJudgement(root: string, slotId: string): SelectedJudgement | null;