toolroll 0.5.0

package/dist/contest.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Tournament orchestration (stage 3; the three review rounds' findings are
+ * the spec). What lives here and what deliberately does not:
+ *
+ *   - the race digest and the JOINT approval digest (finding 31): the
+ *     approval a person gives covers the scope AND the race terms as one
+ *     hash — editing either strands it;
+ *   - planning: turning asked-for agents and dollars into approved-terms
+ *     rows, refusing anything the money machinery cannot bound (finding
+ *     24: eligibility comes from the capability matrix, budgets from the
+ *     pinned prices, and every agent carries its own overrun reserve);
+ *   - admission: ONE transaction that proves everything or admits nothing
+ *     (finding 3/19/22) — the claim, the digests re-derived from stored
+ *     rows, worker-process slots, quota by distinct key, the money
+ *     arithmetic — then creates the contest skeleton;
+ *   - the ready barrier (finding 19): worktrees and setup finish for every
+ *     agent before anything spawns; the barrier is a state CAS;
+ *   - child finalization (findings 1/17): an agent finishing NEVER touches
+ *     the task, the parent claim, or publication — it writes its own row
+ *     and asks, inside the same transaction, whether the whole tournament
+ *     just reached its boundary (maybeAggregate);
+ *   - crash recovery (finding 27): a daemon death mid-dispatch or mid-race
+ *     converts the contest to 'interrupted' by the same generation CAS the
+ *     finalizers use — whoever wins, wins alone — and never charges an
+ *     agent that never started.
+ *
+ * NOT here: the pick and abandon ceremonies (stage 5), decision-wait
+ * re-admission and checkout custody (stage 4), cleanup (stage 6).
+ */
+import { type UnattendedPermissionMode } from "./scope.js";
+import type { Contest, Contestant, ContestState, Store } from "./store.js";
+export declare const MIN_AGENTS = 2;
+export declare const MAX_AGENTS = 4;
+export type RaceAgent = {
+    provider: string;
+    model: string;
+    repairModel: string;
+    permissionMode?: UnattendedPermissionMode;
+};
+/** Canonical and order-preserving: the agents race in the order approved.
+ * v2 (foundations finding 8): each lane's FULL execution profile enters the
+ * fingerprint — permissions and limits included, not just routing — via the
+ * same profile digest every other approval binds. Stored v1 fingerprints
+ * keep verifying byte-for-byte (admission compares stored values; nothing
+ * recomputes a v1). */
+export declare function raceDigestOf(terms: {
+    agents: readonly RaceAgent[];
+    perAgentBudgetMicrousd: number;
+    totalBudgetMicrousd: number;
+    priceVersion: number;
+    publicationPolicy: string;
+}): string;
+/** tournament-approval/v1 (finding 31): one yes covers both documents.
+ * Comparisons reuse it verbatim — their fingerprint rides the same stored
+ * column, and the domains below keep race and comparison terms from ever
+ * colliding. */
+export declare function jointApprovalDigest(scopeDigest: string, raceDigest: string): string;
+/** comparison/v1 (Phase 3 slice B): order-preserving, each lane's FULL
+ * profile digest included, NO money fields — none exist on a comparison. */
+export declare function comparisonDigestOf(terms: {
+    agents: readonly RaceAgent[];
+    publicationPolicy: string;
+}): string;
+export type ComparisonPlan = {
+    kind: "comparison";
+    agents: RaceAgent[];
+    publicationPolicy: string;
+    comparisonDigest: string;
+    /** Per lane, the money words the ceremony renders. */
+    laneWords: string[];
+};
+/**
+ * A comparison admits any registered provider — that is its purpose — but
+ * NEVER lets the budget ceremony be bypassed: if every asked lane could
+ * hold a native dollar cap, the refusal points at the tournament road
+ * (spec D3, the discipline gate). No dollar fields exist here at all;
+ * each lane's bound is its sealed profile's wall clock, said in words.
+ */
+export declare function planComparison(input: {
+    agents: {
+        provider: string;
+        model: string;
+        repairModel?: string;
+        permissionMode?: UnattendedPermissionMode;
+    }[];
+    publicationPolicy?: string;
+}): {
+    ok: true;
+    plan: ComparisonPlan;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** One words helper for every surface that speaks about a contest —
+ * screens, holds, notifications, decision subjects (spec E6). */
+export declare function contestNoun(kind: "race" | "comparison"): string;
+export type TournamentPlan = {
+    agents: RaceAgent[];
+    perAgentBudgetMicrousd: number;
+    /** The DEAREST agent's one-call overrun — shown on the approval card. */
+    overrunReserveMicrousd: number;
+    /** Per agent, its own reserve — what its contestant row will carry. */
+    perAgentReserveMicrousd: number[];
+    totalBudgetMicrousd: number;
+    priceVersion: number;
+    publicationPolicy: string;
+    raceDigest: string;
+};
+export declare function planTournament(input: {
+    agents: {
+        provider: string;
+        model: string;
+        repairModel?: string;
+        permissionMode?: UnattendedPermissionMode;
+    }[];
+    perAgentBudgetUsd: number;
+    totalBudgetUsd: number;
+    publicationPolicy?: string;
+}): {
+    ok: true;
+    plan: TournamentPlan;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Unique per tournament — retained loser branches never collide. */
+export declare function contestBranch(taskId: string, contestId: number, ordinal: number): string;
+export type AdmissionRefusal = {
+    ok: false;
+    reason: "no-terms" | "not-approved" | "digest-drift" | "duplicate-provider-model" | "quota" | "capacity" | "contest-open" | "steering-pending";
+    message: string;
+};
+/**
+ * All or none (finding 3): every check inside one reentrant transaction
+ * with the claim acquisition the caller already made — the caller passes
+ * its live claim, and a refusal here obliges the caller to release it.
+ */
+export declare function admitContest(store: Store, args: {
+    taskId: string;
+    taskRef: number;
+    runner: string;
+    leaseId: string;
+    incarnation: string | null;
+    scopeDigest: string;
+    scopeApproved: boolean;
+    /** slots-based capacity, enforced only in 'processes' mode (finding 26). */
+    capacity: number | null;
+    /** 'exhausted'/'cooling' answers per (provider, model) — the caller reads
+     * quota state; grouping and multiplicity rules live here (finding 22). */
+    quotaBlocked: (provider: string, model: string) => string | null;
+}, now: Date): {
+    ok: true;
+    contestId: number;
+    contestantIds: number[];
+    slotIds: number[];
+} | AdmissionRefusal;
+/** Everything prepared, nothing spawned: pending→ready per agent, then one
+ * dispatching→racing CAS. Any failure leaves the contest for recovery. */
+export declare function crossReadyBarrier(store: Store, contest: Contest, contestantIds: readonly number[]): boolean;
+export type ContestantOutcome = "built" | "failed" | "parked" | "stopped";
+/**
+ * The child finalizer (findings 1/17): writes the agent's own row, frees
+ * its worker-process slot, and — inside this same transaction — asks
+ * whether the tournament just reached its boundary. The parent claim and
+ * the task are NEVER touched here; only the aggregate boundary releases
+ * the claim, exactly once, by CAS.
+ */
+export declare function finalizeContestant(store: Store, args: {
+    contestId: number;
+    contestantId: number;
+    runId: number;
+    outcome: ContestantOutcome;
+    /** Micro-dollars the provider reported for this invocation; null latches. */
+    measuredMicrousd: number | null;
+    slotId: number | null;
+}, now: Date): {
+    aggregated: ContestState | null;
+};
+/**
+ * The aggregate boundary — runs INSIDE a child/recovery transaction. When
+ * no agent remains active: parked-with-open-question → 'decision-wait';
+ * at least one 'built' → 'pick-wait'; none → 'exhausted'. The parent
+ * claim releases conditionally; the contest-owned hold takes over the
+ * task's stillness so the board says "compare and pick", not "vanished".
+ */
+export declare function maybeAggregate(store: Store, contestId: number, now: Date): ContestState | null;
+/**
+ * Crash and reap recovery (finding 27): both CAS on the same generations
+ * the finalizers use. An agent that never crossed provider start settles
+ * at ZERO; only a started-and-silent one latches its full reservation.
+ */
+export declare function recoverContests(store: Store, now: Date): number;
+import type { Artifact, PublicationGrant, Run } from "./store.js";
+export type AgentView = {
+    contestant: Contestant;
+    run: Run | null;
+    diff: Artifact | null;
+    stat: Artifact | null;
+    pickable: boolean;
+    /** Plain words when it cannot be picked. */
+    unpickableReason: string | null;
+};
+/**
+ * Pickability, exactly as ruled (round-3 finding 20): a real result with
+ * verified, unredacted, untruncated evidence whose typed capture verdict
+ * says ok — never a prose parse, never an automatic selection.
+ */
+export declare function buildPickView(store: Store, evidenceRoot: string, contestId: number): {
+    contest: Contest;
+    agents: AgentView[];
+} | null;
+/**
+ * contest-pick/v1 — the canonical tuple the ceremony's nonce binds
+ * (round-1 finding 8 as amended): everything the password authorizes,
+ * rebuilt from live state on the POST, never accepted from a client.
+ */
+export declare function pickTupleDigest(view: {
+    contest: Contest;
+    agents: AgentView[];
+}, selection: {
+    contestantId: number;
+} | {
+    abandon: true;
+}, publication: {
+    grant: PublicationGrant | null;
+    head: string | null;
+}): string;
+/**
+ * One derivation for both moments — the POST that mints the nonce and the
+ * POST that consumes it. Publishability is decided here with exactly the
+ * tick path's predicate: committed real change, live grant, branch under
+ * the grant's prefix, selector satisfied.
+ */
+export declare function computePickPlan(store: Store, view: {
+    contest: Contest;
+    agents: AgentView[];
+}, contestantId: number, repo: string | null, refOrigin: string): {
+    ok: false;
+    message: string;
+} | {
+    ok: true;
+    chosen: AgentView & {
+        run: Run;
+    };
+    grant: PublicationGrant | null;
+    publishable: boolean;
+    digest: string;
+};
+export type PickArgs = {
+    contestId: number;
+    contestantId: number;
+    approver: string;
+    /** The submitted nonce VALUE; its hash must match a live ceremony row. */
+    nonceValue: string;
+    evidenceRoot: string;
+    repo: string | null;
+    taskId: string;
+    refOrigin: string;
+};
+export declare function nonceHashOf(value: string): string;
+/**
+ * The pick, one transaction (round-1 finding 5 + round-3 findings 8/21):
+ * nonce consumed conditionally against the REBUILT tuple digest, contest
+ * CAS'd, winner proven again byte-for-byte, losers marked for cleanup,
+ * the hold lifted, the task done, and the publication intent created —
+ * now and only now — under exactly the tick's own predicate.
+ */
+export declare function finalizeContestPick(store: Store, args: PickArgs, now: Date): {
+    ok: true;
+    state: "picked";
+    publicationIntent: number | null;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Abandon: password + nonce like the pick (it cancels paid-for work and
+ * re-opens the task), everything retained, nothing published. */
+export declare function abandonContest(store: Store, args: {
+    contestId: number;
+    approver: string;
+    nonceValue: string;
+    evidenceRoot: string;
+    taskId: string;
+}, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Fourteen days: the escalation threshold for an undecided tournament. */
+export declare const CONTEST_OVERDUE_MS: number;
+/**
+ * The cleanup pass (stage 6): once a tournament is DECIDED — picked or
+ * abandoned — every agent's checkout goes back to the pool, winners and
+ * losers alike (branches and evidence survive; a checkout is only a
+ * checkout). Custody holds: only the runner that owns a checkout releases
+ * it, and one that will not release cleanly (dirty, uninspectable) is
+ * marked for attention and paged once rather than cleaned by force.
+ */
+export declare function sweepContestCleanup(store: Store, releaseWorktree: (path: string) => Promise<{
+    ok: boolean;
+    reason?: string;
+    message?: string;
+}>, runner: string, now: Date): Promise<{
+    released: number;
+    attention: number;
+}>;
+/**
+ * Overdue escalation (stage 6): a tournament waiting on a person for
+ * fourteen days pages ONCE more — never auto-abandons, never re-pages.
+ * The age is derived from the moment the contest-owned hold took the
+ * task's stillness, which is exactly when the waiting began.
+ */
+export declare function escalateOverdueContests(store: Store, now: Date): number;