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

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

@@ -0,0 +1,235 @@
+/**
+ * Stable reporting for the analysis framework.
+ *
+ * One structured result renders both the versioned machine-readable analysis
+ * and the Markdown report, so the numbers and the decision wording cannot
+ * drift apart. Rendering is deterministic for identical input; the render
+ * timestamp is injected and recorded separately from any execution time.
+ * Markdown cells are escaped so evidence text cannot corrupt a table.
+ */
+import type { SensitivityCell, UtilityWeights } from "../scoring.ts";
+import type { AccountingCounts } from "./accounting.ts";
+import type { MeasuresReport } from "./measures.ts";
+import type { Interval } from "./bounds.ts";
+import type { DecisionResult } from "./decision.ts";
+import type { GuardrailArmSummary } from "./guardrails.ts";
+import type { GuardrailSpec, SelectionSpec } from "./model.ts";
+import type { PairedComparison } from "./pairing.ts";
+import type { Finding } from "./screening/rules.ts";
+import type { ReconcileRow } from "./screening/reconcile.ts";
+/** The analyser implementation identity. */
+export declare const ANALYSER_VERSION = "analysis-framework/1";
+/** The report template this renderer follows. */
+export declare const REPORT_TEMPLATE_VERSION = "trial-feedback-report/2026-11-10";
+/** One arm's report block. */
+export interface AnalysisArmReport {
+    /** The arm's accounting counts. */
+    accounting: AccountingCounts;
+    /** The arm's full-population utility interval. */
+    interval: Interval;
+    /** The arm's guardrail summaries. */
+    guardrails: GuardrailArmSummary[];
+}
+/** The pairing summary included in the report. */
+export interface PairingSummary {
+    /** Declared pairs. */
+    pairs: number;
+    /** Pairs with every arm assessed. */
+    completePairs: number;
+    /** Assessed observations in incomplete pairs. */
+    unmatched: Array<{
+        stamp: string;
+        arm: string;
+        scenario: string;
+        score: number;
+    }>;
+    /** Observations outside any declared pair. */
+    unpaired: number;
+    /** Evidence problems found while pairing. */
+    problems: string[];
+}
+/** One token field's campaign subtotal and independent step coverage. */
+export interface TokenFieldCoverage {
+    /** Sum over reporting steps, or null when no step reported the field. */
+    total: number | null;
+    /** Observed steps reporting a numeric value, including explicit zero. */
+    measuredSteps: number;
+    /** Observed steps not reporting the field. */
+    unknownSteps: number;
+}
+/** Captured token usage, with coverage kept independently per field. */
+export interface UsageSummary {
+    /** Input-token subtotal and coverage. */
+    input: TokenFieldCoverage;
+    /** Output-token subtotal and coverage. */
+    output: TokenFieldCoverage;
+    /** Reasoning-token subtotal and coverage. */
+    reasoning: TokenFieldCoverage;
+    /** Cache-read-token subtotal and coverage. */
+    cacheRead: TokenFieldCoverage;
+    /** Observed step_finish events, or null when no trail was readable. */
+    steps: number | null;
+    /** Trials whose session trail was readable. */
+    measuredTrials: number;
+    /** Trials whose session trail was unreadable. */
+    unknownTrials: number;
+}
+/** Cost availability: token telemetry is not a monetary cost. */
+export interface CostSummary {
+    /** Whether a recorded cost exists; this analyser records none. */
+    available: false;
+    /** Why the cost is unavailable. */
+    note: string;
+}
+/** The reconciled attempt-ledger summary. */
+export interface LedgerSummary {
+    /** The ledger's stable root-relative reference. */
+    reference: string;
+    /** Whether the ledger was readable. */
+    state: "available" | "missing" | "malformed";
+    /** Event counts keyed by recorded event name. */
+    events: Record<string, number>;
+    /** Scheduled slots the campaign declared. */
+    scheduled: number;
+    /** Scheduled slots with a recorded launch. */
+    launched: number;
+    /** Scheduled slots with a recorded judge attempt. */
+    judged: number;
+    /** Scheduled slots with no recorded launch. */
+    missingLaunches: string[];
+    /** Scheduled slots with no recorded judge attempt. */
+    missingJudgeAttempts: string[];
+    /** Ledger stamps outside the declared schedule. */
+    unknownStamps: string[];
+    /** Stamps with more than one recorded launch. */
+    duplicateLaunches: string[];
+    /** Loading and reconciliation problems. */
+    problems: string[];
+}
+/** The structured analysis result: the single source for every rendering. */
+export interface AnalysisResult {
+    /** The analysis schema version. */
+    analysisVersion: string;
+    /** The campaign identity. */
+    campaign: {
+        id: string;
+        question: string | null;
+    };
+    /** SHA-256 of the manifest bytes. */
+    manifestSha256: string;
+    /** The evidence layout adapter. */
+    layout: string;
+    /** The recorded judgement-layer policy. */
+    selectionPolicy: string;
+    /** The frozen policy identity. */
+    policyId: string;
+    /** The frozen utility weights. */
+    weights: UtilityWeights;
+    /** The declared guardrails. */
+    guardrails: GuardrailSpec[];
+    /** The declared selection rule, when present. */
+    selection: SelectionSpec | null;
+    /** Per-arm reports. */
+    arms: Record<string, AnalysisArmReport>;
+    /** Per-arm, per-scenario accounting. */
+    scenarios: Record<string, Record<string, AccountingCounts>>;
+    /** The recording and retrieval opportunity measures, and the personal-trial screen. */
+    measures: MeasuresReport;
+    /** The whole measured population. */
+    totals: AccountingCounts;
+    /** The pairing summary. */
+    pairing: PairingSummary;
+    /** The candidate-minus-control comparison, when a rule is declared. */
+    paired: PairedComparison | null;
+    /** Full-population candidate-minus-control interval, when a rule is declared. */
+    bounds: {
+        delta: Interval | null;
+    };
+    /** The three-limb decision. */
+    decision: DecisionResult;
+    /** The sensitivity grid, when the campaign froze one. */
+    sensitivity: SensitivityCell[] | null;
+    /** Static-screen findings and their reconciliation, kept advisory. */
+    screening: {
+        rulesVersion: string;
+        findings: Finding[];
+        reconciliation: ReconcileRow[];
+        /** The one personal-trial decision, shared with the headline. */
+        personalTrial: MeasuresReport["personalTrial"];
+    };
+    /** Integrity identities. */
+    integrity: {
+        sources: Array<{
+            reference: string;
+            sha256: string;
+        }>;
+        judgedBy: string[];
+    };
+    /** Captured token usage; never an invented zero. */
+    usage: UsageSummary;
+    /** Monetary cost availability. */
+    cost: CostSummary;
+    /** The reconciled attempt ledger, when the campaign declared one. */
+    ledger: LedgerSummary | null;
+    /** Per-slot assessment selection, from checked selection records. */
+    assessmentSelection: {
+        /** Every scheduled slot's selected attempt, or null when unrecorded. */
+        slots: Array<{
+            stamp: string;
+            selectedAttemptId: string | null;
+            recovered: boolean;
+        }>;
+        /** Slots whose selection is the frozen first attempt. */
+        initial: number;
+        /** Slots whose selection is a recovery attempt. */
+        recovered: number;
+        /** Slots with no selection record (historical evidence). */
+        unrecorded: number;
+    };
+    /** Explicit limitations, rendered verbatim. */
+    limitations: string[];
+}
+/** The receipt written beside the analysis. */
+export interface AnalysisReceipt {
+    /** The analyser identity. */
+    analyserVersion: string;
+    /** The report template identity. */
+    templateVersion: string;
+    /** SHA-256 of the manifest bytes. */
+    manifestSha256: string;
+    /** The frozen policy identity. */
+    policyId: string;
+    /** The injected rendering timestamp. */
+    renderedAt: string;
+    /** Every consumed observation with its identity and explicit state, sorted. */
+    inputs: Array<{
+        reference: string;
+        kind: "file" | "directory";
+        sha256: string | null;
+        state: "available" | "missing" | "not-a-directory" | "malformed";
+    }>;
+}
+/**
+ * Escape one Markdown table cell.
+ * @param value The raw cell value.
+ * @returns The escaped, single-line value.
+ */
+export declare function escapeCell(value: unknown): string;
+/**
+ * Render the full analysis report.
+ * @param result The analysis result.
+ * @returns Markdown.
+ */
+export declare function renderReport(result: AnalysisResult): string;
+/**
+ * Render the versioned machine-readable analysis.
+ * @param result The analysis result.
+ * @returns The JSON document with a trailing newline.
+ */
+export declare function renderAnalysisJson(result: AnalysisResult): string;
+/**
+ * Render the analysis receipt.
+ * @param receipt The receipt fields, including the injected timestamp.
+ * @returns The JSON document with a trailing newline.
+ */
+export declare function renderReceipt(receipt: AnalysisReceipt): string;