# Colony Database Schema and Root API Spec

**Date:** [YYYY-MM-DD]  
**Status:** [Draft | In Review | Approved]  
**Owner:** [Name]  
**Reviewers:** [Names]  
**Scope:** [Mission store, root API, approval flow, or related boundary]  
**Purpose:** Define the database schema, root repository behavior, and API surface required for the target system.

## 1. Purpose

State what persistence and API layer is being defined.

## 2. Design Principles

Define the persistence and root-ownership rules.

## 3. Schema Files

List the SQL files or migration units to create.

## 4. Required Tables

List the canonical tables needed.

## 5. Detailed Table Plan

For each table, include:

- purpose
- recommended columns
- indexes
- lifecycle notes

## 6. Root Modules

List:

- repository module
- gateway module
- policy bridge
- route module

## 7. Root API Surface

For each endpoint, include:

- route
- method
- purpose
- request shape
- response shape
- access control

## 8. Lifecycle States

Define status fields and valid transitions.

## 9. Writeback Release Flow

Define proposal, approval, execution, and audit sequence.

## 10. Repository Contract

List the required repository methods.

## 11. Query Shapes

Define:

- summary query
- artifact query
- replay query
- operator inbox query

## 12. Concurrency and Idempotency Rules

State retry, duplicate request, and conflict behavior.

## 13. Security and Access Control

Define auth, scope, redaction, and approval rules.

## 14. Migration and Rollout Plan

Define rollout order and enablement sequence.

## 15. Acceptance Criteria

Define the root-layer completion gate.

## 16. Ticket Breakdown

List the minimum tickets required to build this layer.

## 17. Bottom Line

Summarize the persistence and root API truth.