Skip to main content

Contract Drift Sentinel

Relay prevents contract drift by versioning schemas and enforcing diffs in CI/runtime.

Workflow Overview​

  • Manifests store contract versions (function_contract_versions table) with status/reviewer.
  • CLI command relay contract diff compares working tree vs published version and emits JSON reports.
  • CI pipeline runs scripts/contracts/run_ci_contract_diff.sh; breaking changes fail unless override label present.
  • Runtime middleware samples responses and validates against active contract, emitting contract.drift events.

Console & Approvals​

  • Console admin view lists pending contract changes with diff viewer.
  • Reviewers approve/reject; approvals invalidate policy cache and notify #relay-contracts.
  • Drift incidents appear in the Executions tab > “Contracts” panel with sample payload + recommended fix.

Runbooks​

  1. Breaking change flagged in CI
    • Review diff output artifact.
    • Decide: update contract (version bump) or adjust implementation to remain compatible.
    • Add approval label/override only after design review.
  2. Runtime drift detected
    • Inspect contract.drift event (Datadog dashboard “Relay / Contract Sentinel”).
    • Reproduce via staging; if confirmed bug, roll back or hotfix.
    • Update contract version if intentional change (requires approval).

CLI Usage​

relay contract diff --function my-team/payments \
  --contract docs/contracts/payments.yml \
  --format json --output reports/contract_diff.json

Exit codes:

  • 0 = no breaking change
  • 10 = non-breaking additions
  • 20 = breaking change (blocks CI)

Observability​

  • Datadog monitors contract.drift events by tenant/function.
  • Slack webhook #relay-contracts receives alerts.
  • Audit trail stored in audit_events table with context payloads.
  • Design: dev_process/planning/FN-058_CONTRACT_SENTINEL_DESIGN.md
  • Tests: tests/integration/execution/test_contract_drift.py, CLI unit tests.
  • Registry service: src/services/contract_registry.py
  • CI script: scripts/contracts/run_ci_contract_diff.sh

Contacts​

  • Owner: Core Platform (contract governance)
  • Escalation: Developer Experience / Support for customer-facing issues

Keep this runbook aligned with CLI/console changes and approval workflows.