@theokit/sdk 5.9.1 → 5.10.0

package/dist/chunk-OF2CLCTH.cjs

@@ -1,186 +0,0 @@
-'use strict';
-
-var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
-var chunkUNFBHV46_cjs = require('./chunk-UNFBHV46.cjs');
-var chunk6LHQPOMI_cjs = require('./chunk-6LHQPOMI.cjs');
-var fs = require('fs');
-var path = require('path');
-
-// src/internal/persistence/file-lock.ts
-var cached;
-var warnedMissing = false;
-var warnedStructural = false;
-var loadFailure;
-function isModuleAbsent(err) {
-  const code = err?.code;
-  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
-}
-function describeLockLoadFailure(err) {
-  const consequence = "cross-process file lock unavailable \u2014 concurrent processes over the same file are NOT serialized.";
-  if (isModuleAbsent(err)) {
-    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile
-`;
-  }
-  const code = err?.code;
-  const detail = err instanceof Error ? err.message : String(err);
-  return `[theokit-sdk] proper-lockfile could not be loaded${code !== void 0 ? ` (${String(code)})` : ""}: ${detail}. ${consequence} The package resolves for the SDK but failed to load \u2014 check bundling and module-format interop before re-checking the install.
-`;
-}
-async function getProperLockfile() {
-  if (cached !== void 0) return cached;
-  try {
-    const mod = await import('proper-lockfile');
-    if (!validateLockModule(mod)) {
-      if (!warnedStructural) {
-        warnedStructural = true;
-        chunk6LHQPOMI_cjs.diag(
-          "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
-        );
-      }
-      cached = null;
-      return cached;
-    }
-    cached = mod;
-  } catch (err) {
-    loadFailure = err;
-    cached = null;
-  }
-  return cached;
-}
-function validateLockModule(mod) {
-  if (mod === null || mod === void 0 || typeof mod !== "object") return false;
-  const m = mod;
-  return typeof m.lock === "function" && typeof m.unlock === "function";
-}
-async function withFileLock(path, fn, options) {
-  const lib = await getProperLockfile();
-  if (lib === null) {
-    if (!warnedMissing && !warnedStructural) {
-      warnedMissing = true;
-      chunk6LHQPOMI_cjs.diag(describeLockLoadFailure(loadFailure));
-    }
-    return chunkZF2LDKQQ_cjs.withCwdMutex(`file-lock:${path}`, fn);
-  }
-  return chunkZF2LDKQQ_cjs.withCwdMutex(`file-lock:${path}`, async () => {
-    const release = await lib.lock(path, {
-      // EC-1: companion lockfile, target path may not exist yet.
-      lockfilePath: `${path}.lock`,
-      realpath: false,
-      stale: options?.stale ?? 3e4,
-      retries: {
-        retries: options?.retries ?? 5,
-        factor: options?.retryFactor ?? 1.5,
-        minTimeout: 100,
-        maxTimeout: 5e3
-      }
-    });
-    try {
-      return await fn();
-    } finally {
-      await release();
-    }
-  });
-}
-var JsonlParseError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
-  constructor(message, line) {
-    super(message, { code: "jsonl_parse_failed", isRetryable: false });
-    this.line = line;
-  }
-  line;
-  name = "JsonlParseError";
-};
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function tryParseObjectLine(line) {
-  if (line.length === 0) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return void 0;
-  }
-  return isPlainObject(parsed) ? parsed : void 0;
-}
-function loadJsonl(path, opts = {}) {
-  const lines = fs.readFileSync(path, "utf8").split("\n");
-  const out = [];
-  for (let i = 0; i < lines.length; i += 1) {
-    const lineNumber = i + 1;
-    const line = (lines[i] ?? "").trim();
-    if (line.length === 0) continue;
-    const parsed = parseLine(
-      line,
-      lineNumber,
-      opts.tolerateTrailingPartialLine === true && lineNumber === lines.length
-    );
-    if (parsed === void 0) break;
-    out.push(opts.map ? opts.map(parsed, lineNumber) : parsed);
-  }
-  return out;
-}
-function parseLine(line, lineNumber, tolerate) {
-  let parsed;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    if (tolerate) return void 0;
-    throw new JsonlParseError(`line ${lineNumber}: invalid JSON`, lineNumber);
-  }
-  if (!isPlainObject(parsed)) {
-    throw new JsonlParseError(`line ${lineNumber}: not a JSON object`, lineNumber);
-  }
-  return parsed;
-}
-function appendJsonl(path$1, record) {
-  fs.mkdirSync(path.dirname(path$1), { recursive: true, mode: 448 });
-  const prefix = needsLineBreakBefore(path$1) ? "\n" : "";
-  const fd = fs.openSync(path$1, "a", 384);
-  try {
-    fs.writeSync(fd, `${prefix}${JSON.stringify(record)}
-`);
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-function needsLineBreakBefore(path) {
-  let fd;
-  try {
-    fd = fs.openSync(path, "r");
-  } catch {
-    return false;
-  }
-  try {
-    const size = fs.fstatSync(fd).size;
-    if (size === 0) return false;
-    const buf = Buffer.alloc(1);
-    fs.readSync(fd, buf, 0, 1, size - 1);
-    return buf[0] !== 10;
-  } finally {
-    fs.closeSync(fd);
-  }
-}
-function readJsonlIds(path, keyFn) {
-  const done = /* @__PURE__ */ new Set();
-  let text;
-  try {
-    text = fs.readFileSync(path, "utf8");
-  } catch {
-    return done;
-  }
-  for (const rawLine of text.split("\n")) {
-    const parsed = tryParseObjectLine(rawLine.trim());
-    if (parsed === void 0) continue;
-    const key = keyFn(parsed);
-    if (typeof key === "string" && key.length > 0) done.add(key);
-  }
-  return done;
-}
-
-exports.JsonlParseError = JsonlParseError;
-exports.appendJsonl = appendJsonl;
-exports.loadJsonl = loadJsonl;
-exports.readJsonlIds = readJsonlIds;
-exports.withFileLock = withFileLock;
-//# sourceMappingURL=chunk-OF2CLCTH.cjs.map
-//# sourceMappingURL=chunk-OF2CLCTH.cjs.map

package/dist/chunk-OF2CLCTH.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/persistence/file-lock.ts","../src/internal/persistence/jsonl.ts"],"names":["diag","withCwdMutex","TheokitAgentError","readFileSync","path","mkdirSync","dirname","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":"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","file":"chunk-OF2CLCTH.cjs","sourcesContent":["/**\n * Cross-process file lock helper (ADR D61).\n *\n * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When\n * the peer dep is absent, falls back to `withCwdMutex` (in-process only)\n * with a one-shot stderr warning.\n *\n * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so\n * `withFileLock` works even when the target `path` does not exist yet.\n * Without this, fresh installs that lock-then-create would crash with ENOENT.\n *\n * @internal\n */\n\nimport { diag } from \"../diagnostics.js\";\nimport { withCwdMutex } from \"./cwd-mutex.js\";\n\ninterface ProperLockfileModule {\n  lock: (file: string, options: ProperLockfileOptions) => Promise<() => Promise<void>>;\n}\n\ninterface ProperLockfileOptions {\n  lockfilePath?: string;\n  realpath?: boolean;\n  stale?: number;\n  retries?: {\n    retries: number;\n    factor?: number;\n    minTimeout?: number;\n    maxTimeout?: number;\n  };\n}\n\nlet cached: ProperLockfileModule | null | undefined;\nlet warnedMissing = false;\nlet warnedStructural = false;\n/** Why the import failed, kept so the warning can report the observation instead of a guess (#174). */\nlet loadFailure: unknown;\n\n/** Node reports a missing module as `ERR_MODULE_NOT_FOUND` (ESM loader) or `MODULE_NOT_FOUND` (CJS). */\nfunction isModuleAbsent(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n\n/**\n * #174 — build the fallback warning from what actually happened.\n *\n * This used to always read \"proper-lockfile not installed\", because the import was wrapped in a\n * bare `catch` that discarded the error (Unbreakable Rule 8: a swallowed error is the dangerous\n * kind). A consumer whose package WAS installed, declared and resolvable spent a debugging session\n * re-verifying the install, because the message named a cause the code had never checked.\n *\n * Absence is now the only case that claims absence. Every other failure — a broken install, an\n * interop problem, a bundler that rewrote the specifier — reports its own code and message, which\n * is what points at the real cause.\n *\n * @internal\n */\nfunction describeLockLoadFailure(err: unknown): string {\n  const consequence =\n    \"cross-process file lock unavailable — concurrent processes over the same file are NOT serialized.\";\n  if (isModuleAbsent(err)) {\n    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile\\n`;\n  }\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  const detail = err instanceof Error ? err.message : String(err);\n  return (\n    `[theokit-sdk] proper-lockfile could not be loaded${code !== undefined ? ` (${String(code)})` : \"\"}: ` +\n    `${detail}. ${consequence} The package resolves for the SDK but failed to load — check bundling ` +\n    \"and module-format interop before re-checking the install.\\n\"\n  );\n}\n\n/** Test seam for the message builder — NOT in the public barrel. @internal */\nexport function __TESTING__describeLockLoadFailure(err: unknown): string {\n  return describeLockLoadFailure(err);\n}\n\nasync function getProperLockfile(): Promise<ProperLockfileModule | null> {\n  if (cached !== undefined) return cached;\n  try {\n    const mod = await import(\"proper-lockfile\");\n    // T5.9 — supply-chain hardening: validate the imported module\n    // exposes the API surface we depend on BEFORE caching it. A\n    // tampered or incompatible version that lacks `lock`/`unlock`\n    // functions gets treated as \"not installed\" with an advisory\n    // warning — never silently used.\n    if (!validateLockModule(mod)) {\n      if (!warnedStructural) {\n        warnedStructural = true;\n        diag(\n          \"[theokit-sdk] proper-lockfile: imported module does NOT expose \" +\n            \"the expected `lock`/`unlock` API surface. This may indicate a \" +\n            \"supply-chain compromise or an incompatible major version. \" +\n            \"Falling back to in-process mutex (no cross-process safety). \" +\n            \"Reinstall with: pnpm add proper-lockfile@^11\\n\",\n        );\n      }\n      cached = null;\n      return cached;\n    }\n    cached = mod as ProperLockfileModule;\n  } catch (err) {\n    // #174 — keep WHY. Discarding it here is what made the fallback warning assert a cause it had\n    // never observed, and sent a consumer to re-check an install that was already correct.\n    loadFailure = err;\n    cached = null;\n  }\n  return cached;\n}\n\n/**\n * T5.9 — Structural validation of the dynamically-imported\n * `proper-lockfile` module. Verifies the API surface we depend on\n * (`lock` and `unlock` as functions) is present. Pure function —\n * never throws, never mutates, never performs I/O.\n *\n * Exported via `__TESTING__validateLockModule` seam so unit tests\n * can drive the check without spinning up the dynamic import.\n *\n * @internal\n */\nfunction validateLockModule(mod: unknown): boolean {\n  if (mod === null || mod === undefined || typeof mod !== \"object\") return false;\n  const m = mod as Record<string, unknown>;\n  return typeof m.lock === \"function\" && typeof m.unlock === \"function\";\n}\n\n/**\n * T5.9 — Test seam: expose the structural validator for unit tests.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__validateLockModule(mod: unknown): boolean {\n  return validateLockModule(mod);\n}\n\n/**\n * T5.9 — Test seam: reset the module cache + warning flags between\n * tests so each test starts fresh. NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__resetFileLockCache(): void {\n  cached = undefined;\n  warnedMissing = false;\n  warnedStructural = false;\n  loadFailure = undefined;\n}\n\n/**\n * Retry and staleness tuning for `withFileLock`.\n *\n * Every field is optional and the defaults are applied per call, so `undefined` means the default\n * rather than \"no limit\". They are handed to `proper-lockfile` and have NO effect on the fallback\n * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which\n * queues indefinitely and never goes stale.\n *\n * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a\n * dead process and broken. Setting it below the longest a legitimate holder can run is what turns\n * a slow operation into two concurrent ones.\n *\n * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`\n * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to\n * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall\n * through to running `fn` unlocked.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface FileLockOptions {\n  /** Stale lock timeout in ms. Default 30_000 (30s). */\n  stale?: number;\n  /** Max retries on busy lock. Default 5. */\n  retries?: number;\n  /** Backoff factor between retries. Default 1.5. */\n  retryFactor?: number;\n}\n\n/**\n * Run `fn` while holding an OS-level cross-process lock on `path`.\n *\n * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`\n * file (`realpath: false`, so target file does NOT need to exist yet).\n * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot\n * stderr warning telling the user to install `proper-lockfile` for\n * cross-process safety.\n *\n * The lock is released even when `fn` throws.\n *\n */\nexport async function withFileLock<T>(\n  path: string,\n  fn: () => Promise<T>,\n  options?: FileLockOptions,\n): Promise<T> {\n  const lib = await getProperLockfile();\n\n  if (lib === null) {\n    // #174 — stay silent when the structural check already explained itself. Emitting \"not\n    // installed\" on top of \"does not expose lock/unlock\" would be two contradictory diagnoses of\n    // one failure, and the reader has no way to tell which is true.\n    if (!warnedMissing && !warnedStructural) {\n      warnedMissing = true;\n      diag(describeLockLoadFailure(loadFailure));\n    }\n    return withCwdMutex(`file-lock:${path}`, fn);\n  }\n\n  // proper-lockfile errors immediately on same-process concurrent acquire\n  // (\"Lock file is already being held\"). Wrap with cwd-mutex first so\n  // in-process callers queue and only ONE thread at a time enters the\n  // cross-process acquire path. Combined: full in-process + cross-process\n  // serialization.\n  return withCwdMutex(`file-lock:${path}`, async () => {\n    const release = await lib.lock(path, {\n      // EC-1: companion lockfile, target path may not exist yet.\n      lockfilePath: `${path}.lock`,\n      realpath: false,\n      stale: options?.stale ?? 30_000,\n      retries: {\n        retries: options?.retries ?? 5,\n        factor: options?.retryFactor ?? 1.5,\n        minTimeout: 100,\n        maxTimeout: 5_000,\n      },\n    });\n\n    try {\n      return await fn();\n    } finally {\n      await release();\n    }\n  });\n}\n\n/**\n * Test helper — resets the cached proper-lockfile module + warning flag.\n * Allows tests to simulate \"module absent\" by clearing cache then\n * monkey-patching the dynamic import resolution.\n *\n * @internal\n */\nexport function _resetFileLockCacheForTesting(): void {\n  cached = undefined;\n  warnedMissing = false;\n}\n","/**\n * Durable JSONL primitives shared by the eval harness (M6).\n *\n * - `loadJsonl` — generic dataset reader (split/trim/skip-blank/parse) with a\n *   line-numbered {@link JsonlParseError}. The dataset SCHEMA is the caller's\n *   concern via `map` (M6 ADR D3) — this module owns only the parse.\n * - `appendJsonl` / `readJsonlIds` — crash-durable, resumable batch persistence\n *   (M6 ADR D1): each record is appended as one whole `\\n`-terminated line the\n *   instant it is produced, and a re-run resumes by skipping already-keyed rows.\n *\n * reference: knowledge-base/references/theocode-eval/lib/swebench-dataset.ts:82\n * (parseJsonl + line-N error) and swebench-batch.ts:113,205 (resume + per-line\n * flush).\n *\n * @internal\n */\nimport {\n  closeSync,\n  fstatSync,\n  mkdirSync,\n  openSync,\n  readFileSync,\n  readSync,\n  writeSync,\n} from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */\nexport class JsonlParseError extends TheokitAgentError {\n  override readonly name = \"JsonlParseError\";\n  constructor(\n    message: string,\n    readonly line: number,\n  ) {\n    // Not retryable: the bytes on the line do not change between reads.\n    super(message, { code: \"jsonl_parse_failed\", isRetryable: false });\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Parse a single trimmed line to a plain object, or `undefined` if blank / invalid / non-object. */\nfunction tryParseObjectLine(line: string): Record<string, unknown> | undefined {\n  if (line.length === 0) return undefined;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return undefined;\n  }\n  return isPlainObject(parsed) ? parsed : undefined;\n}\n\n/**\n * Parse a JSONL file into rows. Blank lines are skipped. A malformed or\n * non-object line throws {@link JsonlParseError} naming the 1-based line. When\n * `map` is provided, each raw object is mapped to the typed row (the SWE-bench\n * schema lives in the caller's `map`, per M6 ADR D3).\n */\nexport function loadJsonl<T = Record<string, unknown>>(\n  path: string,\n  opts: {\n    map?: (raw: Record<string, unknown>, lineNumber: number) => T;\n    /**\n     * M81 — tolerate a truncated LAST line (a crash artifact: the process died mid-write).\n     *\n     * Opt-in on purpose. As a default it would also swallow corruption in the MIDDLE of the file,\n     * turning loud data loss into silent data loss — the wrong trade for a session store.\n     */\n    tolerateTrailingPartialLine?: boolean;\n  } = {},\n): T[] {\n  const lines = readFileSync(path, \"utf8\").split(\"\\n\");\n  const out: T[] = [];\n  for (let i = 0; i < lines.length; i += 1) {\n    const lineNumber = i + 1;\n    const line = (lines[i] ?? \"\").trim();\n    if (line.length === 0) continue;\n    // M81 — `undefined` = a tolerated invalid line (the last one, truncated by a crash). Any other\n    // invalid line has already thrown inside `parseLine`.\n    const parsed = parseLine(\n      line,\n      lineNumber,\n      opts.tolerateTrailingPartialLine === true && lineNumber === lines.length,\n    );\n    if (parsed === undefined) break;\n    out.push(opts.map ? opts.map(parsed, lineNumber) : (parsed as unknown as T));\n  }\n  return out;\n}\n\n/**\n * Parses ONE line, returning `undefined` when it is a tolerated truncated last line.\n *\n * Extracted because `loadJsonl` went over the cognitive-complexity ceiling once it gained the\n * tolerance — and because parsing a line and iterating a file are two responsibilities that were\n * only together out of habit.\n */\nfunction parseLine(\n  line: string,\n  lineNumber: number,\n  tolerate: boolean,\n): Record<string, unknown> | undefined {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    if (tolerate) return undefined;\n    throw new JsonlParseError(`line ${lineNumber}: invalid JSON`, lineNumber);\n  }\n  if (!isPlainObject(parsed)) {\n    throw new JsonlParseError(`line ${lineNumber}: not a JSON object`, lineNumber);\n  }\n  return parsed;\n}\n\n/**\n * Append one record as a whole `\\n`-terminated JSON line. Creates the parent dir\n * if missing. `appendFileSync` is synchronous, so within a single Node process\n * the event loop serializes writes and each call writes its line atomically —\n * interleave-safe for the bounded-concurrency batch runner.\n *\n * reference: swebench-batch.ts:192 (mkdir-before-append), :205 (per-line flush).\n */\nexport function appendJsonl(path: string, record: unknown): void {\n  // T2.4 — `0o700` for the same reason the file below is `0o600`, and it is the half M93 missed. A\n  // private file inside a group-writable directory can be replaced wholesale, and the replacement's\n  // mode is whatever the writer chose. Under `umask 002` this directory was born `0775`.\n  //\n  // The directory sits under `~/.theokit`, shared with the credential and trust stores, and the\n  // framework already wrote the diagnosis while fixing a sibling (`@theokit/agents\n  // config/trust-store.ts:157-161`): the mode argument is a no-op on a directory that already\n  // exists, \"and this one is shared with the SDK's transcript root — whoever creates it first sets\n  // the permissions\". Whoever creates it first is usually THIS function, because a session writes a\n  // transcript before it ever touches a credential. So `assertSecureModes` was not wrong to demand a\n  // private directory; this path was wrong to produce one that fails it, depending on run order.\n  //\n  // Creation-time only, deliberately: repairing a pre-existing directory means `stat` + `chmod` on\n  // every append, and this is the hot path of every session. The pre-existing case is what\n  // `assertSecureModes` is for.\n  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });\n  const prefix = needsLineBreakBefore(path) ? \"\\n\" : \"\";\n  // M93 (adversarial review, H1) — `0o600`. `appendFileSync` takes no `mode`, so the permission came\n  // from the umask: under `umask 022` the transcript was born `0664`, world-readable. The previous\n  // path (`replaceFileAtomic`) pinned `0o600` on purpose — \"holds the FULL in-flight content\n  // (credential snapshots, OAuth tokens)\" (`atomic-write.ts:107`) — and switching to append lost\n  // that silently. The same class had already been caught in the consumer (`atomic-sync.ts`, M88\n  // HIGH-1).\n  //\n  // `mode` only applies on CREATION; a pre-existing file keeps whatever permission it already has.\n  const fd = openSync(path, \"a\", 0o600);\n  try {\n    writeSync(fd, `${prefix}${JSON.stringify(record)}\\n`);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Does the file end without a `\\n`? Then the last line is truncated — a crash mid-append.\n *\n * Without this check the next append **glues** itself onto the middle of the broken line, producing\n * an invalid line the reader discards: the NEW record disappears along with the partial one. The\n * previous path (read-modify-write) self-healed from this because it rewrote the whole file.\n * Measured in M93's adversarial review (H2): after an append over a truncated file, the\n * just-written record was no longer readable.\n *\n * Reads **one byte**, not the file.\n */\nfunction needsLineBreakBefore(path: string): boolean {\n  let fd: number;\n  try {\n    fd = openSync(path, \"r\");\n  } catch {\n    return false; // the file does not exist yet: nothing to splice onto\n  }\n  try {\n    const size = fstatSync(fd).size;\n    if (size === 0) return false;\n    const buf = Buffer.alloc(1);\n    readSync(fd, buf, 0, 1, size - 1);\n    return buf[0] !== 0x0a;\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Read the set of keys from an existing JSONL file for which `keyFn(parsed)`\n * returns a non-empty string. Used to resume a crashed batch by skipping rows\n * already persisted with a successful result. A trailing partial line from an\n * interrupted append is tolerated (skipped, not thrown), and a missing file\n * yields an empty set.\n *\n * reference: swebench-batch.ts:113 (readDoneIds), :129 (success-only),\n * :131 (tolerate partial line).\n */\nexport function readJsonlIds(\n  path: string,\n  keyFn: (parsed: Record<string, unknown>) => string | undefined,\n): Set<string> {\n  const done = new Set<string>();\n  let text: string;\n  try {\n    text = readFileSync(path, \"utf8\");\n  } catch {\n    return done; // no file yet → nothing done\n  }\n  for (const rawLine of text.split(\"\\n\")) {\n    // A trailing partial line from an interrupted run parses to undefined → skipped.\n    const parsed = tryParseObjectLine(rawLine.trim());\n    if (parsed === undefined) continue;\n    const key = keyFn(parsed);\n    if (typeof key === \"string\" && key.length > 0) done.add(key);\n  }\n  return done;\n}\n"]}