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

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

@@ -0,0 +1,78 @@
+/**
+ * Structural parsing of the campaign attempt ledger.
+ *
+ * The ledger is the durable record of what a campaign authorised and launched.
+ * It is read as data at a trust boundary: one JSON object per line, with the
+ * fields the runner writes. A malformed, truncated or ambiguous ledger never
+ * authorises spend — a caller must treat anything but `open`/`closed` with a
+ * clean event list as a refusal, not as an empty ledger.
+ */
+/** One structurally valid ledger event. */
+export interface LedgerEvent {
+    /** Event timestamp, or null when the line carried none. */
+    at: string | null;
+    /** The recorded event name. */
+    event: string;
+    /** The trial stamp, when the event names one. */
+    stamp: string | null;
+    /** The scheduled slot number, when the event names one. */
+    slot: number | null;
+    /** The attempt id, when the event names one. */
+    attemptId: string | null;
+    /** The pair id, when the event names one. */
+    pairId: string | null;
+    /** The arm id, when the event names one. */
+    arm: string | null;
+    /** The campaign id, when the event names one. */
+    campaign: string | null;
+}
+/** The explicit state of one ledger read. */
+export type LedgerState = "missing" | "malformed" | "open" | "closed";
+/** The result of reading a ledger. */
+export interface LedgerParse {
+    /** The explicit state; only `open` and `closed` are trustworthy. */
+    state: LedgerState;
+    /** Every structurally valid event, in file order. */
+    events: LedgerEvent[];
+    /** Every reason the ledger cannot be trusted, never silently dropped. */
+    problems: string[];
+    /** The close timestamp, when the ledger records a valid close. */
+    closedAt: string | null;
+}
+/**
+ * Parse a whole ledger.
+ *
+ * A blank line is ignored; any other unreadable line makes the ledger
+ * `malformed`, because a partial read cannot prove what spend was authorised.
+ * A `campaign-closed` event closes the ledger only when every line parsed.
+ * @param text The ledger bytes, or undefined when the file is absent.
+ * @returns The state, the valid events and every problem.
+ */
+export declare function parseCampaignLedger(text: string | undefined): LedgerParse;
+/**
+ * Whether a parsed ledger permits a new launch or judge call. Only a clean
+ * `open` ledger does; `missing` is refused by campaign policy, not by this
+ * predicate, so the caller can distinguish "no campaign yet" from "closed".
+ * @param ledger The parse result.
+ * @returns True only for a clean open ledger.
+ */
+export declare function isOpenLedger(ledger: LedgerParse): boolean;
+/** One scheduled stamp's observed events. */
+export interface StampEvents {
+    /** Events naming this stamp, in file order. */
+    events: LedgerEvent[];
+    /** Trial launch events. */
+    launches: number;
+    /** Judge launch events. */
+    judgeLaunches: number;
+    /** Whether a slot-blocked event exists. */
+    blocked: boolean;
+    /** Whether a slot-complete event exists. */
+    complete: boolean;
+}
+/**
+ * Group ledger events by stamp, keeping unknown stamps visible.
+ * @param events The parsed events.
+ * @returns Per-stamp events and the stamps the ledger mentions.
+ */
+export declare function eventsByStamp(events: readonly LedgerEvent[]): Map<string, StampEvents>;

package/dist/evaluators/docs/analysis/ledger.js

