Project_Velocity/.Agent Context/Sprint 1/Biomimetic Agentic Orchestration Layer/Sourik Work Assignment_ Colony Runtime Entry Point.md

Sourik Work Assignment_ Colony Runtime Entry Point

Date: 2026-04-14
Status: Active assignment handoff
Assignee: Sourik
Purpose: Define the exact entry-point work expected from Sourik for the colony runtime, including current Project Velocity backend constraints, schema expectations, ingress and deployment assumptions, and collaboration rules that prevent merge conflicts or architectural drift.

1. Assignment Summary

Your assignment is to own the colony runtime entry point without breaking the current Project Velocity root.

This is not a greenfield rewrite. This is an integration-first build. The target is to establish the first working colony spine inside the existing Project Velocity architecture so that Oracle and CRM can become the first governed mission consumers.

Your work starts at the runtime entry boundary:

• TypeScript colony service bootstrap
• root-facing mission intake contract
• Python root to colony service connection shape
• file and module layout that matches the implementation blueprint

You are not being asked to redesign the system from scratch. The system design, runtime split, and domain order are already defined in this folder.

2. Primary Objective

Deliver the first real colony runtime entry path that can accept a mission from the Python root in a disciplined way and return status safely, without bypassing:

• current FastAPI authority
• current Project Velocity CRM routes and schema direction
• current Oracle planning spine
• current ingress and stable API direction

The first implementation should make this statement true:

“Project Velocity root can submit a structured mission to a TypeScript colony service over the stable backend path and retrieve its mission state without inventing a parallel backend center.”

3. What You Are Working Within

Assume the following current truths are already valid and must be respected.

3.1 Root Backend Truth

The current Python backend is already the canonical center.

Relevant existing root files and surfaces:

• [main.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\main.py)
• [routes_crm.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\api\routes_crm.py)
• [routes_oracle.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\api\routes_oracle.py)
• [router_v1.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\router_v1.py)
• [routes_catalyst.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\api\routes_catalyst.py)
• [sentinel.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\routers\sentinel.py)

Root rule:

Do not create a second Python backend center. Do not move domain ownership out of root.

3.2 Oracle Truth

Oracle already has a real planning and action spine.

Relevant files:

• [prompt_orchestrator.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\prompt_orchestrator.py)
• [persona_service.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\persona_service.py)
• [policy_service.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\policy_service.py)
• [data_access_gateway.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\data_access_gateway.py)
• [action_service.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\oracle\action_service.py)

Oracle rule:

Do not replace Oracle v1. The colony is an orchestration layer that should sit beside or beneath the current Oracle flow, not destroy it.

3.3 CRM Truth

CRM is no longer a mock-only subsystem. It already has operational routes and state surfaces.

Relevant files:

• [routes_crm.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\api\routes_crm.py)
• [useCrmBootstrap.ts](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\app\src\hooks\useCrmBootstrap.ts)

Root CRM behavior already includes:

• leads
• chat logs
• kanban
• demographics
• analytics scatter
• websocket sync

CRM rule:

Do not fork CRM schema logic into a separate service. Colony should consume CRM through root contracts and root persistence.

3.4 Nemoclaw and MCP Truth

These already exist as append layers in root:

• [nemoclaw_runtime.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\services\nemoclaw_runtime.py)
• [mcp_registry.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\services\mcp_registry.py)
• [nemoclaw_client.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\backend\services\nemoclaw_client.py)

Guard rule:

Use these as governance and tool abstractions. Do not invent a second unrelated guard layer.

4. What You Must Read First

Before implementation, read these in this order:

1. [Introduction for Sourik.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Introduction for Sourik.md)
2. [Implementation Blueprint_ Repository and Runtime Mapping.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Implementation Blueprint_ Repository and Runtime Mapping.md)
3. [TypeScript Colony Service Internal Module Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\TypeScript Colony Service Internal Module Spec.md)
4. [Colony Database Schema and Root API Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Colony Database Schema and Root API Spec.md)
5. [Oracle and CRM Adapter Detailed Implementation Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Oracle and CRM Adapter Detailed Implementation Spec.md)
6. [Implementation Ticket Breakdown and Dependency Matrix.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Implementation Ticket Breakdown and Dependency Matrix.md)

If you skip this reading order, you will likely recreate decisions that are already closed.

5. Your Concrete Scope

Your assignment scope is the colony runtime entry point.

That means the following.

5.1 Create the TypeScript Colony Service Skeleton

Target path:

• services/colony-orchestrator/

Start with the file tree already defined in:

