import type { MetricSpec } from "./goal-parser.js";
/**
 * v0.4 — `results.tsv` append-only tracker + `_best.json` keeper.
 *
 * Per docs/plan/v0.4-autonomous-engine.md §5.
 *
 * results.tsv schema (10 fields, append-only, schema_version=1):
 *   cycle  timestamp  agent  metric  value  status  commit  provenance  task_id  description
 *
 * task_id is a foreign key into v0.3.0 `_events.jsonl` of the workflow that
 * the cycle's spawn(s) belong to — allows JOIN of cost/duration/stage onto
 * each result row.
 */
export declare const RESULTS_SCHEMA_VERSION = 1;
export type CycleStatus = "keep" | "discard";
export interface CycleResult {
    cycle: number;
    timestamp: string;
    agent: string;
    metric: string;
    value: number;
    status: CycleStatus;
    commit: string | "-";
    provenance: string;
    task_id: string;
    description: string;
}
export interface BestCycle {
    /** Cycle index. */
    cycle: number;
    /** Commit SHA of this keep cycle. */
    commit: string;
    /** ISO timestamp. */
    timestamp: string;
    /** Sum of normalized metric scores. Higher = better. */
    composite_score: number;
    /** Map metric name → value for transparency. */
    metric_values: Record<string, number>;
}
export declare function resultsTsvPath(workspace: string, orgSlug: string, goalId: string): string;
export declare function bestJsonPath(workspace: string, orgSlug: string, goalId: string): string;
export declare function goalDir(workspace: string, orgSlug: string, goalId: string): string;
export declare function ensureResultsTsv(workspace: string, orgSlug: string, goalId: string): string;
export declare function appendResults(workspace: string, orgSlug: string, goalId: string, rows: CycleResult[]): void;
export declare function readResults(workspace: string, orgSlug: string, goalId: string): CycleResult[];
export declare function readBest(workspace: string, orgSlug: string, goalId: string): BestCycle | null;
export declare function writeBest(workspace: string, orgSlug: string, goalId: string, best: BestCycle): void;
/**
 * Update _best.json if `candidate` outperforms the current best.
 * Composite score = sum over metrics of (normalized contribution).
 * For maximize: value / threshold (capped to [0, +∞)).
 * For minimize: threshold / value (with value clamped to >0).
 * All metrics must be >= threshold for the cycle to be eligible (CONFIRMING gate).
 *
 * Returns the new best (or unchanged previous best).
 */
export declare function maybeUpdateBest(workspace: string, orgSlug: string, goalId: string, candidate: {
    cycle: number;
    commit: string;
    timestamp: string;
    metrics: Array<{
        spec: MetricSpec;
        value: number;
    }>;
}): {
    best: BestCycle | null;
    updated: boolean;
};
export interface JoinedRow extends CycleResult {
    /** Total tokens from the matching spawn.complete event in _events.jsonl, if any. */
    totalTokens?: number;
    /** Spawn duration in ms. */
    spawnDurationMs?: number;
}
/**
 * Join results.tsv rows with the workflow-level _events.jsonl by task_id.
 * Used by `solosquad workflow show <id>` for unified cycle display.
 *
 * The workflowId is derived from the events.jsonl location — caller passes
 * it (goal-runner records which workflow each cycle belongs to).
 */
export declare function joinEventsByTaskId(workspace: string, orgSlug: string, goalId: string, workflowId: string): JoinedRow[];
export interface GoalRunSummary {
    goalId: string;
    cycleCount: number;
    keepCount: number;
    discardCount: number;
    totalCostUsd: number;
    bestCycle: BestCycle | null;
    lastCycleTimestamp?: string;
}
export declare function summarizeRun(workspace: string, orgSlug: string, goalId: string, cycleCostMap: Record<number, number>): GoalRunSummary;