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

package/dist/evaluators/docs/analysis/recovery.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Opt-in judge recovery: the registered policy, the eligibility decision, the
+ * dual spend claim and the checked per-slot selection record.
+ *
+ * With no registered policy the campaign keeps its historical behaviour: the
+ * first unusable assessment stops it. A registered policy permits at most one
+ * fresh blind assessment of the same evidence, and only when a complete
+ * captured response failed with a JSON syntax error. Every other outcome —
+ * transport uncertainty, truncation, schema failure, semantic inconsistency,
+ * integrity or freeze problems, unresolved reservations — remains an explicit
+ * stop. Nothing here calls a model.
+ */
+import { type BudgetClaim } from "./budget.ts";
+/** The policy schema version this module understands. */
+export declare const RECOVERY_POLICY_VERSION = 1;
+/** The single failure class the initial policy may make eligible. */
+export declare const INITIAL_ELIGIBLE_CLASS = "json-syntax";
+/** The one failure class an attempt can be recovered from under this policy. */
+export type EligibleFailureClass = typeof INITIAL_ELIGIBLE_CLASS;
+/** A registered recovery policy, frozen with the campaign manifest. */
+export interface RecoveryPolicy {
+    /** The schema version; only 1 is accepted. */
+    version: number;
+    /** The failure classes eligible for recovery; `["json-syntax"]` only. */
+    eligibleFailureClasses: EligibleFailureClass[];
+    /** Completion evidence is mandatory; this policy cannot waive it. */
+    requiresCompletionEvidence: true;
+    /** Recoveries per failed slot; exactly one under this policy. */
+    maxRecoveriesPerSlot: number;
+    /** Campaign-wide recovery attempts. */
+    recoveryCeiling: number;
+    /** Total judge attempts, initial assessments plus recoveries. */
+    totalJudgeAttempts: number;
+    /** Requests per attempt the adapter exposes, or null when unavailable. */
+    providerRequestLimit: number | null;
+}
+/** The outcome of reading one registered policy. */
+export type PolicyParse = {
+    ok: true;
+    policy: RecoveryPolicy;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * Read and validate one registered recovery policy.
+ *
+ * The initial policy is deliberately narrow: completion evidence is mandatory,
+ * at most one recovery per slot is permitted, and the only eligible failure
+ * class is a JSON syntax failure. A declaration that widens any of those is
+ * refused rather than silently honoured, so a registration cannot become a
+ * general retry authorisation.
+ * @param value The manifest's `assessment.recovery` declaration.
+ * @returns The normalised policy, or every problem found.
+ */
+export declare function parseRecoveryPolicy(value: unknown): PolicyParse;
+/**
+ * The canonical hash of a registered policy.
+ * @param policy The normalised policy.
+ * @returns The SHA-256 of its canonical JSON.
+ */
+export declare function recoveryPolicySha256(policy: RecoveryPolicy): string;
+/** The facts an eligibility decision is made from. */
+export interface RecoveryFacts {
+    /** The recorded judgement status of the manifest-selected attempt. */
+    attemptStatus: string;
+    /** That attempt's machine-readable failure class, when recorded. */
+    failureClass: string | null;
+    /** Whether that attempt's capture proves a complete final response. */
+    completionComplete: boolean | null;
+    /** Attempt ids recorded for the slot. */
+    attemptIds: readonly string[];
+    /** Attempt ids whose judgement status is usable. */
+    judgedAttemptIds: readonly string[];
+    /** Recovery claims already made campaign-wide. */
+    recoveryClaimsUsed: number;
+    /** Judge claims already made campaign-wide, initial and recovery. */
+    judgeClaimsUsed: number;
+    /** The parsed ledger state. */
+    ledgerState: "missing" | "malformed" | "open" | "closed";
+    /** Freeze-verification problems, empty when the premise is intact. */
+    freezeProblems: readonly string[];
+    /** Unsettled reservations that forbid a repeat dispatch. */
+    unresolvedReservations: readonly string[];
+}
+/** The eligibility decision for one failed slot. */
+export type RecoveryDecision = {
+    eligible: true;
+    attemptId: string;
+} | {
+    eligible: false;
+    reason: string;
+};
+/**
+ * Decide whether one failed slot may receive its single recovery attempt.
+ *
+ * Every refusal names the specific fact that stopped it, so a status report can
+ * distinguish an ineligible failure from an exhausted budget or a broken
+ * premise. A usable first assessment is never replaced.
+ * @param policy The registered policy.
+ * @param facts The recorded facts for the slot and the campaign.
+ * @returns The decision.
+ */
+export declare function recoveryDecision(policy: RecoveryPolicy, facts: RecoveryFacts): RecoveryDecision;
+/** One attempt's recorded facts, as carried by the selection record. */
+export interface SelectionAttempt {
+    /** The attempt directory name. */
+    attemptId: string;
+    /** Its recorded judgement status. */
+    judgementStatus: string;
+    /** The packet identity it was judged from, or null when unrecorded. */
+    packetSha256: string | null;
+    /** Its failure class, when it has no usable verdict. */
+    failureClass: string | null;
+    /** Whether its capture proves a complete final response. */
+    complete: boolean | null;
+}
+/** The per-slot assessment selection, written after a usable judgement lands. */
+export interface SelectionRecord {
+    /** The record schema version. */
+    schemeVersion: number;
+    /** The scheduled slot the record belongs to. */
+    slot: number;
+    /** The scheduled pair id. */
+    pairId: string;
+    /** The trial stamp. */
+    stamp: string;
+    /** The arm letter. */
+    arm: string;
+    /** The scenario id. */
+    scenario: string;
+    /** The attempt whose judgement the analyser must read. */
+    selectedAttemptId: string;
+    /** The registered policy hash, or null when none applied. */
+    policySha256: string | null;
+    /** Every attempt recorded for the slot, in order. */
+    attempts: SelectionAttempt[];
+}
+/** The inputs a selection record is built from. */
+export interface SelectionInput {
+    /** The scheduled slot. */
+    slot: number;
+    /** The scheduled pair id. */
+    pairId: string;
+    /** The trial stamp. */
+    stamp: string;
+    /** The arm letter. */
+    arm: string;
+    /** The scenario id. */
+    scenario: string;
+    /** The attempt whose judgement is authoritative. */
+    selectedAttemptId: string;
+    /** The registered policy hash, or null when none applied. */
+    policySha256: string | null;
+    /** Every attempt recorded for the slot. */
+    attempts: SelectionAttempt[];
+}
+/**
+ * Build one selection record.
+ * @param input The slot identity, the selected attempt and every attempt fact.
+ * @returns The record.
+ */
+export declare function selectionRecordOf(input: SelectionInput): SelectionRecord;
+/** The facts a recorded selection is checked against. */
+export interface SelectionFacts {
+    /** The scheduled slot, when the caller knows it. */
+    slot?: number;
+    /** The pair id, when the caller knows it. */
+    pairId?: string;
+    /** The trial stamp. */
+    stamp?: string;
+    /** The arm letter, when the caller knows it. */
+    arm?: string;
+    /** The scenario id. */
+    scenario?: string;
+    /** Attempt directories actually present for the slot. */
+    attemptIds: readonly string[];
+    /** The frozen manifest selector. */
+    manifestAttemptId: string | null;
+    /** The registered policy, or null. */
+    policy: RecoveryPolicy | null;
+    /** The actual attempt facts, when the caller can re-derive them. */
+    attemptFacts?: Record<string, SelectionAttempt>;
+}
+/**
+ * Check one recorded selection against the evidence it claims to describe.
+ *
+ * The record is evidence, not a trusted pointer: its identity, attempt set,
+ * ordering, policy eligibility, packet identity and usable judgement status are
+ * all re-derived. A tampered record, an ineligible selection, or a replacement
+ * of an already-valid first assessment is refused.
+ * @param value The recorded selection, as read from disk.
+ * @param facts The actual slot and evidence facts.
+ * @returns Every problem; empty means the selection is trustworthy.
+ */
+export declare function selectionProblems(value: unknown, facts: SelectionFacts): string[];
+/**
+ * Claim the recovery and judge budgets atomically.
+ *
+ * The recovery claim is taken first, then the judge claim, each with the
+ * filesystem deciding the winner. If the judge claim refuses, the recovery
+ * reservation is released only because it provably dispatched nothing; a
+ * spawned call keeps consuming both ceilings.
+ * @param root The campaign evidence root.
+ * @param policy The registered policy.
+ * @param identity The slot identity and the logical attempt key.
+ * @param identity.stamp The trial stamp the claim names.
+ * @param identity.attemptId The recovery attempt id.
+ * @param identity.key The logical attempt key; a repeat is refused.
+ * @param identity.at An injected claim timestamp, for determinism.
+ * @returns Both claims, or the refusal.
+ */
+export declare function claimRecoveryBudget(root: string, policy: RecoveryPolicy, identity: {
+    stamp: string;
+    attemptId: string;
+    key: string;
+    at?: string;
+}): {
+    ok: true;
+    recovery: BudgetClaim;
+    judge: BudgetClaim;
+} | {
+    ok: false;
+    reason: string;
+};