Contracts¶

contracts/ is the only directory in the repository that humans author directly. Every other artifact — service code, Helm charts, Prometheus alerts, CI pipelines — is either derived from these files by a script or generated by an AI agent given these files as input.

This is the machine-readable statement of what the system must do. Implementation is downstream of it.

Structure¶

contracts/
├── slas/                      # Numeric SLA targets (availability, latency, throughput)
├── domain-invariants/         # Business rules that can never be violated
└── event-schemas/             # Canonical JSON Schemas for all domain events

SLA Targets¶

Each service has a YAML file in contracts/slas/ that defines the numeric promises the service makes. These flow downstream via a deterministic script to:

observability/slos/ — measurement windows and error budgets
observability/alerts/ — PrometheusRule burn rate alerts

The key property: a target is written once and only once. The validate-contracts.sh script checks that every SLA file has a matching SLO file and a matching alert file. Drift is caught in CI.

SLA file	Service	Key targets
`orders-sla.yaml`	Orders	99.95% availability, 500ms p99, 5s saga compensation max
`inventory-sla.yaml`	Inventory	99.9% availability, 100ms read p99, 0 oversell tolerance
`customers-sla.yaml`	Customers	99.9% availability, 300ms p99, 30-day GDPR deletion
`platform-sla.yaml`	Platform	EKS 99.95%, RTO 4h, RPO 15min
`fulfillment-sla.yaml`	Fulfillment Gateway	99.9% dispatch success, 2s WMS p99, circuit breaker thresholds

Domain Invariants¶

Business rules that the system must never violate, expressed in plain language and numbered for traceability. Each invariant ID (INV-ORD-001, INV-INV-003, etc.) maps to:

A named test in services/*/tests/domain/
A guard in the aggregate root or command handler
A compliance check in the architectural review (ai-agents/tasks/agent/architectural-compliance-review.md)

Invariants file	Service	Key invariants
`orders-invariants.md`	Orders	10 invariants: no empty orders, valid transitions, stock before payment, immutable after confirmation
`inventory-invariants.md`	Inventory	6 invariants: no oversell, no over-release, Redis not authoritative for writes
`customers-invariants.md`	Customers	5 invariants: unique emails, suspended customer blocks orders, cascading deletion

Event Schemas¶

Canonical JSON Schemas (Draft-07) for all domain events. These are the published language of the system — the format that every producer must emit and every consumer must accept.

Each schema has a matching TypeScript interface in services/*/src/domain/events/. The validate-contracts.sh script checks that the TypeScript class exists for every schema file.

Schema	Topic	Owner
`OrderPlaced.json`	`chakra.orders.placed`	orders-team
`OrderCancelled.json`	`chakra.orders.cancelled`	orders-team
`StockReserved.json`	`chakra.inventory.reserved`	inventory-team
`CustomerRegistered.json`	`chakra.customers.registered`	customers-team

Validation in CI¶

The validate-contracts.sh script runs on every push and checks:

Every contracts/slas/*.yaml has a matching observability/slos/*.yaml
Every contracts/slas/*.yaml has a matching observability/alerts/*-burnrate.yaml
Every contracts/event-schemas/*.json has a matching TypeScript event class in services/
Every ADR file appears in docs/adrs/README.md

# Run locally
bash tooling/validate-contracts.sh

All 20 checks currently pass. See ADR-0001 for the contract-first development decision.