Project_Velocity/.Agent Context/Issues/2026-04-12-sourik-root-integration-closure.md

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