fix(cycles): classify cycles whose only closing edges are speculative

Cycle detection (codegraph cycles / check --cycles / manifesto noCycles)
previously treated every call edge identically, so a cycle held together
only by a low-confidence dynamic-dispatch guess (dynamic = 1 AND
confidence < 1) was reported the same as one backed entirely by confirmed
static edges. A single fabricated resolver edge could therefore surface
as a "confirmed" architectural cycle and fail CI.

findCycles() now runs Tarjan a second time on the edge set with
speculative edges removed and diffs the two SCC decompositions — any
cycle that only exists in the full run is marked `speculative: true`
instead of `confirmed`. Threads `dynamic` through getCallEdges (both the
SQLite and native/rusqlite paths) so the classifier has the metadata it
needs; the SCC primitive itself (JS and native) is unchanged and reused
for both passes, so no engine can diverge on the classification.

`codegraph cycles` gains `--exclude-speculative` and annotates
speculative cycles in table/JSON output. `check --cycles` and the
manifesto `noCycles` rule ignore speculative-only cycles by default via
the new `check.excludeSpeculativeCycles` config default.

Author: carlos-alm

crates/codegraph-core/src/db/repository/graph_read.rs

@@ -1682,12 +1682,16 @@ impl NativeDatabase {
     }
 
     /// Get all 'calls' edges.
+    ///
+    /// Includes `dynamic` alongside `confidence` so consumers (e.g. cycle
+    /// detection, #1844) can distinguish confirmed static calls from
+    /// low-confidence dynamic-dispatch guesses.
     #[napi]
     pub fn get_call_edges(&self) -> napi::Result<Vec<NativeCallEdgeRow>> {
         let conn = self.conn()?;
         let mut stmt = conn
             .prepare_cached(
-                "SELECT source_id, target_id, confidence FROM edges WHERE kind = 'calls' \
+                "SELECT source_id, target_id, confidence, dynamic FROM edges WHERE kind = 'calls' \
                  ORDER BY source_id, target_id",
             )
             .map_err(|e| napi::Error::from_reason(format!("get_call_edges prepare: {e}")))?;
@@ -1697,6 +1701,7 @@ impl NativeDatabase {
                     source_id: row.get("source_id")?,
                     target_id: row.get("target_id")?,
                     confidence: row.get("confidence")?,
+                    dynamic: row.get("dynamic")?,
                 })
             })
             .map_err(|e| napi::Error::from_reason(format!("get_call_edges: {e}")))?;

crates/codegraph-core/src/db/repository/read_types.rs

@@ -145,6 +145,11 @@ pub struct NativeCallEdgeRow {
     pub source_id: i32,
     pub target_id: i32,
     pub confidence: Option<f64>,
+    /// 0 or 1 — flags calls resolved via dynamic dispatch (vs. a direct
+    /// static reference). Paired with `confidence` lets consumers (e.g.
+    /// cycle detection, #1844) distinguish confirmed calls from
+    /// low-confidence dynamic-dispatch guesses.
+    pub dynamic: u32,
 }
 
 /// File node row — mirrors `FileNodeRow`.

docs/examples/CLI.md

