Skip to content

DOC-RECONCILIATION.md

Latest commit

 

History

History
116 lines (76 loc) · 6.69 KB

DOC-RECONCILIATION.md

File metadata and controls

116 lines (76 loc) · 6.69 KB

DOC-RECONCILIATION.md

This file was generated by the /doc-truth-up documentation-reconciliation pass. The pass treats the code as read-only ground truth and edits only documentation files so they reflect the repo's actual current state. No code was created, modified, or deleted, and no builds or tests were executed. Its purpose is to give any future reviewer an auditable record of what was checked and what was changed.

Per-Claim Findings

1. What It Is

Status: consistent
Basis: verified-by-reading-code

README intro accurately describes Codec as a macOS desktop app capturing local home-network traffic and presenting a conversation timeline plus force-directed topology graph. All described components exist in source: ConversationView/, TopologyView/, DevicePanel/, HistoryPanel/, StatusBar.tsx, src-tauri/helper/src/decoder/ (DNS, TLS, HTTP, mDNS, DHCP). No changes made.

2. Current State

Status: drifted → fixed
Basis: verified-by-reading-code

CLAUDE.md (portfolio-context block, "Current State" section) claimed Phase 0: Capture Engine + Privileged Helper — the very first phase. The source tree fully implements Phases 0, 1, and 2:

  • Phase 0 evidence: src-tauri/helper/src/ (capture, aggregator, socket, all decoders), scripts/install-helper.sh, scripts/grant-bpf.sh
  • Phase 1 evidence: src-tauri/src/db/ (schema, queries), src-tauri/src/capture/device_registry.rs, src/components/ConversationView/ (3 components), all Tauri IPC commands registered in lib.rs
  • Phase 2 evidence: src/components/TopologyView/ (TopologyView, useForceGraph, NodeTooltip), src/components/HistoryPanel/HistoryPanel.tsx, src/components/DevicePanel/ (DevicePanel, DeviceRow), src/components/shared/StatusBar.tsx
  • Phase 3 absent: no onboarding wizard component, no anomaly detection (no GeoLite2-Country.mmdb in assets/, no anomaly field in models), no menu bar setup in lib.rs

Change in CLAUDE.md:
Before: **Phase 0: Capture Engine + Privileged Helper**
After: **Phases 0–2 complete.** Capture engine (libpcap + ARP spoofing), backend persistence (SQLite, OUI registry, all protocol decoders), and full UI (conversation timeline, topology graph, history panel, device panel, status bar) are all implemented. Phase 3 (onboarding wizard, anomaly detection, macOS menu bar) is not yet started.

3. Stack

Status: drifted (pnet version) → fixed
Basis: verified-by-reading-code

All major stack claims check out against package.json and src-tauri/Cargo.toml:

  • Tauri 2 ✓ (tauri = { version = "2" })
  • React 18 ✓ ("react": "^18.3.1")
  • TypeScript 5 ✓ ("typescript": "~5.8.3")
  • rusqlite 0.31 ✓ (rusqlite = { version = "0.31", features = ["bundled"] })
  • D3.js 7.x ✓ ("d3": "^7.9.0")
  • Zustand 4.x ✓ ("zustand": "4.5.7")
  • pcap crate 2.x ✓ (pcap = "2")
  • Tailwind CSS 3.x ✓ ("tailwindcss": "^3.4.17")

Drifted: CLAUDE.md listed pnet 0.34 in both its main Stack section and the portfolio-context Stack section. The actual src-tauri/helper/Cargo.toml specifies pnet = "0.35" and pnet_packet = "0.35".

Change in CLAUDE.md (main Stack section):
Before: - pnet 0.34 — raw sockets for ARP spoofing
After: - pnet 0.35 — raw sockets for ARP spoofing

Change in CLAUDE.md (portfolio-context Stack section):
Before: - pnet: 0.34 — raw sockets for ARP spoofing
After: - pnet: 0.35 — raw sockets for ARP spoofing

4. How to Run

Status: consistent
Basis: verified-by-reading-code

README.md documents pnpm install, pnpm tauri dev, and pnpm tauri build. The package.json defines a "tauri": "tauri" script, confirming both commands resolve correctly. CLAUDE.md documents cargo clippy as the pre-commit check, which is a valid Cargo command for this workspace. No changes made.

Note: package.json test script is echo "Tests configured in Phase 2" — there are no automated frontend tests. CLAUDE.md states "unit tests required for all Rust decoders and TypeScript formatters before phase completion" as a requirement, not a status claim; this is advisory text and not contradicted by the code's current test state.

5. Known Risks (doc ↔ code contradictions)

Status: consistent (for README/CLAUDE.md claims)
Basis: verified-by-reading-code

All documented architectural constraints are reflected in the code:

  • codec-helper is a separate binary (src-tauri/helper/) with its own Cargo.toml ✓
  • 2-second delta flush cadence coded in helper/src/main.rs (Duration::from_secs(2)) ✓
  • SQLite at ~/.codec/codec.db, opened in lib.rs via dirs::home_dir().join(".codec") ✓
  • No raw packet payloads — flow table stores only metadata ✓
  • OUI database bundled (assets/oui.csv present, loaded on startup in lib.rs) ✓
  • ARP spoof opt-in: arp_spoof_enabled seeded as 'false' in schema, toggle wired through IPC ✓

Items noted for manual review in the section below (IMPLEMENTATION-ROADMAP.md discrepancies).

6. Next Move

Status: consistent
Basis: verified-by-reading-code

IMPLEMENTATION-ROADMAP.md correctly lists Phase 3 tasks (onboarding wizard, anomaly detection, menu bar, performance audit) as the remaining work. After the Current State fix in CLAUDE.md, the next-move claim is now self-consistent. No changes made.

Contradictions for Manual Review

These are drift items found in files outside the allowed edit scope (IMPLEMENTATION-ROADMAP.md). A human should apply these one-line fixes.

File Location Issue Suggested fix
IMPLEMENTATION-ROADMAP.md Dependencies block (helper), line ~357 Specifies dns-parser = "0.8" but the actual helper/Cargo.toml uses simple-dns = "0.9" Replace dns-parser = "0.8" with simple-dns = "0.9"
IMPLEMENTATION-ROADMAP.md TypeScript Type Definitions block TopologyNode interface specifies field type: 'device' | 'service' | 'router' but actual src/types/index.ts uses node_type: "device" | "service" | "router" (different field name), and the live type has two additional fields: icon: string and total_bytes: number Update the roadmap's TypeScript snippet to match the actual interface
IMPLEMENTATION-ROADMAP.md File Structure diagram Shows src-tauri/src/capture/flow_table.rs as a main-process file, but no such file exists; flow table logic lives in src-tauri/helper/src/aggregator.rs Remove flow_table.rs from the diagram or note it as aggregator.rs in the helper

Footer

Reconciliation timestamp: 2026-06-02 19:41:24 PDT
Branch: docs/truth-up-2026-06-02
HEAD sha reconciled against: 3fe7d72059955cfe0f81ebc8879619031ac2a92a