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

package/dist/harnesses/impls/stub.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Env-gated stub harness for the T2.2 producer/evaluator gate.
+ *
+ * When JINN_HARNESS_STUB_INSTANCE is set, the canned patch at
+ * <fixturesDir>/<instanceMatcher>.patch is returned as a SWE-rebench v2
+ * restoration solution. Never calls an LLM; never accepts tasks whose
+ * spec.instance_id differs from the configured matcher.
+ *
+ * PRODUCTION SAFETY — two-env-var requirement.
+ * This is a *fake* harness: it produces canned, non-genuine work. If it ever
+ * entered a real operator run it would generate fraudulent on-chain activity.
+ * To make accidental activation impossible, the factory requires BOTH:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to
+ *   JINN_TEST_MODE === '1'         — explicit test-mode sentinel
+ * If JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not '1', the
+ * factory THROWS rather than silently registering the stub. A single stray
+ * exported env var in an operator's shell can no longer activate it.
+ *
+ * Activated by environment variables:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to (required to activate)
+ *   JINN_TEST_MODE                 — must equal '1' (defense-in-depth; required to activate)
+ *   JINN_HARNESS_STUB_FIXTURES_DIR — dir containing <instanceMatcher>.patch files
+ *                                    (default: client/test/release/tier-2/fixtures)
+ */
+import type { Harness, HarnessContext, ReadyStatus, Solution } from '../types.js';
+export interface StubHarnessConfig {
+    /** Directory containing <instanceMatcher>.patch files. */
+    fixturesDir: string;
+    /** The instance ID this stub will accept. Tasks with other instance IDs are rejected. */
+    instanceMatcher: string;
+}
+/**
+ * A zero-LLM Harness that returns a canned patch for a specific SWE-rebench v2
+ * instance. Intended exclusively for T2.2 release-gate automation.
+ */
+export declare class StubHarness implements Harness {
+    readonly name = "harness:stub";
+    readonly version = "0.1.0-stub";
+    private readonly fixturesDir;
+    private readonly instanceMatcher;
+    constructor(config: StubHarnessConfig);
+    supports(ctx: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): boolean;
+    isReady(): Promise<ReadyStatus>;
+    run(ctx: HarnessContext): Promise<Solution>;
+}
+/**
+ * Factory that reads JINN_HARNESS_STUB_INSTANCE and JINN_HARNESS_STUB_FIXTURES_DIR
+ * from the environment and returns a configured StubHarness, or null if the env
+ * var is absent (allowing the registry to skip registration silently).
+ *
+ * Defense-in-depth: if JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is
+ * not exactly '1', this THROWS rather than returning a harness — a real
+ * operator run must never silently pick up the fake stub harness.
+ */
+export declare function maybeCreateStubHarnessFromEnv(): StubHarness | null;

package/dist/harnesses/impls/stub.js