@@ -492,6 +492,14 @@ Found 1 file-level cycle:
     src/parser.js -> src/constants.js -> src/parser.js
 ```
 
+Cycles whose only closing edge is a low-confidence dynamic call (resolved via
+a resolver heuristic rather than confirmed statically) are marked
+`[speculative]` rather than reported as confirmed structural cycles. Pass
+`--exclude-speculative` to drop them from the output entirely, or `--json` to
+get a `speculative: boolean` field per cycle. `codegraph check --cycles` and
+the manifesto `noCycles` rule ignore speculative-only cycles by default (see
+`check.excludeSpeculativeCycles` in [configuration](../guides/configuration.md)).
+
 ---
 
 ## export — Graph as DOT, Mermaid, JSON, GraphML, GraphSON, or Neo4j CSV

docs/guides/configuration.md

@@ -315,6 +315,7 @@ Toggles for the lightweight `codegraph check` command (separate from manifesto).
 | Key | Type | Default | Purpose |
 |-----|------|---------|---------|
 | `cycles` | `boolean` | `true` | Fail if cycles exist. |
+| `excludeSpeculativeCycles` | `boolean` | `true` | Don't fail on cycles whose only closing edges are low-confidence dynamic calls (`dynamic = 1 AND confidence < 1`) — resolver guesses rather than confirmed structural dependencies. Also honored by the manifesto `noCycles` rule. |
 | `blastRadius` | `number \| null` | `null` | Fail if any function's caller count exceeds this. |
 | `signatures` | `boolean` | `true` | Warn on signature changes in the diff. |
 | `boundaries` | `boolean` | `true` | Honor the `manifesto.boundaries` rules. |

src/cli/commands/cycles.ts

@@ -1,3 +1,4 @@
+import type { Cycle } from '../../domain/graph/cycles.js';
 import { findCycles, formatCycles } from '../../domain/graph/cycles.js';
 import { openGraph } from '../shared/open-graph.js';
 import type { CommandDefinition } from '../types.js';
@@ -10,15 +11,20 @@ export const command: CommandDefinition = {
     ['--functions', 'Function-level cycle detection'],
     ['-T, --no-tests', 'Exclude test/spec files'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    [
+      '--exclude-speculative',
+      'Exclude cycles whose only closing edges are low-confidence dynamic calls',
+    ],
     ['-j, --json', 'Output as JSON'],
   ],
   execute(_args, opts, ctx) {
     const { db, close } = openGraph(opts as { db?: string });
-    let cycles: string[][];
+    let cycles: Cycle[];
     try {
       cycles = findCycles(db, {
         fileLevel: !opts.functions,
         noTests: ctx.resolveNoTests(opts),
+        excludeSpeculative: Boolean(opts.excludeSpeculative),
       });
     } finally {
       close();

src/db/repository/graph-read.ts

@@ -36,12 +36,16 @@ export function getCallableNodes(db: BetterSqlite3Database): CallableNodeRow[] {
 
 /**
  * Get all 'calls' edges. Ordered for determinism — see `getCallableNodes`.
+ *
+ * Includes `dynamic` alongside `confidence` so consumers (e.g. cycle
+ * detection, #1844) can distinguish confirmed static calls from low-
+ * confidence dynamic-dispatch guesses.
  */
 export function getCallEdges(db: BetterSqlite3Database): CallEdgeRow[] {
   return cachedStmt(
     _getCallEdgesStmt,
     db,
-    "SELECT source_id, target_id, confidence FROM edges WHERE kind = 'calls' ORDER BY source_id, target_id",
+    "SELECT source_id, target_id, confidence, dynamic FROM edges WHERE kind = 'calls' ORDER BY source_id, target_id",
   ).all();
 }
 

src/db/repository/in-memory-repository.ts

@@ -574,7 +574,12 @@ export class InMemoryRepository extends Repository {
   getCallEdges(): CallEdgeRow[] {
     return [...this.#edges.values()]
       .filter((e) => e.kind === 'calls')
-      .map((e) => ({ source_id: e.source_id, target_id: e.target_id, confidence: e.confidence }));
+      .map((e) => ({
+        source_id: e.source_id,
+        target_id: e.target_id,
+        confidence: e.confidence,
+        dynamic: e.dynamic,
+      }));
   }
 
   getFileNodesAll(): FileNodeRow[] {

src/db/repository/native-repository.ts

@@ -143,6 +143,7 @@ function toCallEdgeRow(r: NativeCallEdgeRow): CallEdgeRow {
     source_id: r.sourceId,
     target_id: r.targetId,
     confidence: r.confidence,
+    dynamic: r.dynamic,
   };
 }
 

src/domain/graph/cycles.ts

@@ -3,27 +3,66 @@ import { loadNative } from '../../infrastructure/native.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import type { BetterSqlite3Database } from '../../types.js';
 
-type Edge = { source: string; target: string };
-type DbEdge = { source_id: number; target_id: number };
+type Edge = { source: string; target: string; speculative?: boolean };
+type DbEdge = {
+  source_id: number;
+  target_id: number;
+  confidence?: number | null;
+  dynamic?: 0 | 1;
+};
+
+/**
+ * A detected circular dependency, classified by how solid its evidence is.
+ */
+export interface Cycle {
+  /** Node labels forming the cycle (file paths for file-level, `name|file` for function-level). */
+  nodes: string[];
+  /**
+   * True when every edge that closes this cycle is a low-confidence dynamic
+   * resolution (`dynamic = 1 AND confidence < 1`) — i.e. the cycle
+   * disappears once those resolver guesses are excluded from the graph, so
+   * it has no confirmed structural basis. See issue #1844.
+   */
+  speculative: boolean;
+}
+
+/**
+ * An edge only counts as a low-confidence dynamic guess — not confirmed
+ * structural evidence — when it's flagged dynamic *and* the resolver wasn't
+ * fully confident about it. `confidence == null` is treated as confirmed
+ * (unknown, not guessed) so a missing value never manufactures a false
+ * "speculative" classification.
+ */
+function isSpeculative(e: DbEdge): boolean {
+  return e.dynamic === 1 && typeof e.confidence === 'number' && e.confidence < 1;
+}
 
 /**
  * Build a label-based edge list from DB rows, filtering to known nodes and
  * deduplicating. Self-loops are skipped (Tarjan treats them as trivial SCCs).
+ *
+ * When multiple DB edges collapse onto the same (source, target) label pair,
+ * the pair is only marked `speculative` if *every* underlying edge is — one
+ * confirmed edge between two nodes is enough to make that connection real,
+ * even if a separate low-confidence dynamic call also happens to link them.
  */
 function buildLabelEdges(dbEdges: DbEdge[], idToLabel: Map<number, string>): Edge[] {
-  const edges: Edge[] = [];
-  const seen = new Set<string>();
+  const byPair = new Map<string, Edge>();
   for (const e of dbEdges) {
     if (e.source_id === e.target_id) continue;
     const src = idToLabel.get(e.source_id);
     const tgt = idToLabel.get(e.target_id);
     if (src === undefined || tgt === undefined) continue;
     const key = `${src}\0${tgt}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    edges.push({ source: src, target: tgt });
