{"record":{"id":"f4bd7e5d5125c42d","repo":"abhigyanpatwari/GitNexus","slug":"optional-icebug-engine-currently-requires-determin","errorCode":null,"errorMessage":"optional icebug engine currently requires deterministic threads=1","messagePattern":"optional icebug engine currently requires deterministic threads=1","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"gitnexus/src/core/ingestion/community-processor.ts","lineNumber":535,"sourceCode":"    engineRequested,\n  };\n};\n\nconst isIntegerPartition = (partition: ArrayLike<number>): boolean => {\n  for (let index = 0; index < partition.length; index++) {\n    if (!Number.isSafeInteger(partition[index])) return false;\n  }\n  return true;\n};\n\nconst runIcebugWorker = (\n  nodeCount: number,\n  csr: CommunityCsr,\n  options: CommunityDetectionOptions,\n): Promise<IcebugWorkerSuccess> => {\n  const threads = options.icebug?.threads ?? 1;\n  if (!Number.isSafeInteger(threads) || threads !== 1) {\n    throw new Error('optional icebug engine currently requires deterministic threads=1');\n  }\n  if (options.icebug?.randomize === true) {\n    throw new Error('optional icebug engine currently requires randomize=false');\n  }\n\n  const worker = new Worker(ICEBUG_WORKER_SOURCE, {\n    eval: true,\n    workerData: {\n      nodeCount,\n      indices: csr.indices,\n      indptr: csr.indptr,\n      threads,\n      seed: options.icebug?.seed ?? LEIDEN_SEED,\n      iterations: options.icebug?.iterations ?? 4,\n      gamma: options.icebug?.gamma ?? 1.0,\n      randomize: options.icebug?.randomize ?? false,\n    },\n  });","sourceCodeStart":517,"sourceCodeEnd":553,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/ingestion/community-processor.ts#L517-L553","documentation":"Thrown by runIcebugWorker (community-processor.ts) when the optional icebug community-detection engine is requested but options.icebug.threads is not exactly the integer 1. The deterministic-output guarantee that GitNexus relies on (community IDs feed generated context) requires single-threaded execution; multi-threaded Leiden produces non-reproducible partitions. icebug is an optional native engine — the default engine is Graphology (pure JS Leiden).","triggerScenarios":"Configuring community detection with engine: 'icebug' and icebug.threads set to 2 or more; threads set to a non-integer (e.g. 1.5); threads set to 0 or a negative number.","commonSituations":"Operator copied an icebug config from docs/examples that suggested threads > 1 for speed; a config file left threads unset incorrectly via a non-integer; experimenting with the optional engine without reading the determinism constraint.","solutions":["Set icebug.threads to 1 (or omit it — the default is 1) when using the icebug engine.","If you need multi-threaded community detection and don't require reproducibility, note this engine intentionally forbids it — use the default Graphology engine instead, or accept that icebug is gated to threads=1.","Do not retry with the same threads value — this is a deterministic guard, not a transient failure."],"exampleFix":"// before — threads > 1 trips the determinism guard\nrunIcebugWorker(n, csr, { icebug: { threads: 4, seed: 42 } });\n\n// after — single-threaded, deterministic\nrunIcebugWorker(n, csr, { icebug: { threads: 1, seed: 42 } });","handlingStrategy":"validation","validationCode":"function isDeterministicIcebugConfig(opts: { icebug?: { threads?: unknown } }): boolean {\n  const t = opts.icebug?.threads ?? 1;\n  return Number.isSafeInteger(t) && t === 1;\n}\n// before calling community detection with engine:'icebug':\nif (!isDeterministicIcebugConfig(options)) {\n  throw new Error('icebug requires threads=1; refusing non-deterministic config');\n}","typeGuard":"function isIcebugThreads1(v: unknown): v is 1 {\n  return Number.isSafeInteger(v) && v === 1;\n}","tryCatchPattern":null,"preventionTips":["Omit icebug.threads (default 1) or set it explicitly to 1.","Do not attempt multi-threaded icebug — the determinism gate is intentional and will not be relaxed.","Use the default Graphology engine if you don't need icebug's specific behavior."],"tags":["icebug","community-detection","determinism","ingestion","config"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}