@@ -0,0 +1,89 @@
+/**
+ * Env-gated stub harness for the T2.2 producer/evaluator gate.
+ *
+ * When JINN_HARNESS_STUB_INSTANCE is set, the canned patch at
+ * <fixturesDir>/<instanceMatcher>.patch is returned as a SWE-rebench v2
+ * restoration solution. Never calls an LLM; never accepts tasks whose
+ * spec.instance_id differs from the configured matcher.
+ *
+ * PRODUCTION SAFETY — two-env-var requirement.
+ * This is a *fake* harness: it produces canned, non-genuine work. If it ever
+ * entered a real operator run it would generate fraudulent on-chain activity.
+ * To make accidental activation impossible, the factory requires BOTH:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to
+ *   JINN_TEST_MODE === '1'         — explicit test-mode sentinel
+ * If JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not '1', the
+ * factory THROWS rather than silently registering the stub. A single stray
+ * exported env var in an operator's shell can no longer activate it.
+ *
+ * Activated by environment variables:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to (required to activate)
+ *   JINN_TEST_MODE                 — must equal '1' (defense-in-depth; required to activate)
+ *   JINN_HARNESS_STUB_FIXTURES_DIR — dir containing <instanceMatcher>.patch files
+ *                                    (default: client/test/release/tier-2/fixtures)
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+/**
+ * A zero-LLM Harness that returns a canned patch for a specific SWE-rebench v2
+ * instance. Intended exclusively for T2.2 release-gate automation.
+ */
+export class StubHarness {
+    name = 'harness:stub';
+    version = '0.1.0-stub';
+    fixturesDir;
+    instanceMatcher;
+    constructor(config) {
+        this.fixturesDir = config.fixturesDir;
+        this.instanceMatcher = config.instanceMatcher;
+    }
+    supports(ctx) {
+        if (ctx.role === 'evaluation')
+            return false;
+        return ctx.solverType === 'swe-rebench-v2.v1';
+    }
+    async isReady() {
+        return { ready: true };
+    }
+    async run(ctx) {
+        const taskInstanceId = ctx.task.spec?.['instance_id'];
+        if (taskInstanceId !== this.instanceMatcher) {
+            throw new Error(`stub harness: task.spec.instance_id=${String(taskInstanceId)} does not match configured instanceMatcher=${this.instanceMatcher}`);
+        }
+        const patchPath = path.join(this.fixturesDir, `${this.instanceMatcher}.patch`);
+        const patch = await fs.readFile(patchPath, 'utf-8');
+        return {
+            venueRef: { name: this.name },
+            gating: {},
+            solutionPayload: {
+                schemaVersion: 'swe-rebench-v2-solution.v1',
+                patch,
+            },
+        };
+    }
+}
+/**
+ * Factory that reads JINN_HARNESS_STUB_INSTANCE and JINN_HARNESS_STUB_FIXTURES_DIR
+ * from the environment and returns a configured StubHarness, or null if the env
+ * var is absent (allowing the registry to skip registration silently).
+ *
+ * Defense-in-depth: if JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is
+ * not exactly '1', this THROWS rather than returning a harness — a real
+ * operator run must never silently pick up the fake stub harness.
+ */
+export function maybeCreateStubHarnessFromEnv() {
+    const instanceMatcher = process.env['JINN_HARNESS_STUB_INSTANCE'];
+    if (!instanceMatcher)
+        return null;
+    if (process.env['JINN_TEST_MODE'] !== '1') {
+        throw new Error('stub harness must never activate in a real operator run: ' +
+            'JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not "1". ' +
+            'The stub harness produces canned, non-genuine work and would generate ' +
+            'fraudulent on-chain activity. Set JINN_TEST_MODE=1 if this is a Tier 2 ' +
+            'test; otherwise unset JINN_HARNESS_STUB_INSTANCE.');
+    }
+    const fixturesDir = process.env['JINN_HARNESS_STUB_FIXTURES_DIR'] ??
+        path.resolve(process.cwd(), 'test', 'release', 'tier-2', 'fixtures');
+    return new StubHarness({ instanceMatcher, fixturesDir });
+}
+//# sourceMappingURL=stub.js.map

package/dist/harnesses/impls/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../../src/harnesses/impls/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAUlC;;;GAGG;AACH,MAAM,OAAO,WAAW;IACb,IAAI,GAAG,cAAc,CAAC;IACtB,OAAO,GAAG,YAAY,CAAC;IAEf,WAAW,CAAS;IACpB,eAAe,CAAS;IAEzC,YAAY,MAAyB;QACnC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAChD,CAAC;IAED,QAAQ,CAAC,GAAgE;QACvE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAC5C,OAAO,GAAG,CAAC,UAAU,KAAK,mBAAmB,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAmB;QAC3B,MAAM,cAAc,GAAI,GAAG,CAAC,IAAI,CAAC,IAA4C,EAAE,CAAC,aAAa,CAAC,CAAC;QAC/F,IAAI,cAAc,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,CAAC,cAAc,CAAC,8CAA8C,IAAI,CAAC,eAAe,EAAE,CAClI,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,eAAe,QAAQ,CAAC,CAAC;QAC/E,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO;YACL,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YAC7B,MAAM,EAAE,EAAE;YACV,eAAe,EAAE;gBACf,aAAa,EAAE,4BAA4B;gBAC3C,KAAK;aACN;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAClE,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,2DAA2D;YACzD,mEAAmE;YACnE,wEAAwE;YACxE,yEAAyE;YACzE,mDAAmD,CACtD,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvE,OAAO,IAAI,WAAW,CAAC,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/harnesses/impls/swe-rebench-v2-evaluator/eval-runner.d.ts

