@jinn-network/client 0.1.6 → 0.1.7-canary.0a586ca9

package/dist/solver-types/_swe-rebench-v2-validated-pool.d.ts

@@ -34,11 +34,35 @@ import { type CommandRunner } from './_swe-rebench-v2-substrate.js';
  *         `upstreamEvalCommit`) and extended ungradeable classifier
  *         (venv collision, missing pytest, dependency warnings, conftest
  *         import/setup failures) — jinn-mono-fufn.
+ *   '4' — adds the buildTestCommands pytest-install guard (#493): for
+ *         parse_log_pytest rows whose install_config.install does not
+ *         already mention pytest, prepend a best-effort install line so
+ *         the `ungradeable:pytest_missing` bucket (the highest-yield
+ *         capacity blocker on the Stage-1 histogram) becomes scorable.
+ *         The v3→v4 transition is a *targeted* migration, not a wholesale
+ *         invalidation: only `ungradeable:pytest_missing` entries can flip
+ *         under the install guard, so they alone are dropped (re-validated);
+ *         every other verdict (scorable, gold-patch-not-resolved,
+ *         transient/error/other ungradeable) is carried forward verbatim
+ *         (see {@link loadOrMigrateFile}).
  */
-export declare const EVAL_SEMANTICS_VERSION = "3";
+export declare const EVAL_SEMANTICS_VERSION = "4";
+export declare const SWE_REBENCH_V2_VETTED_POOL_ARTIFACT_TYPE: "swe-rebench-v2-vetted-pool.v1";
+export declare const SOLVERNET_ARTIFACT_REF_SCHEMA_VERSION: "solvernet.artifact-ref.v1";
+export declare const VETTED_POOL_REF_ELIGIBILITY_KEY: "vettedPoolRef";
+declare const PUBLICATION_SCHEMA_VERSION: "swe-rebench-v2-vetted-pool-publication.v1";
 export interface ValidatedPoolEntry {
     scorable: boolean;
-    /** Why scorable/unscorable — `'gold-patch-resolves'`, `'ungradeable:<reason>'`, etc. */
+    /**
+     * Why scorable/unscorable — `'gold-patch-resolves'`, `'ungradeable:<reason>'`,
+     * `'transient:HF-429:<msg>'`, `'error:HF-429-permanent-after-5-passes'`, etc.
+     *
+     * Reason prefixes:
+     *   - `transient:` — non-terminal; the next `validatePoolInstances` pass
+     *     re-processes the entry until `transientRetryCount` hits {@link MAX_TRANSIENT_PASSES}.
+     *   - everything else (including `error:`, `ungradeable:`, etc.) — terminal
+     *     under the skip-check; only re-processed when `opts.force` is set.
+     */
     reason: string;
     checkedAt: string;
     /** Canonical-JSON SHA-256 over the HF row fields used for grading. v3+. */
@@ -49,7 +73,84 @@ export interface ValidatedPoolEntry {
     imageDigest?: string;
     /** `git rev-parse HEAD` of the enabled upstream SWE-rebench repo at validation time. v3+. */
     upstreamEvalCommit?: string;
+    /**
+     * Number of consecutive `validatePoolInstances` passes that have recorded a
+     * `transient:` reason for this instance under this `evalSemanticsVersion`.
+     * Bumped on each pass; flips the reason to `error:HF-429-permanent-after-5-passes`
+     * once it hits {@link MAX_TRANSIENT_PASSES} (issue #578). Undefined for
+     * non-transient entries (treated as `0` on read).
+     */
+    transientRetryCount?: number;
+    /** ISO timestamp of the most recent transient pass. Undefined for non-transient entries. */
+    lastTransientAt?: string;
 }
+/**
+ * Cap on consecutive transient passes before an instance flips to the
+ * terminal `error:HF-429-permanent-after-5-passes` reason. Issue #578: the
+ * AC says "the failure is still recorded for visibility, but the validation
+ * pipeline distinguishes transient from permanent so the next run reprocesses
+ * these instances"; this is the convergence boundary that keeps a
+ * permanently-broken split from churning forever.
+ */
+export declare const MAX_TRANSIENT_PASSES = 5;
+/**
+ * The operator-environment subset of `EvalCouldNotGradeError` reasons that are
+ * worth a bounded retry rather than being cached terminal (issue #811). These
+ * may differ on a later pass — Docker comes back, a stale `.venv` is cleaned,
+ * the host's missing venv is provisioned. `image_arch_mismatch` is fixed
+ * per-machine, but the bounded retry caps the waste: it converges to the
+ * terminal `ungradeable:` reason after {@link MAX_TRANSIENT_PASSES}, so there
+ * is no infinite loop.
+ *
+ * Every OTHER `EvalCouldNotGradeError` reason (pytest_missing,
+ * install_build_failed, conftest_import_error, requests_dep_mismatch,
+ * eval_setup_error, …) is a real per-instance problem where a blind retry
+ * won't help; those stay `ungradeable:` terminal. `pytest_missing` in
+ * particular needs the #493 code fix, not a retry.
+ */
+export declare const TRANSIENT_INFRA_REASONS: ReadonlySet<string>;
+export interface SweRebenchV2VettedPoolArtifactEntry extends ValidatedPoolEntry {
+    instance_id: string;
+    scorable: true;
+}
+export interface SweRebenchV2VettedPoolArtifact {
+    schemaVersion: typeof SWE_REBENCH_V2_VETTED_POOL_ARTIFACT_TYPE;
+    evalSemanticsVersion: string;
+    generatedAt: string;
+    entries: SweRebenchV2VettedPoolArtifactEntry[];
+}
+export interface SolverNetArtifactRef {
+    schemaVersion: typeof SOLVERNET_ARTIFACT_REF_SCHEMA_VERSION;
+    manifestCid: string;
+    artifactType: typeof SWE_REBENCH_V2_VETTED_POOL_ARTIFACT_TYPE;
+    artifactCid: string;
+    artifactHash: `sha256:${string}`;
+    evalSemanticsVersion: string;
+    publishedAt: string;
+}
+export interface VettedPoolArtifactPublication {
+    schemaVersion: typeof PUBLICATION_SCHEMA_VERSION;
+    updatedAt: string;
+    ref: SolverNetArtifactRef;
+    artifact: SweRebenchV2VettedPoolArtifact;
+}
+export interface ScorableVettedPoolArtifactEntries {
+    ids: Set<string>;
+    byId: Map<string, SweRebenchV2VettedPoolArtifactEntry>;
+}
+export declare function parseVettedPoolArtifact(raw: unknown): SweRebenchV2VettedPoolArtifact;
+export declare function hashVettedPoolArtifact(artifact: SweRebenchV2VettedPoolArtifact): `sha256:${string}`;
+export declare function loadVettedPoolArtifactScorableEntries(raw: unknown): ScorableVettedPoolArtifactEntries;
+export declare function createVettedPoolArtifactRef(args: {
+    manifestCid: string;
+    artifactCid: string;
+    artifactHash: `sha256:${string}`;
+    evalSemanticsVersion: string;
+    publishedAt: string;
+}): SolverNetArtifactRef;
+export declare function sweRebenchV2VettedPoolArtifactMetadataKey(manifestCid: string): string;
+export declare function parseVettedPoolArtifactRef(raw: unknown): SolverNetArtifactRef;
+export declare function vettedPoolArtifactRefFromEligibility(eligibility: Record<string, unknown> | undefined): SolverNetArtifactRef | null;
 export declare class ValidatedPoolStore {
     private readonly file;
     private cache;
@@ -68,10 +169,51 @@ export declare class ValidatedPoolStore {
      *  on-disk file is absent or built for a different version). Memoised by
      *  mtime so the generator's tick doesn't re-parse the JSON every poll. */
     getScorableIds(evalSemanticsVersion: string): Promise<Set<string> | null>;
+    getScorableEntries(evalSemanticsVersion: string): Promise<{
+        entries: Record<string, ValidatedPoolEntry>;
+        updatedAt: string;
+    } | null>;
     /** The entry for `instanceId`, or `null` if not validated for this semantics version. */
     getEntry(instanceId: string, evalSemanticsVersion: string): Promise<ValidatedPoolEntry | null>;
     record(instanceId: string, entry: ValidatedPoolEntry, evalSemanticsVersion: string): Promise<void>;
 }
+/**
+ * Collapse a stored `reason` string into a histogram bucket. Diagnostic
+ * detail (`(f2p X, p2p_broke Y)`, the verbatim HF 429 message) is kept on
+ * the entry for debugging, but the bucket name is what matters for the
+ * #493 reason-histogram CLI. Unknown reasons pass through unchanged.
+ */
+export declare function normalizeReason(reason: string): string;
+export interface ValidatedPoolHistogramBucket {
+    reason: string;
+    count: number;
+}
+export interface ValidatedPoolSummary {
+    totalEntries: number;
+    scorable: number;
+    unscorable: number;
+    byReason: ValidatedPoolHistogramBucket[];
+}
+/**
+ * Read-only summary of a `validated-pool.json` file. Counts entries by
+ * normalised reason (see {@link normalizeReason}) and returns the buckets
+ * sorted descending by count, with ties broken alphabetically by reason.
+ */
+export declare function summarizeValidatedPool(file: unknown): ValidatedPoolSummary;
+export declare function exportScorableVettedPoolArtifact(store: ValidatedPoolStore, evalSemanticsVersion: string, opts?: {
+    generatedAt?: string;
+}): Promise<SweRebenchV2VettedPoolArtifact | null>;
+export declare function readVettedPoolArtifactPublication(args: {
+    stateDir: string;
+    manifestCid?: string;
+    evalSemanticsVersion?: string;
+}): Promise<VettedPoolArtifactPublication | null>;
+export declare function writeVettedPoolArtifactPublication(args: {
+    stateDir: string;
+    ref: SolverNetArtifactRef;
+    artifact: SweRebenchV2VettedPoolArtifact;
+    updatedAt?: string;
+}): Promise<VettedPoolArtifactPublication>;
 export type AdmissionMode = 'required' | 'python-floor';
 /**
  * Restrict the generator's posting pool.
@@ -120,3 +262,4 @@ export declare function validatePoolInstances(pool: PoolTask[], deps: ValidatePo
     limit?: number;
     force?: boolean;
 }): Promise<ValidatePoolSummary>;
+export {};