+    const speculative = isSpeculative(e);
+    const existing = byPair.get(key);
+    if (!existing) {
+      byPair.set(key, { source: src, target: tgt, speculative });
+    } else if (existing.speculative && !speculative) {
+      existing.speculative = false;
+    }
   }
-  return edges;
+  return [...byPair.values()];
 }
 
 function buildFileLevelEdges(db: BetterSqlite3Database, noTests: boolean): Edge[] {
@@ -42,26 +81,68 @@ function buildCallableEdges(db: BetterSqlite3Database, noTests: boolean): Edge[]
   return buildLabelEdges(getCallEdges(db), idToLabel);
 }
 
+/** Run Tarjan's SCC (native when available, JS fallback otherwise) on a flat edge list. */
+function runTarjan(edges: Edge[]): string[][] {
+  const native = loadNative();
+  if (native) {
+    return native.detectCycles(edges) as string[][];
+  }
+  return tarjanFromEdges(edges);
+}
+
+/** Canonical, order-independent key for an SCC's node set. */
+function sccKey(nodes: string[]): string {
+  return [...nodes].sort().join('\0');
+}
+
+/**
+ * Classify each cycle found in `edges` as confirmed or speculative.
+ *
+ * Runs Tarjan once on the full edge set (current behavior), then — only if
+ * at least one edge is speculative — runs it again on the edges that remain
+ * once low-confidence dynamic edges are removed. Removing edges can only
+ * shrink or split SCCs, never grow them, so any full-graph cycle whose exact
+ * node set doesn't reappear in the filtered run depended on a speculative
+ * edge to close it.
+ */
+function classifyCycles(edges: Edge[]): Cycle[] {
+  const allCycles = runTarjan(edges);
+  if (allCycles.length === 0) return [];
+
+  if (!edges.some((e) => e.speculative)) {
+    return allCycles.map((nodes) => ({ nodes, speculative: false }));
+  }
+
+  const confirmedEdges = edges.filter((e) => !e.speculative);
+  const confirmedCycles = runTarjan(confirmedEdges);
+  const confirmedKeys = new Set(confirmedCycles.map(sccKey));
+
+  return allCycles.map((nodes) => ({
+    nodes,
+    speculative: !confirmedKeys.has(sccKey(nodes)),
+  }));
+}
+
 /**
  * Find cycles using Tarjan's SCC algorithm.
  *
  * Builds a label-based adjacency list directly from DB rows — no intermediate
  * CodeGraph construction. This is O(V + E) with minimal memory overhead.
+ *
+ * By default returns every detected cycle, each flagged `speculative` when
+ * its only structural basis is a low-confidence dynamic edge. Pass
+ * `excludeSpeculative: true` to drop those from the result entirely.
  */
 export function findCycles(
   db: BetterSqlite3Database,
-  opts: { fileLevel?: boolean; noTests?: boolean } = {},
-): string[][] {
+  opts: { fileLevel?: boolean; noTests?: boolean; excludeSpeculative?: boolean } = {},
+): Cycle[] {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
 
   const edges = fileLevel ? buildFileLevelEdges(db, noTests) : buildCallableEdges(db, noTests);
-
-  const native = loadNative();
-  if (native) {
-    return native.detectCycles(edges) as string[][];
-  }
-  return tarjanFromEdges(edges);
+  const cycles = classifyCycles(edges);
+  return opts.excludeSpeculative ? cycles.filter((c) => !c.speculative) : cycles;
 }
 
 export function findCyclesJS(edges: Edge[]): string[][] {
@@ -136,19 +217,22 @@ function tarjanFromEdges(edges: Edge[]): string[][] {
   return sccs;
 }
 
-export function formatCycles(cycles: string[][]): string {
+export function formatCycles(cycles: Cycle[]): string {
   if (cycles.length === 0) {
     return 'No circular dependencies detected.';
   }
 
   const lines: string[] = [`Found ${cycles.length} circular dependency cycle(s):\n`];
   for (let i = 0; i < cycles.length; i++) {
-    const cycle = cycles[i]!;
-    lines.push(`  Cycle ${i + 1} (${cycle.length} files):`);
-    for (const file of cycle) {
+    const { nodes, speculative } = cycles[i]!;
+    const tag = speculative
+      ? '  [speculative — only closes via a low-confidence dynamic call]'
+      : '';
+    lines.push(`  Cycle ${i + 1} (${nodes.length} files):${tag}`);
+    for (const file of nodes) {
       lines.push(`    -> ${file}`);
     }
-    lines.push(`    -> ${cycle[0]} (back to start)`);
+    lines.push(`    -> ${nodes[0]} (back to start)`);
     lines.push('');
   }
   return lines.join('\n');

src/features/check.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { findDbPath, openReadonlyOrFail } from '../db/index.js';
 import { bfsTransitiveCallers } from '../domain/analysis/impact.js';
+import type { Cycle } from '../domain/graph/cycles.js';
 import { findCycles } from '../domain/graph/cycles.js';
 import { DEFAULTS, loadConfig } from '../infrastructure/config.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
@@ -317,16 +318,17 @@ export function parseDiffOutput(diffOutput: string): ParsedDiff {
 
 interface CyclesResult {
   passed: boolean;
-  cycles: string[][];
+  cycles: Cycle[];
 }
 
 export function checkNoNewCycles(
   db: BetterSqlite3Database,
   changedFiles: Set<string>,
   noTests: boolean,
+  excludeSpeculative: boolean,
 ): CyclesResult {
-  const cycles = findCycles(db, { fileLevel: true, noTests });
-  const involved = cycles.filter((cycle) => cycle.some((f) => changedFiles.has(f)));
+  const cycles = findCycles(db, { fileLevel: true, noTests, excludeSpeculative });
+  const involved = cycles.filter((cycle) => cycle.nodes.some((f) => changedFiles.has(f)));
   return { passed: involved.length === 0, cycles: involved };
 }
 
@@ -797,6 +799,8 @@ function resolveCheckFlags(opts: CheckOpts, config: CodegraphConfig) {
   const checkConfig = config.check || ({} as CodegraphConfig['check']);
   return {
     enableCycles: opts.cycles ?? checkConfig.cycles ?? true,
+    excludeSpeculativeCycles:
+      checkConfig.excludeSpeculativeCycles ?? DEFAULTS.check.excludeSpeculativeCycles,
     enableSignatures: opts.signatures ?? checkConfig.signatures ?? true,
     enableBoundaries: opts.boundaries ?? checkConfig.boundaries ?? true,
     blastRadiusThreshold: opts.blastRadius ?? checkConfig.blastRadius ?? null,
@@ -816,7 +820,10 @@ function runPredicates(
   const predicates: PredicateResult[] = [];
 
   if (flags.enableCycles) {
-    predicates.push({ name: 'cycles', ...checkNoNewCycles(db, changedFiles, noTests) });
+    predicates.push({
+      name: 'cycles',
+      ...checkNoNewCycles(db, changedFiles, noTests, flags.excludeSpeculativeCycles),
+    });
   }
   if (flags.blastRadiusThreshold != null) {
     predicates.push({