---
id: 10015
title: '[Sub-Epic] Dynamic Topology — Unified vs. Federated Routing'
state: CLOSED
labels:
  - epic
  - ai
  - architecture
assignees: []
createdAt: '2026-04-14T16:43:34Z'
updatedAt: '2026-05-22T20:13:25Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10015'
author: tobiu
commentsCount: 2
parentIssue: 9999
subIssues:
  - '[x] 10001 Dynamic Topology: Unified vs. Federated Routing'
  - '[x] 10007 Memory Core: Bypass Database Initialization in Unified Mode'
  - '[x] 10008 Playwright Test Coverage: Unified Monolithic Topology'
  - '[x] 10009 Playwright Test Coverage: Federated Cloud Topology'
subIssuesCompleted: 4
subIssuesTotal: 4
blockedBy: []
blocking: []
closedAt: '2026-05-22T20:13:25Z'
---
# [Sub-Epic] Dynamic Topology — Unified vs. Federated Routing

## Objective
Enable seamless switching between a single-instance local ChromaDB deployment and a federated multi-instance cloud deployment via a unified configuration flag.

## Rationale
Solo developers use a single ChromaDB instance (port 8000). Enterprise teams may deploy KB and Memory Core as separate services behind an OAuth gateway. The topology flag (`NEO_CHROMA_UNIFIED`) must transparently route ChromaDB client connections without changing service logic.

## Scope
This sub-epic groups the following existing tickets:
- #10001 — Dynamic Topology: Unified vs. Federated Routing
- #10007 — Memory Core: Bypass Database Initialization in Unified Mode
- #10008 — Playwright Test Coverage: Unified Monolithic Topology
- #10009 — Playwright Test Coverage: Federated Cloud Topology

Parent Epic: #9999
Origin Session ID: 69b726ca-97c8-406c-9106-c63b6642c4c0

## Timeline

- 2026-04-14T16:43:35Z @tobiu added the `epic` label
- 2026-04-14T16:43:35Z @tobiu added the `ai` label
- 2026-04-14T16:43:36Z @tobiu added the `architecture` label
- 2026-04-14T16:43:55Z @tobiu added parent issue #9999
- 2026-04-14T16:44:12Z @tobiu added sub-issue #10001
- 2026-04-14T16:44:13Z @tobiu added sub-issue #10007
- 2026-04-14T16:44:15Z @tobiu added sub-issue #10008
- 2026-04-14T16:44:17Z @tobiu added sub-issue #10009
- 2026-04-14T16:44:56Z @tobiu cross-referenced by #10005
- 2026-04-20T10:40:37Z @tobiu cross-referenced by PR #10121
- 2026-04-20T11:13:56Z @tobiu cross-referenced by #9748
- 2026-04-20T11:19:03Z @tobiu cross-referenced by PR #10122
- 2026-04-20T13:32:29Z @tobiu cross-referenced by PR #10123
- 2026-04-20T13:53:15Z @tobiu cross-referenced by #10127
- 2026-04-20T14:38:15Z @tobiu cross-referenced by PR #10128
- 2026-04-20T15:26:36Z @tobiu cross-referenced by PR #10130
- 2026-04-21T18:21:03Z @tobiu cross-referenced by #10016
- 2026-04-23T22:22:29Z @neo-opus-ada cross-referenced by #9999
- 2026-04-23T22:46:18Z @neo-opus-ada cross-referenced by PR #10268
- 2026-04-23T23:27:54Z @neo-opus-ada cross-referenced by #10270
- 2026-04-23T23:32:12Z @tobiu referenced in commit `f70c48f` - "feat(memory-core): surface effective chromadb topology in /health (#10127) (#10268)

Extends HealthService.healthcheck() with a database.topology observability
block exposing mode (unified|federated), coordinates ({host, port}), and
resolvedVia (the config key path the resolver read). Closes the in-band
observability gap for sub-epic #10015: operators can now verify
NEO_CHROMA_UNIFIED=true took effect from a single healthcheck call,
instead of inspecting logs or re-running config through node -e.

- Add module-scope buildTopologyBlock(cfg) as a pure projection, mirroring
  the buildIdentityBlock precedent from #10176. Delegates coordinate
  resolution to ChromaManager.resolveChromaCoordinates (extracted in #10001
  specifically for this kind of aggregation) and computes resolvedVia
  from chromaUnified. Defensive try/catch keeps healthcheck resilient when
  the resolver throws on missing engines.kb.chroma — surfaces misconfig as
  observable data (coordinates: null, error: <message>), per PR #10227's
  surface-don't-obscure principle.
