kenaz 0.0.0-stage → 0.3.2

package/core/dev/archive/ansuz/investigations/synapse_orphans_indexing_bug_2026-04-11.md

@@ -0,0 +1,352 @@
+# synapse_orphans Indexing Bug Investigation — 2026-04-11
+
+**Task**: TASK_1173  
+**Date**: 2026-04-11  
+**Analyst**: unit agent (backend specialist)  
+**Input**: TASK_1172 verification report — 24/30 false positives confirmed  
+**Scope**: dashboard/src-tauri/src/features/synapse (scanner.rs, calls.rs, imports.rs, index.rs)
+
+---
+
+## Input data (from TASK_1172)
+
+TASK_1172 ran `synapse_orphans(min_age_days=30, limit=50)` and grep-verified 30 in-scope candidates:
+
+- **24/30 FALSE_POSITIVE** — live callers confirmed by grep
+- **5/30 CONFIRMED_ORPHAN** — deleted
+- **1/30 AMBIGUOUS** — retained
+
+Key false-positive groups (with confirmed callers):
+
+| Symbol | File | Caller | Caller location |
+|--------|------|--------|-----------------|
+| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | dispatch.js | line 338 |
+| `isCacheStale` | `.formation/tools/remote-conflict.js` | dispatch.js | line 331 |
+| `checkLinks` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 274 |
+| `rebuildIndex` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 196 |
+| `syncToRag` | `.kenaz/docs/tools/src/registry.ts` | cli.ts | line 250 |
+| `main` (×7) | various .memory/tools and .formation/tools | self-invoked at module scope | tail of each file |
+| `constructor` (×4) | registry.ts, search.ts, field-extractor.ts, token-optimizer.js | `new ClassName()` at call sites | various lines |
+
+---
+
+## Graph state queries
+
+### Query 1 — CALLS edges to hasRemoteFileConflict and isCacheStale
+
+```cypher
+MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'hasRemoteFileConflict'})
+RETURN caller.file_path, caller.name, count(r)
+```
+**Result**: 0 rows
+
+```cypher
+MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'isCacheStale'})
+RETURN caller.file_path, caller.name, count(r)
+```
+**Result**: 0 rows
+
+```cypher
+MATCH (caller:Symbol)-[r:CALLS]->(callee:Symbol {name:'checkLinks'})
+RETURN caller.file_path, caller.name, count(r)
+```
+**Result**: 0 rows
+
+### Query 2 — Caller files in the File table
+
+```cypher
+MATCH (f:File) WHERE f.path CONTAINS 'dispatch.js' OR f.path CONTAINS 'cli.ts'
+RETURN f.path, f.name
+```
+**Result**: BOTH files present:
+- `.kenaz/docs/tools/src/cli.ts`
+- `.formation/tools/dispatch.js`
+
+**Interpretation**: Caller files ARE indexed — this rules out Hypothesis A (files never indexed).
+
+### Query 3 — Symbols defined in caller files
+
+```cypher
+MATCH (f:File {path:'.formation/tools/dispatch.js'})-[:DEFINES]->(s:Symbol)
+RETURN s.name, s.kind, s.start_line ORDER BY s.start_line
+```
+**Result**: 14 symbols — `getSupabaseClient`, `getTaskSync`, `getCommitSync`, `syncCommit`, `broadcastStatus`, `readActiveDispatches`, `writeActiveDispatches`, `registerDispatch`, `unregisterDispatch`, `buildCortexContext`, `checkDependencies`, `dispatch`, `handleDryRun`, `execute`
+
+```cypher
+MATCH (f:File {path:'.kenaz/docs/tools/src/cli.ts'})-[:DEFINES]->(s:Symbol)
+RETURN s.name, s.kind, s.start_line ORDER BY s.start_line
+```
+**Result**: **0 rows** — cli.ts has NO symbols in the graph.
+
+**Interpretation**: Two distinct failure modes:
+- dispatch.js: Phase 2 succeeded (14 symbols) but Phase 3 failed (0 CALLS, 0 IMPORTS)
+- cli.ts: Phase 2 failed entirely (0 symbols extracted)
+
+### Query 4 — IMPORTS edges from dispatch.js
+
+```cypher
+MATCH (f:File {path:'.formation/tools/dispatch.js'})-[r:IMPORTS]->(g:File)
+RETURN g.path, r.imported_symbols, r.confidence
+```
+**Result**: 0 rows. No IMPORTS edges for dispatch.js.
+
+Compare: `run-round2.js`, `legacy-scheduler.js`, `muninn.js`, etc. all have IMPORTS edges.
+
+### Query 5 — Any outgoing CALLS from dispatch.js
+
+```cypher
+MATCH (s:Symbol {file_path:'.formation/tools/dispatch.js'})-[r:CALLS]->(t:Symbol)
+RETURN s.name, t.name, t.file_path, r.call_line LIMIT 10
+```
+**Result**: **0 rows** — no CALLS from ANY dispatch.js symbol, including same-file calls (e.g., `dispatch → checkDependencies`, `execute → registerDispatch`).
+
+### Query 6 — Callee symbol uniqueness
+
+```cypher
+MATCH (s:Symbol {name:'isCacheStale'}) RETURN s.id, s.file_path, s.kind
+MATCH (s:Symbol {name:'hasRemoteFileConflict'}) RETURN s.id, s.file_path, s.kind
+```
+**Result**: Both symbols are globally unique (1 candidate each in symbol_index).
+
+**Interpretation**: The `unique_name` fallback strategy (confidence 0.75) in `find_callee_from_imports` should have matched these symbols. The fact that it didn't confirms Phase 3 was never run for dispatch.js — not that resolution failed.
+
+### Query 7 — CALLS edge coverage across .formation/tools
+
+```cypher
+MATCH (s:Symbol)-[r:CALLS]->(t:Symbol)
+WHERE s.file_path STARTS WITH '.formation/tools/'
+RETURN s.file_path, count(r) AS call_count ORDER BY call_count DESC LIMIT 10
+```
+**Result**: prompt.js (532), loop.js (187), legacy-scheduler.js (171), muninn-watcher.js (127) … **dispatch.js absent** (0 edges).
+
+---
+
+## Hypothesis 1
+
+**cli.ts has zero symbols — Commander-pattern CLI files are invisible to Phase 2**
+
+**Evidence**:
+- cli.ts shows 0 DEFINES edges (Query 3)
+- cli.ts content starts with `#!/usr/bin/env node` and uses the Commander.js pattern:
+  ```ts
+  import { Command } from 'commander';
+  const program = new Command();
+  program.command('search <query>').action((query, options) => { ... });
+  ```
+- There are NO top-level `function` declarations or `const foo = () => {}` arrow functions at declaration level. All handlers are inline anonymous callbacks passed to `.action()`.
+- `collect_ts_calls_recursive` in `calls.rs` only tracks calls made **inside named function/method/arrow-function declarations**. Anonymous callbacks in argument position are recursed into but their enclosing scope is the *outer* function — in cli.ts's case, there is no outer named function.
+- `symbols::extract_symbols` in `symbols.rs` extracts `function_declaration`, `method_definition`, and `variable_declarator` with function value — it does NOT extract anonymous callbacks inside method call chains.
+
+**Test to confirm**: Run `synapse_search({ query: "cli kenaz docs command search", file_filter: "cli.ts" })` — no results = confirmed zero symbols.
+
+**Impact**: ALL callers of registry.ts methods originate in cli.ts (`checkLinks`, `rebuildIndex`, `syncToRag`, `validate`, `stats`, `searchWithScores`, `listSystems`). Since cli.ts has 0 symbols, no CALLS edges from cli.ts can ever exist regardless of how well Phase 3 runs.
+
+**Fix scope**: `symbols.rs` symbol extractor needs to detect CLI script entry patterns (`program.command().action(handler)`) and either: (a) synthesize a virtual caller symbol per command, or (b) registry.ts methods should not be flagged as orphans if their file has a corresponding `.cli.ts` caller file.
+
+---
+
+## Hypothesis 2
+
+**Module-scope call expressions silently dropped by calls.rs**
+
+**Evidence**:
+- `calls.rs:335-345` (confirmed via code read):
+  ```rust
+  if let Some((caller_name, caller_line)) = enclosing_func {
+      if !is_ts_builtin(&simple_name) {
+          calls.push(CallInfo { ... });
+      }
+  }
+  // No else — module-scope calls silently discarded
+  ```
+- `collect_ts_calls_recursive` is called with `enclosing_func = None` for the top-level program node. Call expressions encountered at file scope (outside any function body) hit this guard and are **never pushed to the calls Vec**.
+- Confirmed false positives caused by this:
+  - `main()` at end of file (7 occurrences): `memory-tools.js:475`, `migrate-failures.js` tail, `security-filter.js:419`, `token-optimizer.js:387`, `cleanup-duplicates.js` tail, `rebuild-registry.js:96`, `run-round2.js` tail
+  - `getArg('--skill')` at module scope in `run-round2.js:24`
+  - `rebuildRegistry()` at module scope in `rebuild-registry.js:96`
+
+**Test to confirm**:
+```bash
+grep -n "^main\(\|^main().catch\|^\s*main()" .formation/tools/run-round2.js
+```
+Line found at module scope → no enclosing_func → no CallInfo → no CALLS edge → `main` appears as orphan.
+
+**Fix scope**: `calls.rs:335` — add `else` branch to push CallInfo with synthetic caller (`"<module>"`, `caller_start_line = 0`) for module-scope calls. Then `resolve_phase3` would need to either skip these (no symbol match) or create a module-level pseudo-symbol.
+
+**Simpler fix**: In `synapse_orphans`, additionally check whether the symbol IS called at module scope via a separate grep-style scan, or filter out symbols whose name is `main` and whose file has a `require.main === module` guard.
+
+---
+
+## Hypothesis 3
+
+**Destructured CommonJS require breaks import_map strategy, contributing to Phase 3 staleness for dispatch.js**
+
+**Evidence**:
+- `imports.rs:359-409` — `extract_ts_require` reads the variable name with `child_by_field_name("name")`:
+  ```rust
+  let name = child
+      .child_by_field_name("name")
+      .and_then(|n| n.utf8_text(source_bytes).ok())
+      .unwrap_or("")
+      .to_string();
+  // imported_symbols = vec![name]
+  ```
+- For destructured require `const { refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale } = require('./remote-conflict')`, the `name` field of `variable_declarator` is an `object_pattern` node. `utf8_text()` on that node returns the raw text `{ refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale }` as a SINGLE string.
+- Result: `imported_symbols = ["{ refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale }"]` — one string with braces, not four separate names.
+- In `find_callee_from_imports` (scanner.rs:1901-1910):
+  ```rust
+  if imp.imported_symbols.contains(&simple_name.to_string()) {
+  ```
+  `simple_name = "hasRemoteFileConflict"` → `.contains()` fails → import_map strategy misses.
+- Fallback to `unique_name` (strategy 2): should still work for unique symbols, BUT dispatch.js has 0 CALLS edges even for **same-file** symbols (see Query 5). This means the destructured require bug alone is not the only cause.
+
+**dispatch.js Phase 3 staleness — auxiliary finding**:
+- dispatch.js has 14 symbols (Phase 2 ran), 0 IMPORTS, 0 CALLS (including same-file calls like `dispatch → checkDependencies` at line 252, `execute → registerDispatch` at line 445).
+- Same-file calls use Strategy 1 (`same_file`, confidence 0.90) which operates on `fd.extracted_symbols` — it does NOT depend on imports at all.
+- Conclusion: Phase 3 was **never run for dispatch.js**. The most likely cause: dispatch.js was first indexed in a full index pass that predated the addition of `.formation/tools/remote-conflict.js`. Incremental index only re-processes changed files. Since dispatch.js's content has not changed since that full index, it has been skipped on every subsequent run — its Phase 3 edges were never built.
+- This is a general **incremental index blindspot**: files that existed at full-index time with no subsequent changes never get Phase 3 re-run when *their dependencies* are added/modified.
+
+**Test to confirm destructured require bug**:
+```cypher
+MATCH (f:File {path:'.formation/tools/dispatch.js'})-[r:IMPORTS]->(g:File)
+RETURN g.path, r.imported_symbols
+```
+Expected if bug present: 0 rows (confirmed already). Expected after fix: rows with individual symbol names.
+
+**Fix scope**: `imports.rs:extract_ts_require` — detect when `name` node is `object_pattern`, then iterate its `shorthand_property_identifier_pattern` children to build individual symbol names instead of raw text.
+
+---
+
+## Hypothesis 4
+
+**Constructor calls not tracked — `new ClassName()` not modeled as CALLS to constructor**
+
+**Evidence**:
+- `calls.rs` `collect_ts_calls_recursive` matches `"call_expression"` nodes. However, class instantiation uses `new_expression` nodes in tree-sitter-javascript/typescript, not `call_expression`.
+- tree-sitter-javascript AST for `new DocsRegistry(config)`:
+  ```
+  new_expression
+    constructor: (identifier) "DocsRegistry"
+    arguments: (arguments ...)
+  ```
+- The `collect_ts_calls_recursive` `_ => {}` fallback recurses into `new_expression` children, but there is no arm for `"new_expression"` → the constructor identifier is never treated as a callee.
+- Result: 4 constructor symbols appear as orphans: `constructor` in registry.ts, search.ts, field-extractor.ts, token-optimizer.js.
+
+**Test to confirm**:
+```bash
+grep -rn "new DocsRegistry\|new SearchEngine\|new FieldExtractor" .kenaz/docs/tools/src/
+```
+All found in registry.ts → confirmed live callers exist.
+
+**Fix scope**: `calls.rs:collect_ts_calls_recursive` — add `"new_expression"` arm that extracts the `constructor` field as callee (similar to `call_expression`), treating it as a call to the class's `constructor` method. Alternatively, match `new ClassName()` as a call to `ClassName` (the class itself).
+
+---
+
+## Root cause
+
+Root cause: Multiple independent indexing gaps in calls.rs, imports.rs, and symbol extractor — not a single bug.
+
+**Details — multiple independent gaps:**
+
+| Root cause | Affected symbols | Fix complexity |
+|------------|-----------------|----------------|
+| **cli.ts zero symbols** (Commander pattern — no top-level named functions) | checkLinks, rebuildIndex, syncToRag, validate, stats, searchWithScores, listSystems (7 symbols) | Medium — need Commander-aware symbol extraction or orphan filter |
+| **Module-scope call dropping** (calls.rs:335 guard drops calls without enclosing function) | main (×7), getArg, rebuildRegistry (9+ symbols) | Small — add synthetic `<module>` caller or filter main/cli patterns in orphan tool |
+| **Destructured require breaks import_map** (imports.rs reads object_pattern as raw text) | dispatch.js cross-file callee resolution (affects import_map only; unique_name still works for unique symbols) | Small — 10 LOC fix in extract_ts_require |
+| **Phase 3 never ran for dispatch.js** (incremental blindspot: file unchanged since before remote-conflict.js was added) | hasRemoteFileConflict, isCacheStale, hasRemoteConflict, refreshCache | Requires forced re-index of dispatch.js or full re-index |
+| **new_expression not tracked** (constructor calls use different AST node) | constructor (×4) | Small — add new_expression arm in calls.rs |
+
+**Primary false positive source** (by count): module-scope call dropping (9+) and cli.ts zero symbols (7).
+**Most load-bearing fix**: module-scope call dropping — affects ANY CLI-style script that calls main() or helpers at file scope.
+
+---
+
+## Proposed fix
+
+### Fix 1 — imports.rs: destructured require (≤15 LOC, trivial)
+
+In `extract_ts_require` (imports.rs:366-370), replace raw text extraction with object_pattern child parsing:
+
+```rust
+let imported_symbols = if child
+    .child_by_field_name("name")
+    .map(|n| n.kind() == "object_pattern")
+    .unwrap_or(false)
+{
+    // Destructured: const { X, Y } = require(...)
+    // Walk object_pattern children for shorthand_property_identifier_pattern
+    let mut symbols = vec![];
+    if let Some(pattern) = child.child_by_field_name("name") {
+        let mut c = pattern.walk();
+        for prop in pattern.children(&mut c) {
+            if prop.kind() == "shorthand_property_identifier_pattern" {
+                if let Ok(name) = prop.utf8_text(source_bytes) {
+                    symbols.push(name.to_string());
+                }
+            }
+        }
+    }
+    symbols
+} else {
+    // Simple: const X = require(...)
+    let name = child.child_by_field_name("name")
+        .and_then(|n| n.utf8_text(source_bytes).ok())
+        .unwrap_or("")
+        .to_string();
+    if name.is_empty() { vec![] } else { vec![name] }
+};
+```
+
+### Fix 2 — calls.rs: new_expression tracking (≤20 LOC, trivial)
+
+In `collect_ts_calls_recursive`, add a `"new_expression"` arm after `"call_expression"`:
+
+```rust
+"new_expression" => {
+    if let Some(ctor_node) = child.child_by_field_name("constructor") {
+        let callee = ctor_node.utf8_text(source_bytes).unwrap_or("").to_string();
+        let simple_name = extract_simple_name(&callee);
+        let line = child.start_position().row + 1;
+        if let Some((caller_name, caller_line)) = enclosing_func {
+            if !is_ts_builtin(&simple_name) {
+                calls.push(CallInfo {
+                    callee_name: callee,
+                    callee_simple_name: simple_name,
+                    line,
+                    caller_name: caller_name.to_string(),
+                    caller_start_line: caller_line,
+                });
+            }
+        }
+    }
+    collect_ts_calls_recursive(&child, source_bytes, calls, enclosing_func, depth + 1);
+}
+```
+
+### Fix 3 — Module-scope call tracking (medium, requires design decision)
+
+Option A: Add synthetic `<module>` caller in calls.rs (pushes CallInfo with `caller_name = "<module>"`, `caller_start_line = 0`). Then in resolve_phase3, treat `<module>` caller as a special File-level edge rather than a Symbol-to-Symbol CALLS edge. This requires schema/logic changes.
+
+Option B: Filter `main` and other CLI entry patterns in `synapse_orphans` itself — functions named `main` that are the last expression in a file, or functions with `require.main === module` guard, should be excluded from orphan candidates. This is a heuristic filter, not a graph fix.
+
+Option C: Track module-scope calls as CALLS edges originating from a synthetic `<module_scope>` symbol per file. Add this to Phase 2 as well.
+
+**Recommendation**: Option B for immediate fix (< 5 LOC in lib.rs orphans function), Option A/C for completeness.
+
+### Fix 4 — Forced re-index of dispatch.js
+
+Touching dispatch.js (even adding a comment) will trigger incremental re-index → Phase 3 will run → CALLS edges for `hasRemoteFileConflict`, `isCacheStale` will be created after Fix 1. Not a code fix but an operational remediation.
+
+### Fix 5 — cli.ts symbol extraction (complex, deferred)
+
+Commander-pattern CLI files require either:
+- A new extractor that synthesizes named symbols for each `.command('name').action()` block
+- OR an exclusion in synapse_orphans for symbols in files that have a CLI caller (presence of `cli.ts` or `cli.js` sibling in same directory)
+
+**Recommendation**: Deferred. Document the pattern in synapse_orphans tool description.
+
+---
+
+**Status of proposed fixes**: Fix 1 and Fix 2 are trivial (< 30 LOC combined, well within inline patch threshold). Fix 3 Option B is trivial. They constitute the complete patch for this bug.
+
+status: fix_task_proposed

