# Dead Code & Unused Dependencies Audit Report

**Project:** VeilCLI  
**Date:** 2026-03-04  
**Scope:** Production code in `core/`, `utils/`, `infrastructure/`, `api/`, `tools/`, `llm/`, `settings/`

---

## Summary

| Category | Count |
|----------|-------|
| Unused Exports | 14 |
| Dead Internal Functions | 2 |
| Orphaned Database Columns | 3 |
| Undocumented/Untested Routes | 0 |
| Orphaned Tools | 0 |
| Unused Dependencies | 0 |

---

## Unused Exports

Functions/constants exported from modules but never imported elsewhere in production code.

| File | Export | Reason |
|------|--------|--------|
| `core/agent.js:182` | `loadAgentFromFolder` | Only used internally by `loadAgent()` in same file — no external imports |
| `core/agent.js:182` | `resolveAgentFolder` | Only used internally in `loadAgentFromFolder()` — no external imports |
| `core/compaction.js:177` | `applyObservationMasking` | Only called internally by `manageContext()` — no external imports |
| `core/compaction.js:178` | `applyToolResultClearing` | Only called internally by `manageContext()` — no external imports |
| `core/compaction.js:179` | `estimateContextUsage` | Only called internally by `manageContext()` — no external imports |
| `core/compaction.js:180` | `compactMessages` | Only called internally by `manageContext()` — no external imports |
| `core/loop.js:493` | `checkPermission` | Only used internally in `runLoop()` — no external imports |
| `core/registry.js:248` | `registerBuiltin` | Only called by `loadBuiltinTools()` in same file — no external imports |
| `core/registry.js:255` | `toolToOpenAIFormat` | Only used internally by `buildToolsForLLM()` — no external imports |
| `core/registry.js:256` | `getBuiltinNames` | Never imported anywhere — exposed but unused |
| `core/queue.js:99` | `hasPendingMessages` | Never imported anywhere — exposed but unused |
| `core/queue.js:99` | `drainNonFollowup` | Never imported anywhere — exposed but unused |
| `core/queue.js:99` | `drainFollowup` | Never imported anywhere — exposed but unused |
| `core/queue.js:99` | `postCorrelatedResponse` | Never imported anywhere — exposed but unused |
| `core/memory.js:99` | `readMemory` | Never imported anywhere (tools use direct fs access) — exposed but unused |
| `core/memory.js:99` | `searchMemory` | Never imported anywhere (memory_search.js uses its own implementation) — exposed but unused |
| `utils/settings.js:134` | `deepMerge` | Only used internally in `loadSettings()` — no external imports |
| `utils/settings.js:134` | `getDefaults` | Only used internally in `loadSettings()` — no external imports |
| `utils/paths.js:214` | `getBackupsDir` | Never imported anywhere — exposed but unused |
| `utils/paths.js:210` | `getGlobalSkillsDir` | Never imported anywhere — exposed but unused |
| `infrastructure/database.js:464` | `runMigrations` | Only called internally by `getDb()` — no external imports |

---

## Dead Internal Functions

Private helpers defined but never called within their own file.

| File | Function | Reason |
|------|----------|--------|
| `core/memory.js:51` | `exportOldMemory` | Called by `writeMemory()` but `writeMemory()` itself is never called (tools use direct fs access) |

> **Note:** Most internal helper functions ARE called within their files. The `core/memory.js` module appears to be legacy — the actual `memory_write.js` tool uses direct filesystem operations instead of calling the core memory module.

---

## Orphaned Database Columns

Columns defined in migrations but never read or written by production code.

| Table | Column | Reason |
|-------|--------|--------|
| `sessions` | `compaction_count` | No camelCase (`compactionCount`) usage in production code; only in `.OLD/` legacy code |
| `sessions` | `estimated_cost` | No camelCase (`estimatedCost`) usage in production code; only in `.OLD/` legacy code |
| `tasks` | `estimated_cost` | No camelCase (`estimatedCost`) usage in production code; only in `.OLD/` legacy code |

