> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Contract Validation Checklist

> Version: 1.0.0 Last Updated: 2026-01-15 Constitution Reference: Section 1.3 (Integration Patterns)

**Version:** 1.0.0\
**Last Updated:** 2026-01-15\
**Constitution Reference:** Section 1.3 (Integration Patterns)

***

## Overview

Use this checklist when adding or modifying integration contracts to ensure completeness and consistency. This serves as a quality gate before merging integration documentation.

**Related Documents:**

* `EVENT_CONTRACTS.md` - Event-based integrations
* `API_CONTRACTS.md` - API contracts
* `PLATFORM_INTEGRATION_LAYERS.md` - Platform integration layers
* `CROSS_CORE_INTEGRATIONS.md` - Integration matrix

***

## Event Contract Validation

Complete this checklist when adding a new event to `EVENT_CONTRACTS.md`:

### Event Definition

* [ ] **Event name** follows `{core}_{entity}_{action}` convention (canonical format, snake\_case, past tense)
* [ ] **Channel** specified (`domain_events`, `automation_trigger`, `fa_events`, etc.)
* [ ] **Publisher** identified with core and feature ID
* [ ] **Subscribers** listed with their actions
* [ ] **Status** indicator accurate (✅ Implemented / 📝 Planned / 🟡 In Progress)
* [ ] **Spec reference** linked to specification document

### Payload Schema

* [ ] **`event_type`** field included (string, matches event name)
* [ ] **`organization_id`** field included (uuid, required for tenant isolation)
* [ ] **`timestamp`** field included (timestamptz)
* [ ] **`site_id`** field included if site-scoped
* [ ] **`user_id`** field included if user-initiated action
* [ ] **`correlation_id`** documented if event chaining is possible
* [ ] **All fields** have TypeScript types and descriptions
* [ ] **No PII/PHI** in payload (use IDs only)

### Implementation

* [ ] **Trigger conditions** documented (when event fires)
* [ ] **SQL trigger code** provided with SECURITY DEFINER
* [ ] **Consumer actions** listed with status
* [ ] **Testing requirements** defined

### Backward Compatibility

* [ ] **Breaking changes** documented (if any)
* [ ] **Migration guide** provided (if replacing existing event)
* [ ] **Deprecation date** noted (if applicable)

***

## API Contract Validation

Complete this checklist when adding a new API to `API_CONTRACTS.md`:

### API Definition

* [ ] **Endpoint** fully specified (`/api/v1/{core}/{resource}`)
* [ ] **HTTP method** documented (GET, POST, PUT, DELETE, PATCH)
* [ ] **Provider** identified with core and feature ID
* [ ] **Consumer(s)** listed
* [ ] **Status** indicator accurate
* [ ] **Spec reference** linked

### Request Documentation

* [ ] **Path parameters** documented with types
* [ ] **Query parameters** documented with types, defaults, descriptions
* [ ] **Request body schema** provided as TypeScript interface
* [ ] **Required vs optional** fields clearly distinguished
* [ ] **Content-Type** specified

### Response Documentation

* [ ] **Success response schema** provided (200/201)
* [ ] **Error response schema** follows standard format
* [ ] **All HTTP status codes** documented
* [ ] **Error codes** listed with descriptions and resolutions

### Security & Operations

* [ ] **Authentication** requirements documented (JWT)
* [ ] **Tenant context enforcement** described
* [ ] **Rate limiting** values and headers documented
* [ ] **PII/PHI logging guidelines** included (what can/cannot be logged)
* [ ] **Permission requirements** documented (if applicable)

### Quality & Performance

* [ ] **Usage example** provided (working TypeScript code)
* [ ] **Performance SLA** documented (p50, p95, p99)
* [ ] **Timeout** recommendation included
* [ ] **Retry semantics** documented (safe to retry?)
* [ ] **Idempotency** behavior documented (for write operations)
* [ ] **Caching strategy** documented (if applicable)

### Testing

* [ ] **Testing requirements** listed
* [ ] **Error scenarios** covered

***

## Platform Integration Layer Validation

Complete this checklist when adding a new layer to `PLATFORM_INTEGRATION_LAYERS.md`:

### Layer Definition

* [ ] **Layer name** and location documented (`/src/platform/{layer}/`)
* [ ] **Purpose** clearly described (1-2 sentences)
* [ ] **Consumer cores** listed
* [ ] **Status** indicator accurate
* [ ] **Version** noted

