circle-ir-ai 2.31.0 → 2.32.0

package/CHANGELOG.md

@@ -5,6 +5,120 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.32.0] - 2026-07-02
+
+### Added — LLM call throttle + hard cap (cognium-ai#159 + #160, Sprint L4a)
+
+Ships the LLM call-throttle escape hatch and the per-scan / per-file
+hard cap. Both are opt-in through env vars — with everything unset the
+runtime behavior is identical to `2.31.1`, so this is additive by
+default. Coordinated with `cognium-ai@2.27.0` (doc-only companion).
+
+**cognium-ai#159 — `LLM_CONCURRENCY` alias.**
+`src/llm/ax-client.ts` already ran every LLM call through a shared
+`p-queue` with concurrency read from `LLM_MAX_CONCURRENT` (default
+`10`). The ticket's premise — "LLM calls appear fully serial" —
+turned out to be a naming/discoverability problem rather than a
+missing throttle. The fix is a rename with backward-compat:
+
+- **New env var:** `LLM_CONCURRENCY` (positive integer). Preferred
+  name going forward.
+- **Legacy env var:** `LLM_MAX_CONCURRENT` continues to work; still
+  read when `LLM_CONCURRENCY` is unset. No deprecation warning.
+- **Precedence:** `LLM_CONCURRENCY` > `LLM_MAX_CONCURRENT` > default
+  `10`. Both unset preserves the pre-2.32 behavior exactly.
+- **Recommended values:** `4–8` for Ollama, `16+` for cloud
+  providers. The default `10` is intentionally conservative.
+
+**cognium-ai#160 — `LLM_MAX_CALLS_PER_SCAN` + `LLM_MAX_CALLS_PER_FILE`.**
+New module `src/llm/call-limiter.ts` provides a global counter that
+gates every call at the transport boundary in `chatJSON`. When either
+cap is reached, subsequent calls short-circuit to `null` and the
+caller sees the same "LLM disabled" semantics that already exist for
+provider outages and prefilter rejections (`{ llmSources: [],
+llmSinks: [] }` / `{ verified: [], ... }`). No per-caller changes
+were required.
+
+New env vars, all default unset (unbounded, matches `2.31.1`
+behavior):
+- `LLM_MAX_CALLS_PER_SCAN` — total LLM calls per scan.
+- `LLM_MAX_CALLS_PER_FILE` — per-file budget. Independent per file;
+  a fresh budget is allocated the first time each file appears in
+  the `filePath` context.
+
+Behavior on cap-hit:
+1. Counter is incremented on **acquire**, not on completion, so
+   concurrent p-queue firing cannot overshoot the cap.
+2. Scan cap emits a single `console.warn` (`[call-limit]
+   LLM_MAX_CALLS_PER_SCAN=<n> reached; remaining LLM calls skipped,
+   files fall back to static-only`). Subsequent skips are silent.
+   Per-file cap is silent by design (would spam on large repos).
+3. Retries inside an already-admitted call bypass the gate
+   (`retryCount > 0`), so a retried request does not re-acquire
+   budget.
+4. A synthetic "no-call" JSONL row is written for every skipped call
+   with `skippedByCap: true` and `skippedCapReason: 'scan' | 'file'`,
+   following the existing `skippedByPrefilter` / `verifyCacheHit`
+   pattern. `analyze-llm-log.ts` in cognium-ai already surfaces
+   these rows.
+
+**Per-scan isolation.** `analyzeFilesSwarm`,
+`analyzeFilesSwarmStream`, and `analyzeFilesInBatches` in
+`src/agents/mastra/swarm.ts` bracket their work with
+`resetLLMCallLimiter(true)` + `markSwarmStart()` on entry, and
+`markSwarmEnd()` in a `finally` block. `analyzeFile` in
+`src/agents/mastra/workflow.ts` calls the unforced
+`resetLLMCallLimiter()`, which is a no-op while a swarm is
+orchestrating — this keeps the per-scan budget intact across
+swarm-nested single-file callers while still resetting for
+standalone single-file invocations.
+
+**New exports (also re-exported from `./llm/index.js`):**
+- `checkAndCountCall(ctx?)` — the gate itself. Returns `true` when
+  admitted, `false` when either cap fires.
+- `resetLLMCallLimiter(force?)` — swarm-guarded by default; `force`
+  bypasses the guard (test hook + swarm-entry use).
+- `markSwarmStart()` / `markSwarmEnd()` — bracket a swarm run to
+  suppress nested per-file resets.
+- `getLLMCallStats()` — snapshot for tail summaries: `scanCounter`,
+  `scanSkipped`, `perFileSkipped`, `scanCapWarned`,
+  `resolvedConcurrency`, `resolvedScanCap`, `resolvedFileCap`.
+- Consts: `LLM_CONCURRENCY`, `LLM_MAX_CALLS_PER_SCAN`,
+  `LLM_MAX_CALLS_PER_FILE`.
+
+**Rollback:** unset all three env vars → pre-2.32 behavior. The
+fast path in `checkAndCountCall` bails before any allocation when
+both caps are `null`, so there is zero overhead on the default path.
+
+**Tests.** New `tests/llm/call-limiter.test.ts` — 8 tests covering
+default unbounded path, scan cap admit/skip counts, WARN
+emit-exactly-once, per-file independent budgets, reset semantics,
+swarm-guard interaction, env-var precedence (new name > legacy >
+default), and scan-cap-precedes-per-file-cap ordering. Full engine
+suite: 1204 pass + 3 skipped (was 1196 pass + 3 skipped on 2.31.1;
++8 from this ticket).
+
+## [2.31.1] - 2026-07-02
+
+### Changed — circle-ir bump 3.139.0 → 3.144.0 (patch, dep-only)
+
+Refresh the pinned `circle-ir` dependency to the current published
+version. Rolls up the 3.140/3.141/3.144 releases (3.142 and 3.143
+were unpublished). No engine or public-API changes in this package.
+
+**Test update.** `tests/findings-llm-discovery.test.ts` — the
+"drops type-incompatible LLM pairs via canSourceReachSink gate" case
+previously used `http_param → deserialization` as its incompatible
+example. Upstream circle-ir Sprint 93 / cognium-dev#189 legitimately
+widened `http_param` to include `deserialization` for
+SnakeYAML/Jackson-shape gadget chains (Log4Shell shape). The test now
+uses `env_input → xss` — server-side env vars still cannot reach
+browser DOM contexts, so this pair remains outside the coverage matrix
+and the assertion still exercises the intended gate. This is a
+test-fixture correction, not a behavior change.
+
+Suite: 1196 pass + 3 skipped (was 1196 pass + 3 skipped on 3.139.0).
+
 ## [2.31.0] - 2026-07-01
 
 ### Added — large-repo architectural knobs (cognium-ai#165 + #166 L3)