> **Note:** The `token_cache` column IS used — written via `tokenCache` in `core/loop.js:307` and `core/router.js`.

---

## Undocumented/Untested Routes

All API routes are documented and tested.

| Route | Documented | Tested |
|-------|------------|--------|
| All routes in `api/routes/*.js` | ✅ `docs/api/*.md` | ✅ `test/integration/*.test.js` |

**Verification:**
- `/settings` — documented in `08-settings.md`, tested in `17-settings-api.test.js`
- `/memory/*` — documented in `07-memory.md`, tested in `16-memory-api.test.js`
- All other routes covered by existing docs and tests

---

## Orphaned Tools

All tools in `tools/` are properly registered and reachable.

| Tool | Status |
|------|--------|
| All 24 tools in `tools/*.js` | ✅ Loaded via `core/registry.js:loadBuiltinTools()` |

**Verification:** 
- `loadBuiltinTools()` in `core/registry.js:37-48` iterates over all `.js` files in the `tools/` directory
- Each tool exports `{ schema, execute }` and is automatically registered
- No orphaned tools found

---

## Unused Dependencies

All dependencies in `package.json` are imported somewhere in production code.

| Package | Usage |
|---------|-------|
| `ajv` | `core/agent.js`, `core/registry.js`, `api/routes/settings.js` |
| `ajv-formats` | `core/registry.js`, `api/routes/settings.js` |
| `better-sqlite3` | `infrastructure/database.js` |
| `cors` | `api/server.js` |
| `express` | `api/server.js`, `api/routes/*.js` |
| `node-cron` | `infrastructure/scheduler.js` |
| `ws` | `api/server.js` (WebSocket server) |

---

## Recommendations

### High Priority (Remove Dead Code)

1. **`core/queue.js`** — The entire module appears unused. The loop uses `drainMessageQueue()` defined inline in `core/loop.js:106-114`. Consider:
   - Removing `core/queue.js` entirely, OR
   - Refactoring `core/loop.js` to use `core/queue.js` functions

2. **`core/memory.js`** — The module is bypassed by tools (`memory_read.js`, `memory_write.js`, `memory_search.js` all use direct fs access). Consider:
   - Having tools use this module, OR
   - Removing the module

3. **Orphaned DB columns** (`compaction_count`, `estimated_cost`) — These columns are never written. Either:
   - Implement cost tracking, OR
   - Remove via a migration

### Low Priority (API Surface Cleanup)

4. **Unexported internal helpers** — Many functions are exported but only used internally. Consider reducing module.exports to only externally-used functions:
   - `core/agent.js`: Remove `loadAgentFromFolder`, `resolveAgentFolder` from exports
   - `core/compaction.js`: Only export `manageContext`
   - `core/registry.js`: Remove `registerBuiltin`, `toolToOpenAIFormat`, `getBuiltinNames`
   - `utils/settings.js`: Remove `deepMerge`, `getDefaults`
   - `utils/paths.js`: Remove `getBackupsDir`, `getGlobalSkillsDir`

---

## Files Analyzed

```
core/agent.js, core/cancel.js, core/compaction.js, core/events.js, 
core/loop.js, core/memory.js, core/prompt.js, core/queue.js, 
core/registry.js, core/router.js

utils/context.js, utils/id.js, utils/paths.js, utils/settings.js

infrastructure/database.js, infrastructure/scheduler.js

llm/client.js

settings/fields.js

api/middleware.js, api/server.js
api/routes/agents.js, api/routes/chat.js, api/routes/daemons.js,
api/routes/memory.js, api/routes/sessions.js, api/routes/settings.js,
api/routes/system.js, api/routes/tasks.js

tools/*.js (24 files)

migrations/001-initial.sql, migrations/002-debuggability.sql
```