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

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

@@ -0,0 +1,236 @@
+/**
+ * Versioned campaign manifest for the trial analysis framework.
+ *
+ * A manifest describes a campaign as data — identity, arms, scenarios, the
+ * frozen schedule with declared pair identities, the evidence layout, the
+ * recorded assessment-layer selection policy and the frozen measurement
+ * policy — so a future agent can run the standard analyser without writing
+ * another calculator. Validation is pure and total: it collects problems
+ * instead of throwing, so a CLI can report every defect in one pass.
+ *
+ * Manifests are portable: evidence locations are layout ids and paths relative
+ * to a runtime evidence root. Absolute paths and traversal segments are
+ * refused here, never resolved at parse time. Nothing in this module reads
+ * the filesystem or calls a model.
+ */
+import { type RecoveryPolicy } from "./recovery.ts";
+/** The only manifest schema version this framework parses. */
+export declare const MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * Evidence layout adapters the loader knows how to read. The ledger-shaped
+ * `rr-ledger-v1` layout is deliberately absent until an adapter exists: a
+ * manifest declaring an unreadable layout is refused, never accepted and
+ * silently read as ac-v1.
+ */
+export declare const EVIDENCE_LAYOUTS: readonly ["ac-v1"];
+/** A known evidence layout adapter id. */
+export type EvidenceLayout = (typeof EVIDENCE_LAYOUTS)[number];
+/** Recorded policies for choosing among multiple judgement layers. */
+export declare const SELECTION_POLICIES: readonly ["resolution-then-judgement", "judgement-only"];
+/** A known judgement-layer selection policy id. */
+export type SelectionPolicy = (typeof SELECTION_POLICIES)[number];
+/** Guardrail kinds the evaluator implements. */
+export declare const GUARDRAIL_KINDS: readonly ["mutation-policy", "destructive-loss"];
+/** A known guardrail kind. */
+export type GuardrailKind = (typeof GUARDRAIL_KINDS)[number];
+/** How a slot's observation relates to the frozen schedule. */
+export declare const DISPOSITIONS: readonly ["first-attempt", "replacement", "excluded"];
+/** A known observation disposition. */
+export type Disposition = (typeof DISPOSITIONS)[number];
+/** The campaign being analysed. */
+export interface CampaignIdentity {
+    /** Stable campaign id, e.g. `rc-20261110`. */
+    id: string;
+    /** The frozen question, quoted in reports. */
+    question?: string | undefined;
+}
+/** One arm's declared identity. */
+export interface ArmIdentity {
+    /** Stable arm id used by schedule slots and evidence roots. */
+    id: string;
+    /** Human-readable label, quoted in reports. */
+    label?: string | undefined;
+}
+/** One configured still-valid fact an inventory assesses for preservation. */
+export interface PreservationFactSpec {
+    /** Stable fact id, e.g. `poolSize`; never a hard-coded framework name. */
+    id: string;
+    /** Human-readable label, quoted in findings. */
+    label: string;
+    /** Focused regex sources recognising the fact and its supported equivalents. */
+    mentionPatterns?: string[] | undefined;
+    /** Regex sources asserting the fact's obsolete current form (obsolete-claim facts). */
+    obsoleteCurrentPatterns?: string[] | undefined;
+}
+/** One scenario's configured preservation inventory. */
+export interface PreservationInventorySpec {
+    /** The facts assessed for preservation. */
+    facts: PreservationFactSpec[];
+    /** Regex sources whose in-assertion match negates a fact mention. */
+    negationCues: string[];
+}
+/** A scenario's recorded mutation policy and its visible constraints. */
+export interface MutationPolicySpec {
+    /** Allowed mutation globs, relative to the trial workspace. */
+    allowed: string[];
+    /** Constraints the task prompt communicated, when recorded. */
+    visibleConstraints?: string[] | undefined;
+}
+/** One scenario's declared identity and optional measurement configuration. */
+export interface ScenarioIdentity {
+    /** Stable scenario id used by schedule slots and evidence. */
+    id: string;
+    /** Display-only measurement kind, e.g. `reuse-create`. */
+    kind?: string | undefined;
+    /** The scenario's configured preservation inventory, when it has one. */
+    preservationInventory?: PreservationInventorySpec | undefined;
+    /** The scenario's recorded mutation policy, when the campaign declares one. */
+    mutationPolicy?: MutationPolicySpec | undefined;
+}
+/** One scheduled trial slot: a declared identity, never an array position. */
+export interface SlotSpec {
+    /** One-based position in the frozen execution order. */
+    slot: number;
+    /** The trial's result stamp. */
+    stamp: string;
+    /** The scenario the slot runs. */
+    scenario: string;
+    /** The arm the slot runs. */
+    arm: string;
+    /** The repetition within scenario and arm. */
+    repetition: number;
+    /** The declared pair id; pairs hold exactly two distinct-arm slots. */
+    pairId?: string | undefined;
+    /** How the observation relates to the schedule; defaults to first-attempt. */
+    disposition?: Disposition | undefined;
+}
+/** The frozen schedule. */
+export interface ScheduleSpec {
+    /** Every scheduled slot; may be empty so zero denominators stay reportable. */
+    slots: SlotSpec[];
+}
+/** Evidence locations relative to the runtime evidence root. */
+export interface EvidenceSpec {
+    /** The layout adapter id the loader uses to read this campaign. */
+    layout: EvidenceLayout;
+    /** Per-arm result roots, relative to the evidence root. */
+    resultRoots: Record<string, string>;
+    /** Extra named inputs, relative to the evidence root (e.g. a ledger). */
+    inputs?: Record<string, string> | undefined;
+}
+/** The recorded policy for choosing among judgement layers. */
+export interface AssessmentSpec {
+    /** A known selection policy id; never implicitly "newest wins". */
+    selectionPolicy: SelectionPolicy;
+    /**
+     * The judge attempt directory to read, e.g. `attempt-002`. Absent means
+     * `attempt-001`; a preserved earlier attempt is never overwritten.
+     */
+    attemptId?: string;
+    /**
+     * The registered recovery policy. Absent means the historical behaviour:
+     * no recovery is authorised. Present, it is validated here and its per-slot
+     * selection record becomes the checked evidence for recovered slots.
+     */
+    recovery?: RecoveryPolicy;
+}
+/** One non-compensable guardrail. */
+export interface GuardrailSpec {
+    /** Stable guardrail id. */
+    id: string;
+    /** A known guardrail kind the evaluator implements. */
+    kind: GuardrailKind;
+    /** The requirement, quoted verbatim in reports. */
+    requirement: string;
+}
+/** The declared pairwise comparison rule; absent means "not defined". */
+export interface SelectionSpec {
+    /** The arm the candidate is compared against. */
+    controlArm: string;
+    /** The arm under evaluation. */
+    candidateArm: string;
+    /** The required utility lead of candidate over control. */
+    threshold: number;
+    /** Whether complete assessment coverage of planned slots is required. */
+    requireCompleteCoverage: boolean;
+}
+/** An optional sensitivity grid, frozen before scoring. */
+export interface SensitivitySpec {
+    /** Useful create/update rewards to explore. */
+    usefulWeights: number[];
+    /** Transient penalties (positive magnitudes) to explore. */
+    transientPenalties: number[];
+}
+/** Optional static-screening configuration. */
+export interface ScreeningSpec {
+    /** The screening rules version these settings belong to. */
+    rulesVersion: string;
+    /** Advisory regex sources for transient-state wording. */
+    transientWordingPatterns?: string[] | undefined;
+    /** Regex sources for durable-troubleshooting counterexample wording. */
+    durableCounterexamplePatterns?: string[] | undefined;
+}
+/** The frozen measurement policy. */
+export interface PolicySpec {
+    /** Identity of the frozen policy, quoted in reports. */
+    policyId: string;
+    /** Utility weights; complete, finite, frozen before scoring. */
+    weights: UtilityWeightsSpec;
+    /** The non-compensable guardrails this campaign declares. */
+    guardrails: GuardrailSpec[];
+    /** The declared comparison rule, when the campaign freezes one. */
+    selection?: SelectionSpec | undefined;
+    /** The declared sensitivity grid, when the campaign freezes one. */
+    sensitivity?: SensitivitySpec | undefined;
+    /** Static-screening configuration, when the campaign uses the scanner. */
+    screening?: ScreeningSpec | undefined;
+}
+/** The five utility weight keys, all required. */
+export interface UtilityWeightsSpec {
+    /** Reward for a useful create and a useful update. */
+    useful: number;
+    /** Penalty for a supported but valueless transient note. */
+    transient: number;
+    /** Penalty for a duplicate note. */
+    duplicate: number;
+    /** Penalty for misleading or unsupported documentation. */
+    misleading: number;
+    /** Penalty for a failed primary task. */
+    taskFailure: number;
+}
+/** A validated campaign manifest. */
+export interface CampaignManifest {
+    /** The manifest schema version; only 1 is accepted. */
+    schemaVersion: number;
+    /** The campaign identity. */
+    campaign: CampaignIdentity;
+    /** The declared arms. */
+    arms: ArmIdentity[];
+    /** The declared scenarios. */
+    scenarios: ScenarioIdentity[];
+    /** The frozen schedule. */
+    schedule: ScheduleSpec;
+    /** Evidence locations. */
+    evidence: EvidenceSpec;
+    /** The recorded judgement-layer policy. */
+    assessment: AssessmentSpec;
+    /** The frozen measurement policy. */
+    policy: PolicySpec;
+}
+/** The outcome of parsing one manifest. */
+export interface ManifestParseResult {
+    /** The validated manifest, present only when there are no problems. */
+    value?: CampaignManifest | undefined;
+    /** Every validation problem found, each naming the offending field. */
+    problems: string[];
+}
+/**
+ * Parse and validate one manifest value.
+ *
+ * The parse is total: junk input yields problems instead of an exception.
+ * The returned value is cast only after every field has been validated, so
+ * the cast carries the guarantee the validators establish.
+ * @param value The raw manifest value (as parsed from JSON).
+ * @returns The validated manifest, or every problem found.
+ */
+export declare function parseManifest(value: unknown): ManifestParseResult;