vault backup: 2026-02-27 10:43:35

Test/EventKit/04 - Federation Architecture.md

@@ -226,6 +226,45 @@ Assets can be **permanently transferred** between instances (e.g. selling equipm
 | 4    | Seller's instance marks asset as "Transferred" (end of local history) |
 | 5    | Buyer's instance creates asset with full imported history             |
 
+### Federation Versioning
+
+The federation protocol relies on **Protobuf's built-in backward compatibility**:
+
+- New fields are **additive** — old instances ignore unknown fields
+- Deprecated fields are **never removed**, only marked obsolete
+- Breaking changes are **documented** and communicated to partners
+- No formal version negotiation during handshake — keep it simple
+
+### Dispute Resolution
+
+Equipment condition disputes are handled **out-of-band** (phone, email). EventKit provides supporting evidence:
+
+| Feature                    | Description                                            |
+| -------------------------- | ------------------------------------------------------ |
+| Timestamped condition logs | Before/after condition recorded at dispatch and return |
+| Photo evidence             | Optional photos attached to condition logs             |
+| Audit trail                | Full history of who scanned what and when              |
+| Dispute handling           | Out-of-band — no formal in-app dispute workflow        |
+
+### Federation Downtime Handling
+
+| Behaviour              | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| **Outbox queue**       | Pending requests queued when partner is offline         |
+| **Auto-retry**         | Automatic retry when partner comes back online          |
+| **Admin notification** | Notify admin after configurable hours of failed retries |
+| **Manual retry**       | Option to manually retry or cancel queued requests      |
+
+### Federation Data Visibility
+
+How much partner inventory data is visible is **configurable per trust level**:
+
+| Trust Level  | Visibility                                              |
+| ------------ | ------------------------------------------------------- |
+| **Minimal**  | Real-time availability queries only                     |
+| **Standard** | Cached summary (category counts, general availability)  |
+| **Full**     | Product catalogue shared (not individual asset details) |
+
 ---
 
 ## Global Asset Identity