# Sourik Root Integration Closure

## Summary

This issue tracks the root-side integration of the useful Sourik subsystems into the current Project Velocity mainline without replacing the root FastAPI shell, root Sentinel ownership, or the existing Python-native Oracle v1 surface.

The objective was to absorb the missing operational pieces into the root codebase so Sprint 1 truth is judged by current product reality rather than by stale planning artifacts.

## Scope Closed In This Pass

### CRM backend and sync

- landed canonical root CRM routes for:
  - `GET/POST/PUT/DELETE /api/leads`
  - `GET /api/leads/{lead_id}`
  - `GET /api/leads/demographics`
  - `GET/POST /api/chat-logs`
  - `GET /api/kanban/board`
  - `PUT /api/kanban/move`
  - `POST /api/leads/seed-synthetic`
- added dedicated CRM websocket stream at `GET /ws/crm`
- added root-side CRM event broadcasting for:
  - lead create
  - lead update
  - lead delete
  - kanban move
  - chat log create
  - synthetic seed runs
  - Oracle writebacks

### Oracle append and writeback contract

- kept root Oracle v1 as the primary public Oracle surface
- appended persona and workflow orchestration under the existing Oracle v1 flow
- added real MCP execution endpoint:
  - `POST /api/oracle/mcp/execute`
- added Oracle action ledger and read/writeback routes:
  - `GET /api/oracle/actions`
  - `GET /api/oracle/actions/{action_id}`
  - `POST /api/oracle/actions/writeback`
- Oracle prompt submissions now create persisted action records tied to execution output
- Oracle writebacks now support canonical lead updates for:
  - score adjustments
  - stage changes
  - qualification changes
  - metadata patching
  - note append
  - Oracle-generated message insertion into `chat_logs`

### MCP and search

- converted the MCP registry from a placeholder slot into an executable root service
- external search now executes against:
  - Brave Search if `BRAVE_API_KEY` is configured
  - DuckDuckGo fallback otherwise
- CRM and local property retrieval tools now execute against the root CRM schema through the root DB pool

### Catalyst marketing backend parity

- replaced hardcoded campaign summaries with unified ad-network service backed by root code
- added root Meta plus Google Ads unified campaign listing
- added unified insights endpoint with platform filtering
- added budget update route for Meta plus Google
- added bid strategy update route for Meta plus Google
- added Google-aware campaign creation path so Catalyst campaign creation is no longer Meta-only

Routes covered in this pass:

- `GET /api/catalyst/campaigns`
- `POST /api/catalyst/campaigns/create`
- `GET /api/catalyst/insights/realtime`
- `PUT /api/catalyst/budget`
- `PUT /api/catalyst/bid-strategy`

### Frontend carry-forward

- preserved the existing root Catalyst shell
- kept the vertically stacked `Marketing` sub-tab inside Catalyst
- no second marketing app or second frontend API source of truth was introduced

## Files Added Or Materially Updated

### Backend

- `backend/services/ad_network_service.py`
- `backend/services/mcp_registry.py`
- `backend/api/routes_catalyst.py`
- `backend/api/routes_crm.py`
- `backend/api/routes_oracle.py`
- `backend/oracle/action_service.py`
- `backend/oracle/router_v1.py`
- `backend/main.py`

### Tests

- `backend/tests/test_catalyst_routes.py`
- `backend/tests/test_oracle_routes.py`
- `backend/tests/test_crm_websocket.py`

## Verification Completed

- `python -m pytest Project_Velocity/backend/tests/test_catalyst_routes.py Project_Velocity/backend/tests/test_oracle_routes.py Project_Velocity/backend/tests/test_crm_websocket.py Project_Velocity/backend/tests/test_crm_routes.py Project_Velocity/backend/tests/oracle/test_persona_service.py Project_Velocity/backend/tests/test_nemoclaw_runtime.py`
- result: `9 passed`

- `npm run build`
- result: passed

## Production Notes

- Google Ads support is now integrated at the root contract level, but live mutate behavior still depends on valid provider credentials and provider-managed operations.
- Brave Search becomes the preferred external search provider when `BRAVE_API_KEY` is present; otherwise the root falls back to DuckDuckGo.
- Oracle writebacks currently target leads as the canonical CRM entity. Additional entity writebacks should follow the same `oracle_actions` ledger rather than introducing side-channel writes.

## Residual Work After This Closure

These are still separate follow-up items, not blockers for closing this integration pass:

- deeper Google Ads mutate coverage beyond provider-managed passthroughs
- frontend consumption of the CRM websocket stream
- broader Oracle writebacks beyond `lead`
- stricter auth and role gating for Oracle action application
- richer Catalyst campaign creation UX for platform-specific fields
- prompt inventory and persona-to-runtime mapping docs cleanup

## Acceptance Criteria Met

- root app shell preserved
- root FastAPI entrypoint preserved
- root Sentinel ownership preserved
- no Go runtime adopted
- no second backend center introduced
- MCP external search executes for real
- CRM has a live websocket sync surface
- Oracle has a persisted action/writeback contract
- Catalyst backend exposes Google-aware parity routes in the root