### Public API

* [ ] **All exports** documented (components, hooks, utilities)
* [ ] **TypeScript interfaces** provided for public types
* [ ] **Import path** documented (`@/platform/{layer}`)

### Usage

* [ ] **Usage example** provided (working code)
* [ ] **Common patterns** documented
* [ ] **Anti-patterns** listed (what NOT to do)

### Dependencies

* [ ] **Internal dependencies** listed (other platform layers)
* [ ] **External dependencies** documented (npm packages)
* [ ] **Core dependencies** noted (if any)

***

## Cross-Core Integration Validation

Complete this checklist when adding an integration to `CROSS_CORE_INTEGRATIONS.md`:

### Matrix Entry

* [ ] **Row added** to integration matrix
* [ ] **Publisher/Provider** correctly identified
* [ ] **Consumer** correctly identified
* [ ] **Integration type** specified (Platform Layer / Event / API)
* [ ] **Status** accurate (✅ / 📝 / 🟡)
* [ ] **Documentation link** provided

### Documentation

* [ ] **Contract documented** in appropriate file:
  * Event → `EVENT_CONTRACTS.md`
  * API → `API_CONTRACTS.md`
  * Platform Layer → `PLATFORM_INTEGRATION_LAYERS.md`
* [ ] **Both publisher and consumer** perspectives documented
* [ ] **Data flow** described

***

## Pre-Merge Checklist

Before merging integration documentation changes, verify:

### Documentation Completeness

* [ ] All new integrations added to `CROSS_CORE_INTEGRATIONS.md` matrix
* [ ] Contract documented in appropriate contracts file
* [ ] Related spec references updated
* [ ] README.md overview updated (if new pattern introduced)

### Cross-Reference Validation

* [ ] Links between documents work correctly
* [ ] Spec references are valid paths
* [ ] Version numbers consistent across documents

### Review Requirements

* [ ] Self-review completed using this checklist
* [ ] Architecture review requested (for new patterns)
* [ ] Security review requested (for sensitive data integrations)

***

## Quick Reference: Integration Pattern Selection

Use this guide to choose the right integration pattern:

| Scenario                             | Pattern            | Document                         |
| ------------------------------------ | ------------------ | -------------------------------- |
| Real-time data needed                | API Contract       | `API_CONTRACTS.md`               |
| Async notification                   | Event Contract     | `EVENT_CONTRACTS.md`             |
| Shared UI component                  | Platform Layer     | `PLATFORM_INTEGRATION_LAYERS.md` |
| Database function                    | API Contract (RPC) | `API_CONTRACTS.md`               |
| Cross-cutting capability             | Platform Layer     | `PLATFORM_INTEGRATION_LAYERS.md` |
| Loose coupling, eventual consistency | Event Contract     | `EVENT_CONTRACTS.md`             |

***

## Common Validation Failures

### Event Contracts

| Failure                              | Resolution                                |
| ------------------------------------ | ----------------------------------------- |
| Missing `organization_id` in payload | Add field - required for all events       |
| PII in payload (names, emails)       | Replace with IDs only                     |
| No subscriber documented             | Add subscriber or question need for event |
| Missing SECURITY DEFINER             | Add to trigger function                   |

### API Contracts

| Failure                   | Resolution                         |
| ------------------------- | ---------------------------------- |
| Missing tenant validation | Add `pf_has_org_access()` check    |
| No error response schema  | Add standard error format          |
| Missing rate limiting     | Add limit and header documentation |
| PII logging allowed       | Update logging guidelines          |

### Platform Layers

| Failure               | Resolution                   |
| --------------------- | ---------------------------- |
| Direct core import    | Use platform layer interface |
| Missing usage example | Add working code example     |
| Undocumented export   | Add to public API list       |

***

## Versioning

| Version | Date       | Changes         |
| ------- | ---------- | --------------- |
| 1.0.0   | 2026-01-15 | Initial version |

***

## See Also

* `specs/_templates/INTEGRATION_CONTRACT_TEMPLATE.md` - Event, API, and Database Function contract templates (combined)
* `docs/architecture/patterns/INTEGRATION_EXAMPLES.md` - Code examples
* `constitution.md §1.3` - Integration patterns

***

**Document Owner:** Platform Foundation\
**Review Cadence:** Quarterly\
**Next Review:** 2026-04-15