SuperGraph — Federated Graph Intelligence

SuperGraph is a native P8G module that enables a single Purple8 Hyper Graph instance to coordinate explicitly approved queries across independently deployed P8G instances. It is an SDK-only bounded router, not a distributed query planner.

The key insight

SuperGraph does not replace P8G — it extends it. Peer state and approvals are currently in memory, not persisted Journey events. Partial results identify missing peers rather than silently claiming completeness.

"SuperGraph is P8G knowing about other P8Gs."

---

Why SuperGraph Exists

Large enterprises do not run a single graph. They run many — across divisions, regions, regulatory boundaries, and technology stacks. Without federation:

• Cross-domain queries require manual data extraction and reconciliation
• Duplicate entities accumulate across systems with no canonical source
• Graph size is bounded by a single instance's capacity
• Foreign graph systems (Neo4j, Amazon Neptune, Microsoft Graph) are permanently siloed

SuperGraph addresses explicitly approved cross-P8G requests without modifying the core planner. Foreign-system ingestion and export belong to connectors and egress, not this router.

---

Architecture

Only one P8G instance runs SuperGraph — the coordinator. All other instances are peers. Peers do not need SuperGraph installed. They only need to be reachable.

User Query
    ↓
P8G SuperGraph Instance  ← coordinator (only instance with SuperGraph active)
    ├── queries itself natively
    ├── queries P8G Peer A  (another P8G instance)
    ├── queries P8G Peer B  (another P8G instance)
         ↓
    Unified P8G hypergraph result

If the SuperGraph instance is offline, federation stops. Peers continue operating independently. This is intentional — there is no hidden coordination happening without the designated coordinator.

---

Discovery Tiers

SuperGraph supports four peer discovery modes. None activate without explicit administrator approval. Each tier is a superset of the previous — you must enable lower tiers before higher ones can be activated.

Tier	Mode	Default	Description
1	Static Registry	✅ Always available	Admin manually declares all peer URLs in config. No automation. Every connection is explicit and auditable.
2	Service Discovery	❌ Opt-in	Instances discovered via DNS/Consul/etcd. Discovery surfaces candidates — it does not connect automatically. Each discovered instance still requires manual approval.
3	Central Coordinator	❌ On-demand only	SuperGraph maintains the authoritative peer registry. Other instances check in to get the approved peer list. Not a persistent service — activates for a federated query, shuts down after. Requires Tier 1 + 2.
4	Gossip Protocol	❌ Explicit unlock required	Instances propagate peer knowledge to each other. Fully decentralised. Every gossip message is signed and logged. Not recommended for regulated industries. Requires Tier 1 + 2.

Regulated industries

Tiers 2, 3, and 4 are disabled by default. For industries subject to GDPR, HIPAA, FedRAMP, or equivalent frameworks, Tier 1 (Static Registry) is the recommended operating mode. Your CISO can confirm that no automatic peer discovery or gossip occurs without explicit configuration.

---

Peer Approval

Enabling a tier does not connect anything. Every peer relationship requires explicit approval before it is written to the registry.

P8G's role is to emit, wait, receive, and act — not to own the approval workflow. The approval process is yours.

How it works

SuperGraph Journey (closed loop)
    ├── 1. Peer connection requested
    │         ↓
    ├── 2. P8G emits approval event → your workflow system (webhook/callback)
    │         ↓
    ├── 3. Journey pauses — not blocking, other journeys continue
    │         ↓
    ├── 4. Your system handles approvals (however many approvers you need)
    │         ↓
    ├── 5. Decision received via callback
    │         ↓
    └── 6. Journey resumes (approved) or terminates (denied)
         Peer written to registry — or not.

P8G does not dictate how many approvers are required, who they are, or what tool manages the workflow. Wire it to ServiceNow, Jira, email, or a custom system — P8G only cares about the callback decision.

Approval micro-module

from purple8_graph.supergraph import ApprovalConfig, ApprovalManager

approval = ApprovalManager(
    config=ApprovalConfig(
        webhook_url="https://your-workflow-system.example.com/p8g/peer-approval",
        timeout_hours=72,          # deny automatically if no decision after 72h
        callback_secret="...",     # HMAC-signed callbacks only
    )
)

Separate query authority

Registry approval permits peer selection; it does not authorize queries. Every execution also requires an approved, unexpired scope="query" grant bound to the executor's tenant and the peer's exact address:

token = approval.request_approval(
    instance_id="p8g-legal-eu",
    requested_by="operator",
    scope="query",
    tenant_id="legal",
    peer_address="https://p8g-legal.example.com",
    domains=["legal"],
    valid_for_seconds=900,
)
# Your trusted approval integration must approve this token before execution.

