# Project Velocity: Sentinel QD Engine Status Report
*Generated: April 1, 2026*

This artifact provides a comprehensive overview of the current status of the **Sentinel Quantum Dynamics (QD) Engine**. It maps the architectural decisions and milestones directly to the codebase, detailing what has been completed, deployed, and what remains to be done.

---

## 1. Architectural Adjustments & Realities
During the NemoClaw deployment (Milestone 4 & 7), several key architectural realities emerged that forced an adjustment to the original design:

1. **Inference Pipeline Switch (NVIDIA API vs. Ollama)**
   - **Original Plan**: Route traffic through the OpenShell mTLS gateway locally holding `qwen3.5:27b`.
   - **The Reality**: The `qwen3.5:27b` model under Ollama currently runs in an extended "think mode" (chain-of-thought) which exhausts token limits before outputting JSON, causing timeouts. The OpenShell Gateway also expects internal sandbox client certificates (mTLS).
   - **The Pivot**: We have updated `nemoclaw_client.py` to use the **NVIDIA API directly** (`llama-3.3-nemotron-super-49b-v1`) as the primary inference engine since it is OpenAI-compatible, fast, and reliable. Ollama remains a fallback (with a known TODO to fix the `think` parameter parsing).

2. **Storage Eviction Issues Resolved**
   - **The Reality**: k3s and Docker were exhausting the root `/dev/root` volume, triggering disk pressure evictions and crashing OpenShell pods.
   - **The Pivot**: We migrated the 103GB model cache and the `/var/lib/rancher` k3s storage to the 3.4TB `/opt/dlami/nvme` partition, restoring disk health and allowing NemoClaw to successfully "onboard" and enter a "Ready" state.

3. **Port Collisions**
   - **The Reality**: Both the existing `velocity-oracle` and the OpenShell gateway wanted port `8080`.
   - **The Pivot**: We migrated `velocity-oracle` to bind to port **`8081`**.

---

## 2. Codebase Map: What is Done

### ✅ **Milestone 1: Database & Auth**
- **Types:** `app/src/types/index.ts` (BiometricPacket, QDScore, Notifications)
- **State:** `app/src/store/useStore.ts` (Notification state management)
- **Schema:** `backend/db/schema.sql`, `backend/db/schema_addendum.sql`
- **Pool Data:** `backend/db/pool.py`, `backend/auth/dependencies.py`
- **Entrypoint:** `backend/main.py` (FastAPI lifecycle and router integration)

### ✅ **Milestone 2: Velocity Link & Notifications**
- **Routers:** `backend/routers/vault.py`
- **Hooks:** `app/src/hooks/useVelocitySocket.ts`
- **UI:** `app/src/components/layout/NotificationCenter.tsx` + `App.tsx` wiring.

### ✅ **Milestone 3: Perception Pipeline (Frontend)**
- **WASM Encoders:** `app/src/utils/landmarkPacketEncoder.ts`
- **Vision Feed:** `app/src/hooks/useMediapipeFaceLandmarker.ts`
- **Live UI:** `app/src/components/modules/sentinel/PerceptionPlayer.tsx` + `SentinelLiveSession.tsx`

### ✅ **Milestone 4 & 7: NemoClaw Sandbox & AWS Env**
- **Client Logic:** `backend/services/nemoclaw_client.py` (Now pointed to NVIDIA API)
- **Prompts:** Uploaded to NVMe (`cctv_profiler.md`, `lead_tagger.md`, `qd_calculator.md`)
- **System Service:** `nemoclaw-velocity.service` created and enabled.
- **Environment:** `/opt/dlami/nvme/velocity/env` written.
- **NemoClaw Onboarding:** Succeeded; the sandbox is completely ready (`Phase: Ready`).

---

## 3. Pending Workflow: What is Left

### ⏳ **Database Initialization (Finalizing Milestone 1/7)**
While the backend code and schema files exist, the AWS database instance itself has not been booted.
- **Action Required:** Instantiate PostgreSQL on `/opt/dlami/nvme/pgdata` and execute `schema.sql` and `schema_addendum.sql`.
- **Action Required:** Point FastAPI to the PostgreSQL instance.

### ⏳ **Milestone 5: CCTV & Auto Mode Integration**
- **Action Required:** Build `backend/routers/cctv.py` to ingest frames.
- **Action Required:** Build OCR bridging logic to pass plates and cars to the NemoClaw prompt (`cctv_profiler.md`) and into the DB.
- **Action Required:** Build `backend/services/auto_mode_matcher.py` (matching CCTV feed data to post-session lead attribution).

### ⏳ **Milestone 6: Video Scene CSV Upload**
- **Action Required:** Implement `backend/routers/scenes.py` (/api/scenes/upload endpoint).
- **Action Required:** Integrate the scene context into the frontend `PerceptionPlayer` to correlate timestamped video annotations with real-time biometric feeds.

### ⏳ **Milestone 8: End-to-End Integration Testing**
- **Action Required:** E2E testing of the full pipeline (Frontend → FastAPI → PostgreSQL/NemoClaw → Frontend Notifications).