package/core/dev/archive/ansuz/investigations/synapse_orphans_reindex_verification_2026-04-11.md

@@ -0,0 +1,48 @@
+# Synapse Orphans Re-index Verification — 2026-04-11
+
+**Task**: TASK_1177  
+**Dependency**: TASK_1174 (imports.rs destructured require fix) — confirmed DONE  
+**Date**: 2026-04-11  
+**Operator**: unit (Formation agent)
+
+---
+
+## Before
+
+Snapshot taken before forced full re-index. Source: `synapse_orphans(min_age_days=30)` + `synapse_context` per symbol.
+
+| Symbol | File | Callers (BEFORE) | In orphans(min_age_days=30)? |
+|--------|------|-----------------|------------------------------|
+| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 0 | No (EXPORTS edge from module.exports) |
+| `isCacheStale` | `.formation/tools/remote-conflict.js` | 0 | No (EXPORTS edge from module.exports) |
+| `hasRemoteConflict` | `.formation/tools/remote-conflict.js` | 2 (legacy-scheduler.js only) | No (has callers) |
+| `refreshCache` | `.formation/tools/remote-conflict.js` | 1 (legacy-scheduler.js only) | No (has callers) |
+
+**Interpretation**: The four symbols were NOT surfaced as orphans because `remote-conflict.js` exports them via `module.exports`, giving them EXPORTS edges that excluded them from orphan detection. However, `hasRemoteFileConflict` and `isCacheStale` had **0 callers** — confirming the Phase 3 CALLS/IMPORTS edge build never ran for `dispatch.js`. The destructured require at `dispatch.js:21` was present in code but not recognized by the pre-TASK_1174 parser.
+
+**Re-index method used**: `POST /api/synapse/index` with `force: true` — triggered a full re-index (bypassing Layer 2 SHA1 hash check). The incremental `synapse_index` MCP call returned "No changes detected" as expected (SHA1 unchanged since dispatch.js content was correct but un-re-parsed).
+
+---
+
+## After
+
+Snapshot taken after full re-index completed (relationships stabilized at 23,670, symbol_entries at 21,751).
+
+| Symbol | File | Callers (AFTER) | Caller from dispatch.js? |
+|--------|------|----------------|--------------------------|
+| `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 1 | ✅ Yes (`dispatch` function) |
+| `isCacheStale` | `.formation/tools/remote-conflict.js` | 1 | ✅ Yes (`dispatch` function) |
+| `hasRemoteConflict` | `.formation/tools/remote-conflict.js` | 3 | ✅ Yes (`dispatch` function + legacy-scheduler.js x2) |
+| `refreshCache` | `.formation/tools/remote-conflict.js` | 2 | ✅ Yes (`dispatch` function + legacy-scheduler.js x1) |
+
+**dispatch.js byte-identity**: Confirmed — `git diff --stat .formation/tools/dispatch.js` returned no output (no changes).
+
+---
+
+## Notes
+
+- The `synapse_index` MCP tool (incremental) is insufficient to re-parse dispatch.js when content is unchanged — Layer 2 SHA1 hash check short-circuits Phase 3. A forced full re-index via the HTTP API (`force: true`) was required.
+- TASK_1174's fix to `imports.rs` (destructured require parsing) is confirmed effective: all four symbols now have dispatch.js as a caller.
+- The orphans false-positive framing in TASK_1173 was partially inaccurate: the symbols were never in `orphans(min_age_days=30)` due to EXPORTS edges. The real signal was the missing CALLS edges (0 callers for hasRemoteFileConflict and isCacheStale).
+
+Verdict: all_four_cleared

package/core/dev/archive/ansuz/investigations/synapse_orphans_verification_2026-04-11.md

@@ -0,0 +1,170 @@
+# synapse_orphans Verification Report — 2026-04-11
+
+**Task**: TASK_1172  
+**Date**: 2026-04-11  
+**Snapshot**: synapse_orphans(min_age_days=30, limit=50)  
+**Scope paths**: .kenaz/docs/tools, .memory/tools, .formation/tools/run-round2.js, .formation/tools/remote-conflict.js  
+**Analyst**: unit agent  
+**Paired task**: TASK_1173 (synapse_orphans indexing bug investigation)
+
+---
+
+## Summary
+
+false_positive_rate: 24/30
+
+| Category | Count | Notes |
+|---|---|---|
+| CONFIRMED_ORPHAN | 5 | Zero non-definition callers; safe to delete |
+| FALSE_POSITIVE | 24 | Actual callers found (code, docs, or self-invocation) |
+| AMBIGUOUS | 1 | Exported API, no external callers discovered |
+| **Total in-scope** | **30** | Of 50 returned by synapse_orphans |
+
+**Key finding**: 80% false-positive rate. Root cause appears to be synapse_orphans failing to model: (a) module-scope self-invocation (CLI `main()` calls), (b) class instantiation callers (`new ClassName()`), (c) cross-module require chains. TASK_1173 should investigate these indexing gaps.
+
+---
+
+## Candidates
+
+Full list of in-scope candidates from synapse_orphans snapshot:
+
+| # | Symbol | File | Lines | LOC Impact | Classification |
+|---|---|---|---|---|---|
+| 1 | `checkLinks` | `.kenaz/docs/tools/src/registry.ts` | 594–637 | 44 | FALSE_POSITIVE |
+| 2 | `syncToRag` | `.kenaz/docs/tools/src/registry.ts` | 475–514 | 40 | FALSE_POSITIVE |
+| 3 | `validate` | `.kenaz/docs/tools/src/registry.ts` | 516–551 | 36 | FALSE_POSITIVE |
+| 4 | `rebuildIndex` | `.kenaz/docs/tools/src/registry.ts` | 142–173 | 32 | FALSE_POSITIVE |
+| 5 | `__init__` | `.kenaz/docs/tools/sync_to_rag.py` | 59–81 | 23 | FALSE_POSITIVE |
+| 6 | `stats` | `.kenaz/docs/tools/src/registry.ts` | 553–574 | 22 | FALSE_POSITIVE |
+| 7 | `searchWithScores` | `.kenaz/docs/tools/src/registry.ts` | 106–124 | 19 | FALSE_POSITIVE |
+| 8 | `addSystem` | `.kenaz/docs/tools/src/registry.ts` | 576–584 | 9 | CONFIRMED_ORPHAN |
+| 9 | `removeSystem` | `.kenaz/docs/tools/src/registry.ts` | 586–592 | 7 | CONFIRMED_ORPHAN |
+| 10 | `constructor` | `.kenaz/docs/tools/src/registry.ts` | 37–39 | 3 | FALSE_POSITIVE |
+| 11 | `listSystems` | `.kenaz/docs/tools/src/registry.ts` | 134–136 | 3 | FALSE_POSITIVE |
+| 12 | `main` | `.memory/tools/memory-tools.js` | 376–472 | 97 | FALSE_POSITIVE |
+| 13 | `main` | `.memory/tools/migrate-failures.js` | 263–342 | 80 | FALSE_POSITIVE |
+| 14 | `smartTrim` | `.memory/tools/token-optimizer.js` | 180–246 | 67 | FALSE_POSITIVE |
+| 15 | `main` | `.memory/tools/security-filter.js` | 358–417 | 60 | FALSE_POSITIVE |
+| 16 | `main` | `.memory/tools/token-optimizer.js` | 334–384 | 51 | FALSE_POSITIVE |
+| 17 | `constructor` | `.memory/tools/token-optimizer.js` | 31–36 | 6 | FALSE_POSITIVE |
+| 18 | `hasSensitiveData` | `.memory/tools/security-filter.js` | 352–355 | 4 | AMBIGUOUS |
+| 19 | `main` | `.memory/tools/cleanup-duplicates.js` | 100–144 | 45 | FALSE_POSITIVE |
+| 20 | `rebuildRegistry` | `.memory/tools/rebuild-registry.js` | 65–94 | 30 | FALSE_POSITIVE |
+| 21 | `search` | `.kenaz/docs/tools/src/search.ts` | 32–74 | 43 | FALSE_POSITIVE |
+| 22 | `getSearchStats` | `.kenaz/docs/tools/src/search.ts` | 191–232 | 42 | CONFIRMED_ORPHAN |
+| 23 | `constructor` | `.kenaz/docs/tools/src/field-extractor.ts` | 27–61 | 35 | FALSE_POSITIVE |
+| 24 | `registerSystem` | `.kenaz/docs/tools/src/field-extractor.ts` | 155–157 | 3 | CONFIRMED_ORPHAN |
+| 25 | `getRegisteredSystems` | `.kenaz/docs/tools/src/field-extractor.ts` | 162–164 | 3 | CONFIRMED_ORPHAN |
+| 26 | `constructor` | `.kenaz/docs/tools/src/search.ts` | 24–24 | 1 | FALSE_POSITIVE |
+| 27 | `main` | `.formation/tools/run-round2.js` | 90–116 | 27 | FALSE_POSITIVE |
+| 28 | `getArg` | `.formation/tools/run-round2.js` | 16–22 | 7 | FALSE_POSITIVE |
+| 29 | `hasRemoteFileConflict` | `.formation/tools/remote-conflict.js` | 69–89 | 21 | FALSE_POSITIVE |
+| 30 | `isCacheStale` | `.formation/tools/remote-conflict.js` | 94–96 | 3 | FALSE_POSITIVE |
+
+---
+
+## Confirmed orphans
+
+Five symbols with zero non-definition callers across all file extensions (.js, .ts, .py, .sh, .md, .yaml, .yml, .json, .toml):
+
+### 1. `addSystem` — `.kenaz/docs/tools/src/registry.ts` lines 576–584
+
+```
+grep -rn 'addSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
+```
+Result: Only definition site (registry.ts:576). No callers.  
+**Action**: Deleted.
+
+### 2. `removeSystem` — `.kenaz/docs/tools/src/registry.ts` lines 586–592
+
+```
+grep -rn 'removeSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
+```
+Result: Only definition site (registry.ts:586). No callers.  
+**Action**: Deleted.
+
+### 3. `getSearchStats` — `.kenaz/docs/tools/src/search.ts` lines 191–232
+
+```
+grep -rn 'getSearchStats' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
+```
+Result: Only definition site (search.ts:191). No callers.  
+**Action**: Deleted.
+
+### 4. `registerSystem` — `.kenaz/docs/tools/src/field-extractor.ts` lines 155–157
+
+```
+grep -rn 'registerSystem' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
+```
+Result: Only definition site (field-extractor.ts:155). No callers.  
+**Action**: Deleted.
+
+### 5. `getRegisteredSystems` — `.kenaz/docs/tools/src/field-extractor.ts` lines 162–164
+
+```
+grep -rn 'getRegisteredSystems' --include='*.{js,ts,py,sh,md,yaml,yml,json,toml}' .
+```
+Result: Only definition site (field-extractor.ts:162). No callers.  
+**Action**: Deleted.
+
+---
+
+## False positives
+
+24 symbols reported as orphans by synapse_orphans that have live callers:
+
+| Symbol | File | Caller Evidence |
+|---|---|---|
+| `checkLinks` | registry.ts | `.kenaz/docs/tools/src/cli.ts:274` — `registry.checkLinks()` |
+| `syncToRag` | registry.ts | `.kenaz/docs/tools/src/cli.ts:250` — `registry.syncToRag(!options.force)` |
+| `validate` | registry.ts | `.kenaz/docs/tools/src/cli.ts:201,295` — `registry.validate()` |
+| `rebuildIndex` | registry.ts | `.kenaz/docs/tools/src/cli.ts:196` — `registry.rebuildIndex()` |
+| `stats` | registry.ts | `.kenaz/docs/tools/src/cli.ts:212,321` — `registry.stats()` |
+| `searchWithScores` | registry.ts | `.kenaz/docs/tools/src/cli.ts:31` — `registry.searchWithScores(query, {...})` |
+| `listSystems` | registry.ts | `.kenaz/docs/tools/src/cli.ts:107` — `registry.listSystems()` |
+| `constructor` | registry.ts:37 | `registry.ts:56,61` — `new DocsRegistry(...)` |
+| `__init__` | sync_to_rag.py | `registry.ts:478` spawns script; `RAG_INTEGRATION_GUIDE.md:73` — `DocsSyncManager(Path.cwd())` |
+| `search` | search.ts | `registry.ts:95,122` — `searchEngine.search(query, options)` |
+| `constructor` | search.ts:24 | `registry.ts:95,122` — `new SearchEngine(allDocs)` |
+| `constructor` | field-extractor.ts:27 | `registry.ts:38` — `new FieldExtractor()` |
+| `main` | memory-tools.js | `memory-tools.js:475` — self-invoked at module scope (`main()`) |
+| `main` | migrate-failures.js | `migrate-failures.js` tail — self-invoked (`main()`) |
+| `smartTrim` | token-optimizer.js | `.memory/README.md:263`, `.memory/SECURITY_TOKEN_OPTIMIZATION.md:117` — documented API import; exported |
+| `main` | security-filter.js | `security-filter.js:419-420` — guarded CLI entry (`if (require.main === module) { main(); }`) |
+| `main` | token-optimizer.js | `token-optimizer.js:387` — self-invoked at module scope |
+| `constructor` | token-optimizer.js:31 | class `MemoryCache` instantiated internally |
+| `main` | cleanup-duplicates.js | `cleanup-duplicates.js` tail — self-invoked (`main()`) |
+| `rebuildRegistry` | rebuild-registry.js | `rebuild-registry.js:96` — self-invoked at module scope |
+| `main` | run-round2.js | `run-round2.js` tail — `main().catch(e => { process.exit(1); })` |
+| `getArg` | run-round2.js | `run-round2.js:24` — called at module scope (`getArg('--skill')`) |
+| `hasRemoteFileConflict` | remote-conflict.js | `.formation/tools/dispatch.js:338` — `hasRemoteFileConflict(scopePaths)` |
+| `isCacheStale` | remote-conflict.js | `.formation/tools/dispatch.js:331` — `isCacheStale()` |
+
+**Root causes of false positives:**
+1. **Module-scope self-invocation**: synapse_orphans misses calls at file scope (e.g., `main()` at end of file). Affects 7 `main()` + 2 internal helpers.
+2. **Class instantiation**: `new ClassName()` calls are not tracked as CALLS edges to `constructor`. Affects 4 constructor methods.
+3. **Subprocess spawn**: Python CLI scripts spawned via `child_process.spawn` don't create graph edges.
+4. **Cross-module import resolution**: `require('./security-filter')` → exported API not mapped to callers.
+5. **Documented-only callers**: Functions referenced only in `.md` docs (smartTrim) are not detected.
+
+---
+
+## Ambiguous
+
+### `hasSensitiveData` — `.memory/tools/security-filter.js` lines 352–355
+
+A 4-line utility function exported via `module.exports.hasSensitiveData`. No external file imports or calls it. However it is part of the exported public API alongside `filterSensitiveData` and `filterMemoryEntry` (which are used by memory-tools.js). It may be dead code or an intentional public API without current consumers.
+
+**Decision**: Not deleted. Requires explicit owner review. Low LOC impact (4 lines).
+
+---
+
+## Synapse_orphans indexing gaps (for TASK_1173)
+
+The following indexing failures were observed and should inform TASK_1173:
+
+1. **Module-scope calls not tracked**: `main()` called at file scope (e.g., `main().catch(...)`) produces no CALLS edge in the graph. This caused 7 false positives.
+2. **Constructor calls not tracked**: `new ClassName()` does not create a CALLS edge to the class `constructor` method. This caused 4 false positives.
+3. **Python subprocess spawn not tracked**: `child_process.spawn('python', [scriptPath])` in registry.ts:478 does not create any cross-language edge.
+4. **Cross-language import not tracked**: `from sync_to_rag import DocsSyncManager` (Python import, in doc examples) not modeled.
+5. **Intra-file module-scope references**: `getArg` called at file scope in run-round2.js — no CALLS edge despite local definition.