Changelog & Versioning

This page tracks engine versions, API changes, and backward compatibility.

Versioning Policy

Component Versioning Compatibility
API /v1, /v2, etc. Breaking changes = new version
Decision Engine SemVer (v1.0.0) Weight changes = minor bump
Webhooks Schema versioned Additive only within version

Backward Compatibility

Within a major API version:

  • ✓ New endpoints may be added
  • ✓ New optional fields may be added to responses
  • ✓ New optional fields may be added to requests
  • ✗ Existing fields will not be removed
  • ✗ Existing field types will not change
  • ✗ Required fields will not become required

Current Versions

Component Version Status
API v1 Stable
Decision Engine v1.0.0 Stable
Webhook Schema v1 Stable

Changelog

2025-01-15 — v1.0.0 (Initial Release)

API

  • Initial release of /v1 endpoints
  • Escrow lifecycle: CREATE → FUNDED → IN_PROGRESS → DELIVERED → COMPLETED
  • Dispute flow: OPEN → EVIDENCE_LOCKED → RESOLVED
  • HMAC authentication with replay protection
  • Idempotency support for all POST endpoints

Decision Engine

  • Initial weight configuration (v1.0.0)
  • Signals: deadline_met, deliverable_submitted, evidence_balance, completion_ratio
  • Operator override within ±30%

Webhooks

  • HMAC-signed webhook delivery
  • Exponential backoff retry (5 attempts)
  • Dead-letter after max retries

Deprecation Policy

When a version is deprecated:

  1. Announcement made at least 6 months in advance
  2. Deprecation header added to all responses
  3. Migration guide published
  4. Support continues for 12 months after deprecation

We do not break /v1 without a new /v2.

Next: Legal & Liability →