@@ -0,0 +1,145 @@
+/**
+ * Structural parsing of the campaign attempt ledger.
+ *
+ * The ledger is the durable record of what a campaign authorised and launched.
+ * It is read as data at a trust boundary: one JSON object per line, with the
+ * fields the runner writes. A malformed, truncated or ambiguous ledger never
+ * authorises spend — a caller must treat anything but `open`/`closed` with a
+ * clean event list as a refusal, not as an empty ledger.
+ */
+/** Whether a value is a plain JSON object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A nonblank string, or null. */
+function stringOrNull(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/** A positive integer, or null. */
+function slotOrNull(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1
+        ? value
+        : null;
+}
+/**
+ * Parse one ledger line.
+ * @param line The raw line, without its newline.
+ * @param index The zero-based line index, for problem messages.
+ * @returns The event, or a problem.
+ */
+function eventOf(line, index) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return { problem: `ledger line ${String(index + 1)} is not JSON` };
+    }
+    if (!isRecord(value)) {
+        return {
+            problem: `ledger line ${String(index + 1)} is not a JSON object`,
+        };
+    }
+    const event = stringOrNull(value.event);
+    if (event === null) {
+        return {
+            problem: `ledger line ${String(index + 1)} has no event name`,
+        };
+    }
+    return {
+        event: {
+            at: stringOrNull(value.at),
+            event,
+            stamp: stringOrNull(value.stamp),
+            slot: slotOrNull(value.slot),
+            attemptId: stringOrNull(value.attemptId),
+            pairId: stringOrNull(value.pairId),
+            arm: stringOrNull(value.arm),
+            campaign: stringOrNull(value.campaign),
+        },
+    };
+}
+/**
+ * Parse a whole ledger.
+ *
+ * A blank line is ignored; any other unreadable line makes the ledger
+ * `malformed`, because a partial read cannot prove what spend was authorised.
+ * A `campaign-closed` event closes the ledger only when every line parsed.
+ * @param text The ledger bytes, or undefined when the file is absent.
+ * @returns The state, the valid events and every problem.
+ */
+export function parseCampaignLedger(text) {
+    if (text === undefined) {
+        return {
+            state: "missing",
+            events: [],
+            problems: ["attempt ledger is missing"],
+            closedAt: null,
+        };
+    }
+    const events = [];
+    const problems = [];
+    for (const [index, raw] of text.split("\n").entries()) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        const parsed = eventOf(line, index);
+        if (parsed.event !== undefined)
+            events.push(parsed.event);
+        if (parsed.problem !== undefined)
+            problems.push(parsed.problem);
+    }
+    if (problems.length > 0) {
+        return { state: "malformed", events, problems, closedAt: null };
+    }
+    const close = events.find((event) => event.event === "campaign-closed");
+    if (close !== undefined) {
+        return {
+            state: "closed",
+            events,
+            problems: [],
+            closedAt: close.at,
+        };
+    }
+    return { state: "open", events, problems: [], closedAt: null };
+}
+/**
+ * Whether a parsed ledger permits a new launch or judge call. Only a clean
+ * `open` ledger does; `missing` is refused by campaign policy, not by this
+ * predicate, so the caller can distinguish "no campaign yet" from "closed".
+ * @param ledger The parse result.
+ * @returns True only for a clean open ledger.
+ */
+export function isOpenLedger(ledger) {
+    return ledger.state === "open";
+}
+/**
+ * Group ledger events by stamp, keeping unknown stamps visible.
+ * @param events The parsed events.
+ * @returns Per-stamp events and the stamps the ledger mentions.
+ */
+export function eventsByStamp(events) {
+    const grouped = new Map();
+    for (const event of events) {
+        if (event.stamp === null)
+            continue;
+        const entry = grouped.get(event.stamp) ?? {
+            events: [],
+            launches: 0,
+            judgeLaunches: 0,
+            blocked: false,
+            complete: false,
+        };
+        entry.events.push(event);
+        if (event.event === "launch")
+            entry.launches += 1;
+        if (event.event === "judge-launch")
+            entry.judgeLaunches += 1;
+        if (event.event === "slot-blocked")
+            entry.blocked = true;
+        if (event.event === "slot-complete")
+            entry.complete = true;
+        grouped.set(event.stamp, entry);
+    }
+    return grouped;
+}

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