- Wire buildTopologyBlock(aiConfig) into #performHealthCheck's payload
  under database.topology, before connectivity checks so operators still
  see target coordinates when status is unhealthy.
- Extend HealthService.spec.mjs with three topology tests covering
  federated mode, unified mode, and unified-with-missing-kb-chroma misconfig.
- Document the full healthcheck response shape in learn/agentos/MemoryCore.md,
  folding in the deferred doc pass from #10001 + #10007 and covering the
  #10176 identity and #10017 migration observability blocks.

Resolves #10127

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-04T13:21:56Z @neo-gpt cross-referenced by #10691
- 2026-05-04T13:24:45Z @neo-gpt cross-referenced by #10694
- 2026-05-06T08:40:08Z @neo-opus-ada cross-referenced by #10805
- 2026-05-06T11:40:41Z @neo-opus-ada cross-referenced by #10815
- 2026-05-06T16:00:40Z @neo-opus-ada cross-referenced by #10822
- 2026-05-07T01:58:50Z @neo-opus-ada cross-referenced by #10871
- 2026-05-08T10:24:23Z @neo-gpt cross-referenced by #10945
- 2026-05-08T10:47:53Z @neo-gpt cross-referenced by #10950
- 2026-05-08T20:41:22Z @neo-opus-ada cross-referenced by PR #10989
- 2026-05-11T19:24:46Z @neo-gpt cross-referenced by #10961
- 2026-05-21T17:32:55Z @neo-gpt cross-referenced by #11720
### @neo-gpt - 2026-05-22T20:10:58Z

## Epic Resolution Review

**Reviewer:** @neo-gpt
**Started:** 2026-05-22T20:11:00Z
**Completed:** 2026-05-22T20:11:20Z
**Verdict:** RECOMMEND_RETIRE_OR_SUPERSEDE

### Matrix

| Parent AC | Required evidence | Owning sub(s) | Delivered PR(s) | Achieved evidence | Residual state |
|---|---|---|---|---|---|
| Enable seamless switching between local unified ChromaDB and federated multi-instance ChromaDB via `NEO_CHROMA_UNIFIED` | L2 config/routing tests | #10001, #10007 | #10121, #10123 | Historical implementation landed: `chromaUnified` routing and unified-mode lifecycle bypass | SUPERSEDED — ADR 0003 later retired the topology toggle |
| Add unified monolithic topology coverage | L2 tests | #10008 | (no close-linked PR visible) | Subissue closed completed | SUPERSEDED by unified-only posture |
| Add federated cloud topology coverage | L2 tests or explicit retirement evidence | #10009 | #11014 | PR #11014 explicitly retired federated topology and closed #10009 as no longer applicable | SUPERSEDED — federated topology removed |

### Rationale

All native subissues under #10015 are closed, but the parent epic should not be closed as completed. Its objective was a dual-topology switch between unified and federated ChromaDB deployments. ADR 0003, accepted on 2026-05-09, superseded that premise by permanently retiring the federated topology and removing the `chromaUnified` toggle in favor of unified-only ChromaDB.

This is exactly the `RECOMMEND_RETIRE_OR_SUPERSEDE` shape from the epic-resolution workflow: the work graph is no longer active, but the parent AC framing is no longer valid as a completed objective.

### Required operator action

Operator decision: retire/close #10015 as superseded/not-planned, or leave it open only if a historical audit trail is intentionally desired on the v13 board.

### A2A coordination

Broadcast sent: `[lifecycle] epic #10015 retire/supersede verdict posted` — MESSAGE:e0e5bd86-5102-4af0-a816-88a2372ade97.

Origin Session ID: d60db68f-8ff0-48a6-b168-237ca9dca2a0

### @neo-gpt - 2026-05-22T20:13:20Z

**Input from GPT-5 (Codex Desktop):**

> ● Operator closeout confirmation received 2026-05-22: Neo now has a unified-only Chroma topology. Per ADR 0003, the legacy `chromaUnified` toggle and federated topology are retired.
> 
> Closing this epic as superseded/not-planned rather than completed: its original dual-topology objective is intentionally no longer valid, and the active architecture is covered by ADR 0003 / PR #11014.

- 2026-05-22T20:13:25Z @neo-gpt closed this issue

