audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories

docs/modules/concelier/federation-operations.md

@@ -2,9 +2,44 @@
 
 Per SPRINT_8200_0014_0003.
 
+> **Related:** [Bundle Export Format](federation-bundle-export.md) for detailed bundle schema.
+
 ## Overview
 
-Federation enables multi-site synchronization of canonical advisory data between Concelier instances. Sites can export bundles containing delta changes and import bundles from other sites to maintain synchronized vulnerability intelligence.
+Federation enables secure, cursor-based synchronization of canonical vulnerability advisories between StellaOps sites. It supports:
+
+- **Delta exports**: Only changed records since the last cursor are included
+- **Air-gap transfers**: Bundles can be written to files for offline transfer
+- **Multi-site topology**: Multiple sites can synchronize independently
+- **Cryptographic verification**: DSSE signatures ensure bundle authenticity
+
+## Bundle Format
+
+Federation bundles are ZST-compressed TAR archives containing:
+
+| File | Description |
+|------|-------------|
+| `MANIFEST.json` | Bundle metadata, cursor, counts, hash |
+| `canonicals.ndjson` | Canonical advisories (one per line) |
+| `edges.ndjson` | Source edges linking advisories to sources |
+| `deletions.ndjson` | Withdrawn/deleted advisory IDs |
+| `SIGNATURE.json` | Optional DSSE signature envelope |
+
+## Cursor Format
+
+Cursors use ISO-8601 timestamp with sequence number:
+
+```
+{ISO-8601 timestamp}#{sequence number}
+
+Examples:
+2025-01-15T10:00:00.000Z#0001
+2025-01-15T10:00:00.000Z#0002
+```
+
+- Cursors are site-specific (each site maintains independent cursors)
+- Sequence numbers distinguish concurrent exports
+- Cursors are monotonically increasing within a site
 
 ## Architecture
 
@@ -384,3 +419,80 @@ stella feedser canonical get sha256:mergehash...
 6. **Maintain Key Trust:** Regularly rotate and verify federation signing keys
 
 7. **Document Site Policies:** Keep a registry of trusted sites and their policies
+
+## Multi-Site Topologies
+
+### Hub-and-Spoke Topology
+
+```
+           ┌─────────────┐
+           │   Hub Site  │
+           │  (Primary)  │
+           └──────┬──────┘
+                  │
+       ┌──────────┼──────────┐
+       ▼          ▼          ▼
+ ┌──────────┐ ┌──────────┐ ┌──────────┐
+ │  Site A  │ │  Site B  │ │  Site C  │
+ │ (Spoke)  │ │ (Spoke)  │ │ (Spoke)  │
+ └──────────┘ └──────────┘ └──────────┘
+```
+
+### Mesh Topology
+
+Each site can import from multiple sources for redundancy:
+
+```yaml
+federation:
+  import:
+    allowed_sites:
+      - "hub-primary"
+      - "hub-secondary"  # Redundancy
+```
+
+## Verification Details
+
+### Hash Verification
+
+Bundle hash is computed over compressed content:
+
+```
+SHA256(compressed bundle content)
+```
+
+### DSSE Signature Format
+
+DSSE envelope contains:
+
+```json
+{
+  "payloadType": "application/stellaops.federation.bundle+json",
+  "payload": "base64(bundle_hash + site_id + cursor)",
+  "signatures": [
+    {
+      "keyId": "signing-key-001",
+      "algorithm": "ES256",
+      "signature": "base64(signature)"
+    }
+  ]
+}
+```
+
+## Monitoring Metrics
+
+### Key Prometheus Metrics
+
+- `federation_export_duration_seconds` - Export time
+- `federation_import_duration_seconds` - Import time
+- `federation_bundle_size_bytes` - Bundle sizes
+- `federation_items_processed_total` - Items processed by type
+- `federation_conflicts_total` - Merge conflicts encountered
+
+## Security Considerations
+
+1. **Never skip signature verification in production**
+2. **Validate allowed_sites whitelist**
+3. **Use TLS for API endpoints**
+4. **Rotate signing keys periodically**
+5. **Audit import events**
+6. **Monitor for duplicate bundle imports**