@@ -0,0 +1,302 @@
+/**
+ * Recording and retrieval opportunity measures for a productivity screen.
+ *
+ * The frozen utility answers "what did the trial document". These measures
+ * answer two different questions that utility does not: was a durable finding
+ * recorded through the plugin into the appropriate lake, and was an existing
+ * note retrieved and actually applied to the work. They are pure functions
+ * over loaded evidence: a missing journal, a missing judgement and an
+ * unattributable read each stay explicit and never become a zero or a pass.
+ */
+import type { DocumentationOutcome } from "../scoring.ts";
+import type { AccountingCounts } from "./accounting.ts";
+import type { SlotSpec } from "./model.ts";
+import type { TrialRecord } from "./records.ts";
+/** The measurement declaration schema version this module parses. */
+export declare const MEASURES_SCHEMA_VERSION = 1;
+/** One retrieval opportunity's declared note and assessed facts. */
+export interface RetrievalDeclaration {
+    /** The lake-relative path of the seeded note. */
+    note: string;
+    /** The lake the note belongs to; identity is not optional for credit. */
+    lake: string;
+    /** The preservation facts the note's correction must keep, when any. */
+    facts: string[];
+}
+/** The declared eligible scenarios for each opportunity measure. */
+export interface MeasureDeclarations {
+    /** Scenarios counted in the unprompted-recording denominator. */
+    recording: string[];
+    /** Scenarios counted in the unprompted-retrieval denominator. */
+    retrieval: Record<string, RetrievalDeclaration>;
+}
+/** The outcome of parsing a measurement declaration. */
+export interface MeasureDeclarationParse {
+    /** The validated declarations, when the input is usable. */
+    declarations?: MeasureDeclarations;
+    /** Every shape problem, so a malformed declaration is visible. */
+    problems: string[];
+}
+/** One journal operation, from the plugin's own operation journal. */
+export interface DocsOperation {
+    /** The recorded completion status. */
+    status: string;
+    /** Whether the served result says the operation succeeded. */
+    success: boolean | null;
+    /** The delivery surface (native, twin, or Code Mode twin). */
+    surface: string;
+    /** The operation's verb. */
+    verb: "add" | "read" | "search" | "check" | "help" | "unknown";
+    /** The typed target of a read or add, when present. */
+    target: string | null;
+    /** The lake the completed operation reports, when present. */
+    lake: string | null;
+    /** The lake-relative path the completed operation reports, when present. */
+    path: string | null;
+    /** The raw journal line, for the receipt/evidence trail. */
+    line: string;
+}
+/** The recording measure for one trial. */
+export interface RecordingMeasure {
+    /** Whether the scenario is in the recording denominator. */
+    eligible: boolean;
+    /** The deterministic disposition of any write. */
+    disposition: "verified-write" | "gate-blocked" | "filesystem-only" | "tool-error" | "no-write" | "unknown" | "not-run" | "not-eligible";
+    /** Whether a verified useful plugin-mediated write landed. */
+    success: boolean;
+    /** The semantic outcome, when the judge recorded one. */
+    outcome: DocumentationOutcome | null;
+    /** The recorded gate status, when readable. */
+    gate: string | null;
+    /** Completed add operations, rendered for evidence. */
+    writes: string[];
+    /** Supporting evidence lines. */
+    evidence: string[];
+}
+/** The retrieval measure for one trial. */
+export interface RetrievalMeasure {
+    /** Whether the scenario is in the retrieval denominator. */
+    eligible: boolean;
+    /** The resolved state: applied, miss, unknown, not run or not eligible. */
+    state: "applied" | "miss" | "unknown" | "not-run" | "not-eligible";
+    /** Whether an attributable completed read of the declared note exists. */
+    read: boolean;
+    /** The judge's recorded retrieval state, when present. */
+    judgeState: string | null;
+    /** The declared target note. */
+    note: string | null;
+    /** The attributable read operation lines. */
+    trace: string[];
+    /** Supporting evidence lines. */
+    evidence: string[];
+}
+/** One trial's measures. */
+export interface TrialMeasures {
+    /** The trial stamp. */
+    stamp: string;
+    /** The scenario. */
+    scenario: string;
+    /** The arm. */
+    arm: string;
+    /** The recording measure. */
+    recording: RecordingMeasure;
+    /** The retrieval measure. */
+    retrieval: RetrievalMeasure;
+}
+/** One arm's opportunity counts. */
+export interface ArmMeasureSummary {
+    /** Recording out of the planned four. */
+    recording: {
+        planned: number;
+        success: number;
+        miss: number;
+        unknown: number;
+        notRun: number;
+        dispositions: Record<string, number>;
+    };
+    /** Retrieval out of the planned five. */
+    retrieval: {
+        planned: number;
+        applied: number;
+        miss: number;
+        unknown: number;
+        notRun: number;
+        states: Record<string, number>;
+    };
+}
+/** The campaign measures block published in analysis.json. */
+export interface MeasuresReport {
+    /** Whether the declaration was loaded and usable. */
+    status: "available" | "missing" | "malformed";
+    /** SHA-256 of the declaration bytes, when available. */
+    declarationSha256: string | null;
+    /** Per-arm opportunity counts. */
+    arms: Record<string, ArmMeasureSummary>;
+    /** Every trial's measure, eligible or not. */
+    trials: TrialMeasures[];
+    /** The personal-trial screen, kept separate from the utility threshold. */
+    personalTrial: PersonalTrialDecision;
+}
+/** The personal-trial screen's decision. */
+export interface PersonalTrialDecision {
+    /** The screen's recommendation. */
+    recommendation: "personal-trial" | "no-promotion" | "inconclusive";
+    /** Every criterion and how it was decided. */
+    reasons: string[];
+    /** The analyser's utility-threshold limb, labelled as one component. */
+    utilityThreshold: {
+        component: "utility-threshold";
+        status: string;
+        lead: number | null;
+        interval: {
+            low: number;
+            high: number;
+        } | null;
+        note: string;
+    };
+}
+/** One paired scenario's control and candidate documented outcomes. */
+export interface PairedOutcome {
+    /** The declared pair id. */
+    pairId: string;
+    /** The control arm's outcomes in this pair. */
+    control: DocumentationOutcome[];
+    /** The candidate arm's outcomes in this pair. */
+    candidate: DocumentationOutcome[];
+}
+/** A criterion's decision. */
+interface Criterion {
+    /** The criterion outcome. */
+    status: "pass" | "fail" | "inconclusive";
+    /** Supporting reasons. */
+    reasons: string[];
+}
+/**
+ * Parse and validate the measurement declaration. The declaration is data:
+ * every problem is collected instead of throwing.
+ * @param value The parsed `measurement.json` value.
+ * @returns The declarations or the collected problems.
+ */
+export declare function parseMeasureDeclarations(value: unknown): MeasureDeclarationParse;
+/**
+ * Parse the plugin journal lines into operations, keeping unreadable lines
+ * explicit.
+ * @param lines The raw journal lines.
+ * @returns The operations and any parse problems.
+ */
+export declare function parseOperations(lines: readonly string[]): {
+    operations: DocsOperation[];
+    problems: string[];
+};
+/**
+ * Whether an operation names the declared note path exactly. A suffix match is
+ * deliberately not accepted: `shared/db/pool.md` is a different file from
+ * `db/pool.md`.
+ * @param operation The journal operation.
+ * @param declaration The declared note.
+ * @returns True when the operation's reported path or target is the note.
+ */
+export declare function operationMatchesNotePath(operation: DocsOperation, declaration: RetrievalDeclaration): boolean;
+/**
+ * Whether an operation's reported lake matches the declaration. A declaration
+ * without a lake accepts only an exact path; a declared lake must match.
+ * @param operation The journal operation.
+ * @param declaration The declared note.
+ * @returns True when the lake identity is satisfied.
+ */
+export declare function operationMatchesNoteLake(operation: DocsOperation, declaration: RetrievalDeclaration): boolean;
+/** One lake document the trial's writes report names. */
+export interface ChangedLakeDocument {
+    /** The lake the change landed in. */
+    lake: string;
+    /** The lake-relative path. */
+    path: string;
+    /** The change kind, when the report names one. */
+    kind: "added" | "modified" | "removed" | "unknown";
+}
+/**
+ * Read the changed lake documents from a trial's writes report.
+ *
+ * Only `lakes/<lake>/<path>` entries are documents; a work-file change never
+ * makes a documentation write verified. An unreadable report is a problem, not
+ * an empty change set.
+ * @param writes The recorded writes report.
+ * @param writes.state The report's explicit load state.
+ * @param writes.text The report's text.
+ * @returns The changed documents and any parse problem.
+ */
+export declare function changedLakeDocuments(writes: {
+    state: string;
+    text: string;
+}): {
+    documents: ChangedLakeDocument[];
+    problem: string | null;
+};
+/**
+ * Whether a completed plugin write targets exactly one changed document.
+ * @param operation The completed add operation.
+ * @param document The evidenced changed document.
+ * @returns True when lake and relative path agree.
+ */
+export declare function operationMatchesChangedDocument(operation: DocsOperation, document: ChangedLakeDocument): boolean;
+/**
+ * Measure one trial against the declared opportunities.
+ * @param record The loaded trial record.
+ * @param declarations The validated declarations.
+ * @param arm The declared arm id.
+ * @returns The trial measures.
+ */
+export declare function measureTrial(record: TrialRecord, declarations: MeasureDeclarations, arm: string): TrialMeasures;
+/**
+ * Summarise the measures per arm.
+ * @param trials The trial measures.
+ * @param planned The frozen slots.
+ * @param declarations The validated declarations.
+ * @returns The per-arm counts.
+ */
+export declare function summariseMeasures(trials: readonly TrialMeasures[], planned: readonly SlotSpec[], declarations: MeasureDeclarations): Record<string, ArmMeasureSummary>;
+/**
+ * The paired scenario criterion: a misleading outcome that appears only on the
+ * candidate side of a pair defeats promotion, even when the aggregate counts
+ * are equal. A pair where the candidate is not misleading, or both sides are,
+ * is not candidate-specific.
+ * @param pairs The complete paired outcomes.
+ * @returns The criterion.
+ */
+export declare function pairedMisleadingCriterion(pairs: readonly PairedOutcome[]): Criterion;
+/**
+ * The personal-trial screen. The utility threshold is one component; the
+ * opportunity counts and quality checks decide the recommendation alongside
+ * it.
+ * @param controlArm The control arm id.
+ * @param candidateArm The candidate arm id.
+ * @param measures The per-arm opportunity summaries.
+ * @param counts The per-arm accounting counts.
+ * @param guardrails The candidate arm's aggregate guardrail status and detail.
+ * @param guardrails.status The aggregate status (clean, breached, unresolved).
+ * @param guardrails.detail The guardrail evidence.
+ * @param coverage The assessment-coverage limb.
+ * @param coverage.status The limb's status.
+ * @param coverage.detail The limb's reason.
+ * @param utilityThreshold The analyser's utility-threshold limb.
+ * @param utilityThreshold.status The limb's status.
+ * @param utilityThreshold.lead The assessed lead.
+ * @param utilityThreshold.interval The full-population interval.
+ * @param pairs The complete paired scenario outcomes, when available.
+ * @returns The recommendation and every criterion's reason.
+ */
+export declare function personalTrialDecision(controlArm: string, candidateArm: string, measures: Record<string, ArmMeasureSummary>, counts: Record<string, AccountingCounts>, guardrails: {
+    status: string;
+    detail: string;
+}, coverage: {
+    status: string;
+    detail: string;
+}, utilityThreshold: {
+    status: string;
+    lead: number | null;
+    interval: {
+        low: number;
+        high: number;
+    } | null;
+}, pairs?: readonly PairedOutcome[]): PersonalTrialDecision;
+export {};