package/dist/agents/mastra/steps.d.ts

@@ -5,8 +5,8 @@
  * createStep() API with Zod schemas for type safety.
  */
 export declare const patternMatchStep: import("@mastra/core/workflows").Step<"pattern-match", unknown, {
-    sourceCode: string;
     filePath: string;
+    sourceCode: string;
     language?: string | undefined;
 }, {
     imports: string[];
@@ -40,9 +40,9 @@ export declare const patternMatchStep: import("@mastra/core/workflows").Step<"pa
     }[];
 }, unknown, unknown, import("@mastra/core/workflows").DefaultEngineType, unknown>;
 export declare const enrichStep: import("@mastra/core/workflows").Step<"enrich", unknown, {
+    filePath: string;
     imports: string[];
     sourceCode: string;
-    filePath: string;
     patternSources: {
         type: string;
         line: number;
@@ -160,8 +160,8 @@ export declare const mergeStep: import("@mastra/core/workflows").Step<"merge", u
     }[];
 }, unknown, unknown, import("@mastra/core/workflows").DefaultEngineType, unknown>;
 export declare const verifyStep: import("@mastra/core/workflows").Step<"verify", unknown, {
-    sourceCode: string;
     filePath: string;
+    sourceCode: string;
     types: {
         kind: "class" | "interface" | "enum";
         name: string;

package/dist/agents/mastra/swarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../../../src/agents/mastra/swarm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../../../src/agents/mastra/swarm.ts"],"names":[],"mappings":"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"}