The lease starts when the decision is approved. Restricted-domain grants require an explicit requested-domain subset; omitting domains is an unrestricted request and is denied by a restricted grant. Domain selection constrains routing, not query-language semantics or remote row access. The destination must independently authenticate and authorize the query.

The executor checks authority both before enqueueing and immediately before HTTP dispatch. It refuses changed destinations, revoked grants and non-P8G adapters; HTTP redirects are not followed. Revocation cannot recall an already dispatched request. Use approval.revoke_query_approval(token, revoked_by="operator") to revoke a query lease, and approval.close() on shutdown.

Grants are in-memory and fail closed after restart or manager shutdown. No REST/MCP approval callback or federation surface is supplied by these SDK classes. An integration must derive the executor tenant from authenticated server context, not a caller-controlled request field.

---

Partial Results & Disconnection Handling

If a peer becomes unreachable mid-traversal, SuperGraph does not fail the query. It returns everything it gathered, with a clear disclaimer.

from purple8_graph.supergraph import SuperGraphExecutor, SuperGraphStitcher

executor = SuperGraphExecutor(
    registry, approval_manager=approval, tenant_id="legal",
)
peer_results = executor.execute(
    """
    MATCH (doc:Document)-[:EXTRACTED_CONCEPT]->(concept:Concept)
          -[:USED_IN]->(design:DesignElement)
    RETURN doc, concept, design
    """,
    journey_id="j-2026-001",
    domains=["legal"],
)

stitcher = SuperGraphStitcher()
result = stitcher.stitch(peer_results, journey_id="j-2026-001")

print(result.status)         # "complete" | "partial" | "empty"
print(result.total_records)  # everything retrieved before disconnection
print(result.disclaimer)     # non-empty only when partial/empty

Result envelope

{
  "status": "partial",
  "data": [ "...merged, deduplicated records from all successful peers..." ],
  "sources": ["p8g-coordinator", "p8g-legal-eu-west-2"],
  "disclaimer": "This result is incomplete. One or more peer instances were unreachable or revoked during this query. Data from the following instances is absent: p8g-legal-eu-west. Re-run after those peers are restored or removed.",
  "total_records": 42,
  "unreachable": [
    {
      "instance_id": "p8g-legal-eu-west",
      "address": "http://p8g-legal:8000",
      "adapter": "p8g",
      "reason": "timeout",
      "last_queried_at": 1743065911.42
    }
  ]
}

The user always knows exactly what is missing and why. Silent gaps do not exist.

---

Peer protocol boundary

Only adapter="p8g" is executable. Legacy foreign-adapter path configuration does not enable foreign execution. Use connectors for inbound data and egress for outbound integrations.

Before enabling production federation, validate end-to-end authentication, query shape, and response compatibility against each deployed Purple8 peer.

---

Journey Integration

The federation classes (PeerRegistry, ApprovalManager, SuperGraphExecutor, SuperGraphStitcher) are in-memory Python objects. Federation state (peer registry, approval status) lives for the lifetime of the coordinator process; wire your persistence or audit log around ApprovalManager's callbacks when you require a durable, queryable history of peer approvals.

---

Licensing

SuperGraph is an Enterprise / Custom (Self-Hosted) feature of Purple8 Hyper Graph.

Feature	Developer (Self-Hosted Free)	Enterprise / Custom (Self-Hosted)
Scale & Agent Quota	Up to 50K nodes, 1 MCP agent	Unlimited nodes & MCP agents, full compliance/HA
Tier 1 — Static Registry	❌	✅
Tier 2 — Service Discovery	❌	✅
Tier 3 — Central Coordinator	❌	✅
Tier 4 — Gossip Protocol	❌	✅ (explicit unlock)
Partial result handling	❌	✅
Approval micro-module	❌	✅

---

Design Principles

• P8G core is untouched. SuperGraph only uses P8G's public interfaces.
• Nothing connects without approval. Discovery ≠ connection.
• One coordinator. Only the SuperGraph instance can initiate federation.
• Honest partial results. Missing data is always declared, never silently omitted.
• Your approval workflow. P8G emits and waits — it does not own the process.
• Durable audit is an integration boundary. SDK state is in memory; persist approval history through a trusted integration when required.

---

See Also

• Journey Engine — durable local workflows and human review
• Architecture — P8G core internals that SuperGraph builds on
• Multi-tenancy — tenant isolation within a single P8G instance
• Clustering — high availability within a single P8G deployment