• [Implementation Blueprint_ Repository and Runtime Mapping.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Implementation Blueprint_ Repository and Runtime Mapping.md)

Minimum early files:

• package.json
• tsconfig.json
• README.md
• src/index.ts
• src/app.ts
• src/config/env.ts
• src/contracts/*
• src/core/colony-runtime.ts
• src/persistence/mission-store.ts
• src/persistence/artifact-store.ts
• src/adapters/python-root-client.ts

5.2 Establish the Internal Mission Intake Surface

Minimum internal colony service routes:

• POST /missions
• GET /missions/:missionId/status
• GET /health

These are internal service routes, not public internet routes.

5.3 Implement Contract-First Intake

The mission intake must validate a structured mission envelope and reject malformed input early.

Use:

• typed contracts
• Zod or equivalent runtime validation
• stable mission IDs
• stable stage reporting

5.4 Integrate Through Root, Not Around Root

Your service should assume the Python root is the caller and the persistence authority.

That means:

• root creates or accepts the mission envelope
• colony service executes the runtime pipeline
• root persists canonical mission state and artifacts

5.5 Prepare for Oracle and CRM as First Consumers

Do not spend your first pass on generic agent experimentation.

Build with these first mission classes in mind:

• oracle_advisory
• crm_lead_intelligence

These are the two mission classes the whole architecture is already optimized around.

6. What You Are Not Supposed to Do

Do not do the following:

• do not rewrite backend/main.py into a new architecture center
• do not replace Oracle prompt orchestration with an unrelated flow
• do not bypass CRM routes and talk directly to ad hoc tables
• do not create direct worker writebacks
• do not expose the colony service as the public external product API
• do not hardcode public IP addresses anywhere
• do not fork a second schema truth outside the current backend ownership model

If any proposed change pushes in those directions, stop and align before coding.

7. Current Backend and Schema Respect Rules

This project already has real work from multiple people. Your implementation must accommodate that.

7.1 Respect Existing Root API Ownership

If a domain already has a route module, integrate through it or beside it:

• backend/api/routes_crm.py
• backend/api/routes_oracle.py
• backend/api/routes_catalyst.py

Do not shadow them with parallel service endpoints that duplicate product authority.

7.2 Respect Current Schema Direction

The current colony persistence direction is already defined in:

• [Colony Database Schema and Root API Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Colony Database Schema and Root API Spec.md)

Phase 1 root tables are:

• colony_missions
• colony_tasks
• colony_prompt_packages
• colony_research_artifacts
• colony_librarian_passes
• colony_worker_results
• colony_aggregation_packets
• colony_review_packets
• colony_policy_decisions
• colony_writeback_proposals
• colony_event_log
• colony_pheromone_signals

Schema rule:

Do not improvise a different schema family unless there is a concrete, defensible reason and it is discussed first.

7.3 Respect Existing Action and Writeback Semantics

Writeback proposals must still flow through root approval and execution control.

Relevant existing root direction:

• Oracle actions already exist
• CRM writeback paths already exist
• colony should produce proposals, not side-effectful worker commits

8. Ingress and Stable API Information You Must Respect

This work must respect the current production networking direction described in:

• [Desineuron Stable Ingress Handoff.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Desineuron Stable Ingress Handoff.md)

8.1 Production Access Pattern

Current correct production pattern:

• public API hostname: api.desineuron.in
• public edge: ingress node with Elastic IP 98.87.120.120
• backend target: current private IP of the EC2 instance tagged DesineuronRole=velocity-backend
• Linux box owns the route-sync timer pattern

8.2 Why This Matters to Your Work

Your work should assume:

• the frontend must not depend on ephemeral backend IPs
• internal colony service communication should also avoid stale hardcoded addressing
• all production-facing references should align with stable ingress and root-owned config

8.3 Repo Artifacts Already Supporting This Pattern

Relevant ingress/runtime files:

• [sync_velocity_route.py](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\infrastructure\desineuron_ingress\sync_velocity_route.py)
• [desineuron-velocity-route-sync.service](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\infrastructure\desineuron_ingress\desineuron-velocity-route-sync.service)
• [desineuron-velocity-route-sync.timer](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\infrastructure\desineuron_ingress\desineuron-velocity-route-sync.timer)
• [install_linux_velocity_route_sync.sh](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\infrastructure\desineuron_ingress\install_linux_velocity_route_sync.sh)
• [TEAM_HANDOFF_2026-04-08.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\infrastructure\desineuron_ingress\TEAM_HANDOFF_2026-04-08.md)

Relevant frontend/runtime files:

• [api.ts](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\app\src\lib\api.ts)
• [vite.config.ts](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\app\vite.config.ts)
• [remote_bootstrap_20260401.sh](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity\remote_bootstrap_20260401.sh)

8.4 Networking Rules for Your Work

When you add configuration for the colony service:

• use environment-driven service URLs
• assume stable ingress for product-facing backend access
• do not pin anything to a one-off EC2 public IP
• assume backend app ports should remain private behind ingress security group control

9. Conflict Avoidance and Merge Discipline

This is important. Multiple people have already touched this codebase.

9.1 Respect Each Other’s Code

Do not revert unrelated changes.

If a file already has real work in it:

• read it first
• integrate with it
• extend it carefully

Do not “clean up” someone else’s work by replacing it wholesale unless there is explicit agreement.

9.2 Avoid Conflict Merges by Ownership Boundary

For your first pass, keep primary ownership focused on:

• services/colony-orchestrator/*
• colony-specific root bridge files once approved:
  • backend/api/routes_colony.py
  • backend/services/colony_gateway.py
  • backend/services/colony_repository.py
  • backend/services/colony_policy_bridge.py
  • backend/db/schema_colony.sql

Try to avoid broad simultaneous edits to:

• backend/api/routes_crm.py
• backend/api/routes_oracle.py
• backend/main.py

until the colony service bootstrap and contracts are stable enough to integrate cleanly.

9.3 Make Small, Defensible Changes

Preferred merge behavior:

• contract layer first
• service bootstrap second
• root bridge third
• adapter entry hooks after that

That sequence keeps merges smaller and reduces cross-team breakage.

10. Recommended Build Order for You

Your best first execution order is:

1. scaffold services/colony-orchestrator/
2. add internal contracts and validation
3. add internal health route
4. add python-root-client.ts
5. define mission intake route and status route
6. align service outputs with root DB/API spec
7. only then start attaching Oracle and CRM adapter paths

Do not start with:

• external research providers
• UI hooks
• generic agent swarms
• direct domain writebacks

11. Deliverables Expected From You

Your first assignment is complete when the following are true:

11.1 Service Bootstrap Exists

The TypeScript colony service exists in repo with the correct top-level structure.

11.2 Mission Intake Works

The service can accept a validated mission envelope and return:

• mission ID
• status
• current stage

11.3 Root Integration Shape Is Clear

The bridge between Python root and colony service is explicit and compatible with the root API and persistence plan.

11.4 No Architectural Regression Occurs

Current Project Velocity routes and domain ownership remain intact.

11.5 No Networking Regression Occurs

Nothing in your work reintroduces ephemeral-IP assumptions or conflicts with the stable ingress/API direction.

12. Exact Docs That Define Your Assignment Boundary

You should treat these as your canonical references:

• [Introduction for Sourik.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Introduction for Sourik.md)
• [Implementation Blueprint_ Repository and Runtime Mapping.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Implementation Blueprint_ Repository and Runtime Mapping.md)
• [TypeScript Colony Service Internal Module Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\TypeScript Colony Service Internal Module Spec.md)
• [Colony Database Schema and Root API Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Colony Database Schema and Root API Spec.md)
• [Oracle and CRM Adapter Detailed Implementation Spec.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Oracle and CRM Adapter Detailed Implementation Spec.md)
• [Desineuron Stable Ingress Handoff.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Desineuron Stable Ingress Handoff.md)
• [Implementation Ticket Breakdown and Dependency Matrix.md](F:\Workin In Progress\DESINEURON\GITLAB\Project_Velocity.Agent Context\Sprint 1\Biomimetic Agentic Orchestration Layer\Implementation Ticket Breakdown and Dependency Matrix.md)

13. Final Guidance

The right way to help this system is to strengthen the runtime spine, not to spread into every domain file at once.

If you build:

• the service skeleton
• the mission intake contract
• the root integration seam
• the non-conflicting file boundary

then the rest of the team can attach Oracle, CRM, governance, and review behavior without stepping on each other.

14. Bottom Line

Your assignment is to establish the colony runtime entry point in a way that respects the current Project Velocity backend, current schema direction, current stable ingress deployment pattern, and current multi-person code ownership reality.

Build the spine first. Keep the changes narrow. Respect root ownership. Respect existing routes and schema. Avoid hardcoded infrastructure assumptions. Avoid broad conflicting edits. If you do that, your work becomes the clean starting point the rest of the team can safely build on.