hivecast-sdk/packages/federation/COVERAGE.md

# Scenario & Requirement Coverage Map

This document is a lightweight **requirements traceability matrix** mapping the major requirements/scenarios discussed to concrete tests and modules in this TypeScript reference implementation.

The goal is to answer, unambiguously:

- **What is proven by executable tests?**
- **Which scenarios are represented?**
- **What is still out of scope for this POC (i.e., production engineering / operations)?**

## Key Terms

- **Backbone / public broker**: the globally reachable NATS cluster (or any shared pub/sub fabric) used as a rendezvous point.
- **Mailbox topic**: a wildcard-free topic unique per realm (and optionally per shard) that receives cross-realm envelopes.
- **EdgeGateway**: the boundary component that terminates the backbone protocol, applies guard rails, then bridges into the realm's internal bus.
- **Internal bus**: per-realm message bus (in-memory, local broker, etc.) where atomic component topics live (`mx/1/<realm>/<toPath>`).
- **Matrix-3 compatibility / legacy**: `public.ingress.<realm>` mailbox + legacy request/reply envelopes.
- **MXENV/1**: structured envelope with explicit `msgType` and nested endpoints (`to`, `from`, `replyTo`).

## What This POC Proves

### 1) Matrix URLs are pasteable and canonicalize

**Requirement**: Matrix addresses should be URL-like; tolerant parsing supports both legacy compact and explicit `/-/` delimiter form.

**Modules**:
- `src/uri.ts`

**Tests**:
- `tests/unit/uri.test.ts`
  - legacy compact URI with realm/mount/atom
  - segmented MXURI/1 with `/-/`
  - tab normalization (`~tab/<id>` → `.<tab>.<id>` realm)
  - query param parsing (`?k=v` → defaults/body)
  - local-only legacy URI (no realm)
  - invalid URI rejection

### 2) Topic naming aligns with your constraints

**Requirement**: Internal topics preserve atomic component paths; mailbox topics do not require wildcards.

**Modules**:
- `src/topics.ts` (mailboxes, internal topics, route inbox topics)
- `src/engine/mxesc1.ts` (escaping)

**Tests**:
- `tests/unit/topics.test.ts`
  - legacy ingress roundtrip
  - MX ingress roundtrip
  - internal topic composition (atomic component preserved)
  - route inbox derivation
- `tests/unit/mxesc1.test.ts`

### 3) Cross-realm request/reply works over an isolated broker fabric

**Requirement**: Broker islands are isolated. Cross-realm request/reply must work by using mailbox topics + envelopes + EdgeGateway bridging, without any wildcard subscription on the backbone.

**Modules**:
- `src/runtime/edge_gateway.ts`
- `src/cross_realm_client.ts`
- `src/runtime/component_host.ts` (internal handler adapter)

**Tests**:
- `tests/integration/request_reply.test.ts`
  - local-to-local request/reply (single realm, internal bus)
  - cross-realm Cmd/Result via backbone (legacy Matrix-3 mailboxes)
  - cross-realm Cmd/Result via backbone (MXENV/1 mailboxes)

### 4) Strangler-fig dual-rail migration is supported

**Requirement**: During migration, a realm can subscribe to *both* mailbox namespaces and accept both envelope types.

**Modules**:
- `src/wire_profile.ts`
- `src/runtime/edge_gateway.ts` (dual subscription)

**Tests**:
- `tests/integration/request_reply.test.ts`
  - mxenv1 EdgeGateway accepts legacy request and replies on legacy mailbox
  - matrix3 EdgeGateway accepts MXENV/1 request and replies on MX mailbox

### 5) No-handler / missing component does not leak subscriptions

**Requirement**: If the internal component does not respond (missing handler, crash, bug), the EdgeGateway must not leak per-request subscriptions forever; callers should receive an error.

**Modules**:
- `src/runtime/edge_gateway.ts` (`internalTimeoutMs`)

**Tests**:
- `tests/integration/request_reply.test.ts`
  - internal handler timeout produces error reply (mxenv1)
  - internal handler timeout produces error reply (legacy)

### 6) Streaming subscriptions are leased and renewable

**Requirement**: Cross-realm subscriptions must exist (Sub/Unsub), have lease/expiry semantics, and support refresh.

**Modules**:
- `src/runtime/federation.ts` (subscription state machine)

**Tests**:
- `tests/integration/subscription.test.ts`
  - subscribe → event forwarded → unsubscribe stops stream
  - lease expiry prevents forwarding
  - refresh extends lease

### 7) Session directory enables unsolicited push to tabs

**Requirement**: Tabs are ephemeral leaf realms; principals may have multiple active tabs; agents/services must discover active tab realms to push events.

**Modules**:
- `src/runtime/directory.ts` (in-memory directory + protocol facade)

**Tests**:
- `tests/integration/directory.test.ts`
  - tab registers under principal; agent lookup + push
  - spoof prevention (tab realm cannot spoof another)
  - expiry removes stale registrations
  - heartbeat extends lease

### 8) Discovery supports “direct broker if available, else backbone”

**Requirement**: If a realm exposes a direct endpoint (e.g., publicly reachable broker / websocket gateway), use it; otherwise fall back to backbone mailbox addressing.

**Modules**:
- `src/runtime/discovery.ts`
- `src/runtime/resolved_client.ts`

**Tests**:
- `tests/integration/discovery.test.ts`
  - prefer direct endpoint when available
  - fall back when direct publish fails

### 9) Hierarchical routing overlay exists (multi-hop)

**Requirement**: Support hierarchical realm paths with multi-hop forwarding **without broker wildcards**, using explicit route inbox topics.

**Modules**:
- `src/runtime/router.ts`

**Tests**:
- `tests/integration/router.test.ts`
  - deliver across siblings via common ancestor
  - TTL exhaustion fails
  - unknown route fails
  - duplicate msgId is dropped

### 10) Security guard rails exist (protocol-level)

**Requirement**: Public transport needs basic guard rails to avoid being an open relay / amplification mechanism.

**Modules**:
- `src/security/*`
- `src/runtime/edge_gateway.ts` (enforcement points)

**Tests**:
- `tests/integration/security.test.ts`
  - anti-open-relay drop (replyTo.realm must equal from.realm)
  - replay cache dedup (msgId)
  - rate limiting (mxenv1 → Nack)
  - policy denial (mxenv1 → Nack)
  - policy denial (legacy → error reply)
  - rate limiting (legacy → error reply)

## What This POC Does NOT Claim

These items are intentionally out-of-scope for this “prove the routing semantics” implementation:

- **Real broker deployment**: TLS, auth, ACLs, server-side throttling, persistence, JetStream delivery guarantees.
- **JWKS + JWT validation**: this repo carries principal/auth fields in MXENV/1 but does not implement key distribution or signature verification.
- **Global directory/discovery service**: directory is in-memory; production would be distributed and secured.
- **NAT traversal**: the design assumes the edge runtime can reach *some* rendezvous (backbone) or a direct endpoint; it does not implement TURN-like traversal.
- **Guaranteed delivery / store-and-forward**: this is router-like, not email-like. Offline recipients may miss events unless you add persistence.