# Mission Contracts and JSON Schemas Blueprint

**Date:** 2026-04-14  
**Status:** Draft implementation artifact  
**Purpose:** Define the concrete contract model, JSON payload shapes, schema boundaries, versioning rules, and validation plan for the colony orchestration layer.

## 1. Purpose

This document converts the colony architecture into explicit contracts. The system must not rely on informal prompt chaining between stages. Every stage must read and write a typed artifact.

## 2. Contract Design Rules

### 2.1 Version Every Artifact

Every artifact must carry:

- `schema_name`
- `schema_version`

This is mandatory from day one so prompt package evolution and mission replay do not become brittle later.

### 2.2 Keep Root Metadata on Every Artifact

Every artifact should include:

- `mission_id`
- `tenant_id`
- `actor_id`
- `created_at`
- `producer`

This prevents orphan artifacts and makes debugging much easier.

### 2.3 Store Canonical Payloads as JSON

Root PostgreSQL persistence should store the canonical artifact payload in `jsonb`, even if some fields are also denormalized for indexing.

### 2.4 Prefer Small Composable Artifacts

Do not use one giant colony state blob. The correct design is multiple artifacts with explicit linkage.

## 3. Core Artifact Set

Phase 1 artifact set:

- `mission_envelope`
- `mission_task_graph`
- `prompt_package`
- `research_artifact`
- `librarian_pass`
- `worker_result`
- `aggregation_packet`
- `review_packet`
- `policy_decision`
- `writeback_proposal`

## 4. Mission Envelope Schema

### 4.1 Purpose

Defines the normalized mission before decomposition.

### 4.2 Suggested JSON Shape

```json
{
  "schema_name": "mission_envelope",
  "schema_version": "v1",
  "mission_id": "uuid",
  "mission_type": "oracle_advisory",
  "origin_surface": "oracle",
  "tenant_id": "tenant_velocity",
  "actor_id": "oracle_operator",
  "actor_role": "sales_director",
  "user_goal": "Summarize the highest intent waterfront prospects and recommend next actions.",
  "normalized_goal": "Produce a prioritized lead intelligence brief for waterfront prospects with actions.",
  "risk_level": "medium",
  "sensitivity_class": "internal_business",
  "time_budget_ms": 45000,
  "token_budget": 180000,
  "requested_outputs": [
    "reviewed_summary",
    "writeback_proposal"
  ],
  "context_refs": {
    "lead_ids": ["lead_123"],
    "page_id": null,
    "campaign_ids": []
  },
  "created_at": "2026-04-14T12:00:00Z",
  "producer": "python_root_gateway"
}
```

### 4.3 Required Fields

Required:

- `schema_name`
- `schema_version`
- `mission_id`
- `mission_type`
- `origin_surface`
- `tenant_id`
- `actor_id`
- `user_goal`
- `normalized_goal`
- `risk_level`
- `sensitivity_class`
- `created_at`
- `producer`

## 5. Mission Task Graph Schema

### 5.1 Purpose

Defines the DAG produced by the planner.

### 5.2 Suggested JSON Shape

```json
{
  "schema_name": "mission_task_graph",
  "schema_version": "v1",
  "mission_id": "uuid",
  "tasks": [
    {
      "task_id": "task_plan_01",
      "role_type": "prompt_master",
      "objective": "Prepare role-specific prompt packages for all execution tasks.",
      "depends_on": [],
      "required_capabilities": ["prompt_templates", "task_prompting"],
      "allowed_tools": [],
      "required_data_scopes": ["mission_metadata"],
      "success_criteria": [
        "prompt packages exist for all downstream tasks"
      ]
    }
  ],
  "created_at": "2026-04-14T12:00:02Z",
  "producer": "planner_agent"
}
```

### 5.3 Required Rules

- every `task_id` must be unique within mission
- `depends_on` must only reference existing task IDs
- role types must be from an allowed enum in Phase 1

Phase 1 allowed role types:

- `planner`
- `prompt_master`
- `researcher`
- `librarian`
- `worker`
- `aggregator`
- `reviewer`

## 6. Prompt Package Schema

### 6.1 Purpose

Defines the exact worker-facing prompt instruction package.

### 6.2 Suggested JSON Shape

```json
{
  "schema_name": "prompt_package",
  "schema_version": "v1",
  "mission_id": "uuid",
  "task_id": "task_worker_01",
  "package_id": "pkg_001",
  "role_type": "worker",
  "template_id": "crm_lead_intelligence_worker",
  "template_version": "v1",
  "examples_used": [
    "crm_worker_example_01"
  ],
  "system_prompt": "You are a lead intelligence specialist...",
  "task_prompt": "Analyze the provided lead context...",
  "constraints": {
    "must_cite_sources": true,
    "must_not_writeback_directly": true
  },
  "tool_scope": [
    "crm_search",
    "local_property_rag",
    "external_search"
  ],
  "model_route": "tier_high_reasoning",
  "created_at": "2026-04-14T12:00:05Z",
  "producer": "prompt_master_agent"
}
```

## 7. Research Artifact Schema

### 7.1 Purpose

Represents external evidence.

### 7.2 Suggested JSON Shape

```json
{
  "schema_name": "research_artifact",
  "schema_version": "v1",
  "mission_id": "uuid",
  "task_id": "task_research_01",
  "artifact_id": "res_001",
  "provider": "brave",
  "query": "Dubai waterfront premium real estate 2026 demand",
  "results": [
    {
      "title": "Market report title",
      "url": "https://example.com/report",
      "snippet": "Short snippet",
      "source_type": "web",
      "retrieved_at": "2026-04-14T12:01:00Z",
      "confidence": 0.82
    }
  ],
  "created_at": "2026-04-14T12:01:01Z",
  "producer": "researcher_agent"
}
```