@@ -37,6 +37,36 @@ export declare class EvalCouldNotGradeError extends Error {
     readonly logExcerpt: string;
     constructor(reason: string, logExcerpt?: string);
 }
+/**
+ * Thrown by `runEval` when the disk cannot be brought above the eval
+ * disk-floor even after a broad prune. A clean abort — the caller stops
+ * gracefully; no instance is graded, nothing is marked. Distinct from
+ * `EvalCouldNotGradeError`: this is operator-environment, retryable, and must
+ * never be turned into a `scorable: false` admission (#476).
+ */
+export declare class InsufficientDiskError extends Error {
+    readonly freeBytes: number;
+    readonly floorBytes: number;
+    constructor(freeBytes: number, floorBytes: number);
+}
+/**
+ * Default free-disk floor required before an eval round: 20 GB. A single
+ * SWE-rebench eval image was observed to peak transiently at ~12.6 GB, so the
+ * floor clears the worst observed instance with real margin. Override with
+ * `JINN_EVAL_DISK_FLOOR_GB` on constrained hosts.
+ */
+export declare const DEFAULT_EVAL_DISK_FLOOR_BYTES = 20000000000;
+/** Resolve the disk floor: explicit option > `JINN_EVAL_DISK_FLOOR_GB` env > default. */
+export declare function resolveDiskFloorBytes(opt: number | undefined): number;
+/**
+ * Default wall-clock limit for one upstream eval.py invocation: 2 hours. Some
+ * linux/amd64 SWE-rebench images can wedge indefinitely under Apple Silicon
+ * emulation after a native crash, so the subprocess gets a hard guardrail.
+ * Override with `JINN_SWE_REBENCH_EVAL_TIMEOUT_MS`; set `0` to disable.
+ */
+export declare const DEFAULT_EVAL_TIMEOUT_MS: number;
+/** Resolve the eval timeout: explicit option > env > default. */
+export declare function resolveEvalTimeoutMs(opt: number | undefined): number;
 export interface PythonEvalRunnerOptions {
     /** Path to the cloned SWE-rebench-V2 repo (cached locally). */
     upstreamRepoDir: string;
@@ -45,66 +75,55 @@ export interface PythonEvalRunnerOptions {
     /** Workers for parallel eval (defaults to 1; we run one task at a time). */
     maxWorkers?: number;
     /**
-     * Max number of distinct eval images to keep in the local Docker cache.
-     * The runner tracks an in-process LRU keyed by image tag; once usage exceeds
-     * this cap, the least-recently-used images are removed via
-     * {@link PythonEvalRunnerOptions.cleanupImage}.
-     *
-     * The leaderboard pool has hundreds of unique instances at ~3 GB/image, so
-     * an unbounded cache fills operator disks in days (jinn-mono-uy6v.11).
+     * Removes a completed round's entire Docker footprint — the round's image,
+     * stopped containers, and build cache — so eval disk usage never
+     * accumulates across instances (#476). Called once per `runEval`, in a
+     * `finally`, even when the eval threw.
      *
-     * Default: `process.env.JINN_EVAL_IMAGE_CACHE_MAX` parsed as an integer, or
-     * `DEFAULT_EVAL_IMAGE_CACHE_MAX` (20) if unset/invalid.
+     * Defaults to {@link defaultPruneRound}. Implementations MUST NOT throw —
+     * `runEval` guards defensively, but cleanup failures should be swallowed
+     * (logged elsewhere if desired) so a flaky `docker` never escapes `runEval`.
      */
-    imageCacheMax?: number;
+    pruneRound?: (image: string) => Promise<void>;
     /**
-     * Removes an image from the local Docker cache (or no-ops if the operator
-     * has chosen not to GC). Called for each eviction from the LRU.
-     *
-     * Defaults to `docker rmi <image>` via the system `docker` binary. Test
-     * suites inject a stub to capture the eviction order without shelling out.
-     *
-     * Implementations MUST NOT throw — failures should be swallowed (logged
-     * elsewhere if desired) so a missing/failed `docker rmi` never escapes
-     * `runEval`. The runner enforces this defensively too.
+     * Resolves the eval image digest while the image is still local, before
+     * per-round pruning removes it. Defaults to `docker image inspect`.
+     */
+    resolveImageDigest?: (image: string) => Promise<string | null>;
+    /**
+     * Required free disk (bytes) before an eval round starts. Explicit value >
+     * `JINN_EVAL_DISK_FLOOR_GB` env > {@link DEFAULT_EVAL_DISK_FLOOR_BYTES}.
      */
-    cleanupImage?: (image: string) => Promise<void>;
+    diskFloorBytes?: number;
+    /** Probe of free disk (bytes). Defaults to a `statfs` on the temp dir. */
+    freeDiskBytes?: () => Promise<number>;
+    /**
+     * Broad reclaim invoked when free disk is below the floor. Defaults to
+     * `docker system prune -f`. MUST NOT throw.
+     */
+    systemPrune?: () => Promise<void>;
+    /**
+     * Wall-clock timeout (ms) for one upstream eval.py invocation. Explicit value
+     * > `JINN_SWE_REBENCH_EVAL_TIMEOUT_MS` env > {@link DEFAULT_EVAL_TIMEOUT_MS}.
+     * Set to 0 to disable.
+     */
+    evalTimeoutMs?: number;
 }
-/**
- * Default cap on the per-instance Docker image cache when no explicit
- * `imageCacheMax` and no `JINN_EVAL_IMAGE_CACHE_MAX` env var are configured.
- *
- * 20 images × ~3 GB/image ≈ 60 GB working set — small enough that even a
- * 256 GB disk has headroom, large enough that the steady-state loop on a
- * frequently-repeating subset of the pool rarely re-pulls.
- */
-export declare const DEFAULT_EVAL_IMAGE_CACHE_MAX = 20;
-export declare function resolveImageCacheMax(opt: number | undefined): number;
 export declare function matchInfraSignature(log: string): string | null;
 export declare class PythonEvalRunner implements EvalRunner {
     private readonly opts;
-    /**
-     * LRU of image tags whose Docker layers may be cached locally. Stored as a
-     * `Set<string>` because `Set` preserves insertion order; we delete-then-add
-     * to refresh recency and `next()` on the keys iterator to find the
-     * least-recently-used entry.
-     */
-    private readonly imageLru;
-    private readonly imageCacheMax;
-    private readonly cleanupImage;
+    private readonly pruneRound;
+    private readonly diskFloorBytes;
+    private readonly freeDiskBytes;
+    private readonly systemPrune;
+    private readonly resolveImageDigest;
+    private readonly evalTimeoutMs;
     constructor(opts: PythonEvalRunnerOptions);
-    runEval(args: Parameters<EvalRunner['runEval']>[0]): ReturnType<EvalRunner['runEval']>;
     /**
-     * Move `image` to the most-recently-used slot of the in-process LRU; if the
-     * set now exceeds {@link imageCacheMax}, evict the oldest entries via
-     * {@link cleanupImage}. Eviction failures are swallowed so a flaky
-     * `docker rmi` cannot escape `runEval`.
-     *
-     * The cap is enforced after the just-used image is inserted: the
-     * just-evaluated image is the *most* recent, so repeat-evals of recently
-     * used instances never re-pull. Only when more than N distinct images have
-     * been used does the oldest get rmi'd.
+     * Ensure enough free disk for an eval round. Below the floor → broad prune →
+     * re-probe; still below → `InsufficientDiskError` (clean abort). (#476)
      */
-    private recordImageUsage;
+    private ensureDiskHeadroom;
+    runEval(args: Parameters<EvalRunner['runEval']>[0]): ReturnType<EvalRunner['runEval']>;
     private runEvalImpl;
 }