Spaces:
Runtime error
Runtime error
| # 🔄 Protocol Versioning & Client Compatibility Matrix Specification | |
| This document defines the semantic versioning scheme, gRPC header handshake protocol, REST/WebSocket schema versioning, and backward compatibility invariants for the Collaborative Fraud Intelligence (CFI) platform. | |
| --- | |
| ## 📌 1. Protocol Versioning Scheme | |
| Protocol releases strictly adhere to **Semantic Versioning (SemVer 2.0.0)** (`MAJOR.MINOR.PATCH`): | |
| - **MAJOR (`X.0.0`)**: Breaking changes to protobuf wire formats ([`fl_service.proto`](../backend/app/infrastructure/grpc/proto/fl_service.proto)), required parameter serialization schemas, or cryptographic primitives (e.g. `v1.x` to `v2.x`). Requires client SDK upgrades. | |
| - **MINOR (`x.Y.0`)**: Backward-compatible feature additions (e.g., new optional telemetry fields, updated drift metrics, additive database columns). | |
| - **PATCH (`x.y.Z`)**: Backward-compatible bug fixes, internal algorithmic optimizations, and performance enhancements. | |
| --- | |
| ## 📑 2. Platform Compatibility Matrix | |
| The domain compatibility bounds are enforced by [`VersionCompatibilityMatrix`](../backend/app/domain/protocol_versioning.py): | |
| | Platform Version | gRPC Wire Protocol | Supported Client SDK Range | Schema Digest (SHA-256) | Lifecycle Status | Deprecation Date | | |
| | :--- | :---: | :---: | :---: | :---: | :---: | | |
| | **v1.0.0** | `1.0.0` | `1.0.0 - 1.99.99` | `a1b2c3d4e5f60718...` | ⚠️ Deprecated | 2026-10-01 | | |
| | **v1.1.0** | `1.1.0` | `1.0.0 - 1.99.99` | `e5f6g7h8i9j01234...` | ⚠️ Maintenance | 2026-12-31 | | |
| | **v2.0.0** | `2.0.0` | `2.0.0 - 2.99.99` | `9988776655443322...` | ✅ **Active Production** | N/A | | |
| | **v2.1.0** | `2.1.0` | `2.0.0 - 2.99.99` | `3344556677889900...` | ✅ **Active Production** | N/A | | |
| | **v3.0.0 (Roadmap)**| `3.0.0` | `3.0.0 - 3.99.99` | *(Planned)* | 🔬 Planned (PQC / zk-SNARK) | 2027-Q2 | | |
| --- | |
| ## 🤝 3. gRPC Header Handshake & Context Metadata | |
| Every gRPC streaming request (`RegisterClient`, `Heartbeat`, `StreamModelParameters`) is intercepted by [`ProtocolVersionInterceptor`](../backend/app/infrastructure/grpc/version_interceptor.py) to validate client protocol metadata: | |
| ``` | |
| ┌────────────────────────────────────────────────────────────────────────────────────────┐ | |
| │ gRPC CLIENT HANDSHAKE METADATA │ | |
| ├──────────────────────────┬──────────────────────────────────┬──────────────────────────┤ | |
| │ METADATA KEY │ EXAMPLE VALUE │ VALIDATION PURPOSE │ | |
| ├──────────────────────────┼──────────────────────────────────┼──────────────────────────┤ | |
| │ `x-cfi-protocol-version` │ `2.1.0` │ SemVer compatibility │ | |
| │ `x-cfi-schema-hash` │ `e3b0c44298fc1c14...` │ Feature schema alignment │ | |
| │ `x-cfi-tenant-id` │ `bank_alpha` │ ContextVar routing │ | |
| │ `x-cfi-mtls-fingerprint` │ `SHA256:7b908f24...` │ X.509 cert binding │ | |
| └──────────────────────────┴──────────────────────────────────┴──────────────────────────┘ | |
| ``` | |
| ### Protocol Rejection & Negotiation Semantics | |
| The server evaluates `(client_version, client_schema_hash)` against the active matrix: | |
| - **`VersionNegotiationStatus.COMPATIBLE`**: Client version satisfies SemVer major alignment and falls within `[min_supported_version, max_supported_version]`. | |
| - **`VersionNegotiationStatus.DEGRADED_COMPATIBLE`**: Version matches, but client feature schema hash differs from the consortium registry (logged as a drift warning). | |
| - **`VersionNegotiationStatus.INCOMPATIBLE`**: Aborts request with `grpc.StatusCode.FAILED_PRECONDITION` (or `OUT_OF_RANGE`), directing the client node to the consortium upgrade portal. | |
| --- | |
| ## 🌐 4. HTTP REST & WebSocket Versioning Invariants | |
| 1. **Path-Based Prefix Routing**: | |
| - Production REST endpoints are namespaced under `/api/v1` or `/v1` (e.g. `/api/v1/score-transaction`, `/api/v1/predict`, `/v1/webhooks/subscriptions`, `/v1/inference/score`). | |
| 2. **RFC 8594 Standard Deprecation & Sunset Headers**: | |
| - `APIVersionLifecycleMiddleware` in `backend/app/main.py` attaches standard version lifecycle headers to all HTTP responses: | |
| ```http | |
| X-API-Version: v1 | |
| Deprecation: Sat, 01 Jan 2026 00:00:00 GMT | |
| Sunset: Sat, 01 Jul 2026 00:00:00 GMT | |
| ``` | |
| 3. **Consortium Deprecation Warning Headers**: | |
| - During rolling upgrades and migration windows, legacy endpoints signal target versions: | |
| ```http | |
| x-cfi-deprecation-warning: Version v2.0.0 will be retired on 2026-10-01. | |
| x-cfi-target-version: v2.1.0 | |
| ``` | |
| 4. **Additive JSON Contracts**: | |
| - Pydantic models across `backend/app/presentation/routers/` enforce additive field updates with default values, preventing serialization crashes in older client libraries. | |
| --- | |
| ## 🧪 5. Automated Test Verification Matrix | |
| Protocol negotiation, SemVer comparison, and lifecycle header adherence are continuously verified: | |
| | Test Suite | File Path | Verified Capabilities | Status | | |
| | :--- | :--- | :--- | :---: | | |
| | **Protocol Versioning** | `backend/tests/unit/test_protocol_versioning.py` | SemVer parsing (`1.0.0 < 2.0.0`), matrix negotiation, gRPC metadata extraction | `3/3 PASSED` | | |
| | **OpenAPI Contract Accuracy** | `backend/tests/unit/test_openapi_contract_accuracy.py` | Route schema accuracy, lifecycle headers, FinCEN export endpoints | `2/2 PASSED` | | |