## 8. Librarian Pass Schema

### 8.1 Purpose

Represents scoped internal routing instructions for workers.

### 8.2 Suggested JSON Shape

```json
{
  "schema_name": "librarian_pass",
  "schema_version": "v1",
  "mission_id": "uuid",
  "task_id": "task_worker_01",
  "pass_id": "pass_001",
  "allowed_resource_families": [
    "crm.leads",
    "crm.chat_logs"
  ],
  "recommended_queries": [
    {
      "tool": "crm_search",
      "query": "waterfront whale prospects"
    }
  ],
  "cached_previews": [
    {
      "label": "Lead summary",
      "entity_type": "lead",
      "entity_id": "lead_123",
      "preview": "Whale prospect interested in marina-facing unit"
    }
  ],
  "expires_at": "2026-04-14T13:00:00Z",
  "created_at": "2026-04-14T12:00:08Z",
  "producer": "librarian_agent"
}
```

## 9. Worker Result Schema

### 9.1 Purpose

Represents normalized output from one worker.

### 9.2 Suggested JSON Shape

```json
{
  "schema_name": "worker_result",
  "schema_version": "v1",
  "mission_id": "uuid",
  "task_id": "task_worker_01",
  "result_id": "wrk_001",
  "output_text": "Lead 123 has the highest close probability...",
  "structured_output": {
    "priority": "high",
    "recommended_action": "schedule executive follow-up"
  },
  "citations": [
    {
      "kind": "internal",
      "ref": "lead_123"
    }
  ],
  "confidence": 0.79,
  "tool_trace_refs": [
    "toolcall_001",
    "toolcall_002"
  ],
  "created_at": "2026-04-14T12:02:10Z",
  "producer": "worker_agent"
}
```

## 10. Aggregation Packet Schema

### 10.1 Purpose

Represents the synthesized draft before review.

### 10.2 Suggested JSON Shape

```json
{
  "schema_name": "aggregation_packet",
  "schema_version": "v1",
  "mission_id": "uuid",
  "packet_id": "agg_001",
  "summary": "Top waterfront leads are concentrated in two whale segments...",
  "evidence_matrix": [
    {
      "claim": "Lead 123 is high priority",
      "support_refs": ["wrk_001", "lead_123"]
    }
  ],
  "contradictions": [],
  "coverage_gaps": [],
  "recommended_output": {
    "format": "structured_brief"
  },
  "created_at": "2026-04-14T12:03:00Z",
  "producer": "aggregator_agent"
}
```

## 11. Review Packet Schema

### 11.1 Purpose

Represents the one-pass review outcome.

### 11.2 Suggested JSON Shape

```json
{
  "schema_name": "review_packet",
  "schema_version": "v1",
  "mission_id": "uuid",
  "packet_id": "rev_001",
  "review_status": "approved_with_edits",
  "issues": [
    {
      "severity": "medium",
      "message": "One recommendation needs clearer business justification."
    }
  ],
  "required_edits": [
    "add one sentence linking lead score to action priority"
  ],
  "approved_output": {
    "summary": "Reviewed final answer here"
  },
  "created_at": "2026-04-14T12:03:20Z",
  "producer": "reviewer_agent"
}
```

## 12. Policy Decision Schema

### 12.1 Purpose

Represents an explicit allow or deny decision from the guard plane.

### 12.2 Suggested JSON Shape

```json
{
  "schema_name": "policy_decision",
  "schema_version": "v1",
  "mission_id": "uuid",
  "decision_id": "pol_001",
  "decision_type": "tool_scope",
  "subject": "external_search",
  "decision": "allow",
  "reason": "mission sensitivity permits public web search",
  "created_at": "2026-04-14T12:00:03Z",
  "producer": "colony_policy_bridge"
}
```

## 13. Writeback Proposal Schema

### 13.1 Purpose

Represents a proposed root mutation. This is a proposal only, never a direct execution artifact.

### 13.2 Suggested JSON Shape

```json
{
  "schema_name": "writeback_proposal",
  "schema_version": "v1",
  "mission_id": "uuid",
  "proposal_id": "wb_001",
  "target_entity_type": "lead",
  "target_entity_id": "lead_123",
  "action_type": "lead_stage_update",
  "payload": {
    "kanban_status": "Negotiation"
  },
  "requires_approval": true,
  "created_at": "2026-04-14T12:03:25Z",
  "producer": "reviewer_agent"
}
```

## 14. Root Table Mapping

Recommended root table to artifact mapping:

- `colony_missions` -> mission envelope
- `colony_tasks` -> task graph task records
- `colony_prompt_packages` -> prompt package
- `colony_research_artifacts` -> research artifact
- `colony_librarian_passes` -> librarian pass
- `colony_worker_results` -> worker result
- `colony_aggregation_packets` -> aggregation packet
- `colony_review_packets` -> review packet
- `colony_policy_decisions` -> policy decision

## 15. Validation Strategy

Validation should occur in three layers:

1. TypeScript runtime validation in colony service
2. Python root payload validation before persistence
3. database-level required column and foreign key validation

## 16. Immediate Implementation Order

Implement schemas in this order:

1. mission envelope
2. task graph
3. prompt package
4. worker result
5. review packet
6. policy decision
7. librarian pass
8. research artifact
9. aggregation packet
10. writeback proposal

## 17. Bottom Line

The colony will only be dependable if every stage is contract-first. This document defines the contract spine that allows the rest of the implementation to stay disciplined.