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.