Installed package set is derived from the explicit [tool.setuptools].packages list in pyproject.toml; package discovery must not change in this handbook PR.
| Concept / responsibility | Canonical package/module | Current transitional implementation | Dependency direction | Public/internal | Design link | Relevant tests | Migration status | Status |
|---|---|---|---|---|---|---|---|---|
| Canonical namespace root | cacheroute |
src/cacheroute/__init__.py |
root -> focused domain packages | Public namespace root; explicit public export list is currently empty | package RFC | test/test_namespace_layout.py, test/test_documentation_governance.py |
Users import public objects from focused packages such as cacheroute.runtime, not from root |
Current |
| Runtime profile vocabulary | cacheroute.runtime |
core.runtime_compat, src/cacheroute_compat |
contracts/domain -> services | Public | runtime_compatibility_v1 | test/test_runtime_compat.py, test/test_wheel_install.py |
Canonical foundation exists; shims remain | Current / Transitional |
| Topology endpoint identity | cacheroute.topology |
Proxy/Instance/KDN resource pools | domain -> services | Public foundation | package RFC | test/test_namespace_layout.py, test/test_wheel_install.py |
Foundation exists | Current |
| Cache artifacts and operations | cacheroute.cache |
KDN, Proxy, legacy Redis paths | domain -> services/adapters | Public foundation | package RFC | test/test_contract_foundation.py |
Foundation exists | Current |
| Queue lifecycle models | cacheroute.routing |
scheduler.strategy, proxy.strategy, proxy.queue |
domain -> services | Public foundation | package RFC | test/test_namespace_layout.py |
Reusable foundation exists; root strategies remain | Current / Transitional |
| Contract namespace | cacheroute.contracts |
kdn_server/contracts forwarding shims |
contracts only | Public | package RFC | test/test_contract_foundation.py |
Canonical v1 exists | Current |
| KDN/Gateway v1 contracts | cacheroute.contracts.v1 |
kdn_server/contracts |
contracts -> domain | Public | package RFC | test/test_contract_service_migration.py |
Canonical objects plus shims | Current / Transitional |
| Observability helpers | cacheroute.observability |
Scheduler and Proxy local usage | domain -> services | Public helper API | observability v1 | test/observability |
Foundation and PR #183 propagation Current | Current |
| Observability schema | cacheroute.observability.v1 |
Process-local request stage projection | contracts/domain -> services | Public schema | observability v1 | test/observability |
Schema exists; exporters absent | Current |
| Compatibility runtime API | cacheroute.compat |
cacheroute_compat, core.runtime_compat |
compat -> canonical | Public compatibility | phase A | test/test_runtime_compat.py |
Shim remains | Transitional |
| Legacy compatibility namespace | cacheroute_compat |
Forwarding package in src/cacheroute_compat |
compat -> canonical | Public compatibility | phase A | test/test_wheel_install.py |
Shim remains | Transitional |
| Scheduler service | Target cacheroute.services.scheduler |
scheduler |
service uses contracts/domain | Transitional public runtime | scheduler README | demo and governance tests | Not migrated | Transitional |
| Proxy service | Target cacheroute.services.proxy |
proxy |
service uses contracts/domain | Transitional public runtime | proxy README | demo, observability tests | Not migrated | Transitional |
| Instance service | Target cacheroute.services.instance |
instance |
service uses contracts/domain | Transitional public runtime | instance README | demo tests | Not migrated | Transitional |
| KDN service | Target cacheroute.services.kdn |
kdn_server |
service uses contracts/domain | Transitional public runtime | kdn README | contract tests | Not migrated | Transitional |
| Client and workload tooling | future entrypoints/examples | client |
caller -> services | Transitional | client README | demo tests | Not migrated | Transitional |
| Shared configuration/request models | assign by domain after audit | core |
transitional shared | Transitional | core README | source checkout tests | Awaiting audit | Transitional |
| Knowledge storage helpers | target knowledge after approval |
store |
transitional | Internal/transitional | package RFC | governance tests | Not migrated | Transitional |
| Model/embedder helpers | target integrations/runtime after audit | model |
transitional | Internal/transitional | root docs | source checkout tests | Not migrated | Transitional |
| Browser assets | owning service packages | UI |
UI -> services | Transitional | UI proxy README | wheel package-data tests | Not migrated | Transitional |
| Generic helpers | owning domain after audit | util |
transitional | Internal/transitional | package RFC | governance tests | Not migrated | Transitional |
| Knowledge domain | cacheroute.knowledge |
root KDN/store concepts | domain -> services | Target | package RFC | not importable | Accepted, absent | Target / Accepted |
| External adapters | cacheroute.integrations |
legacy Redis/KDN/vLLM code in roots | adapter implements ports | Target | package RFC | not importable | Accepted, absent | Target / Accepted |
| Deployable services | cacheroute.services |
root service packages | services use domain | Target | package RFC | not importable | Accepted, absent | Target / Accepted |
| Plugins | cacheroute.plugins |
none canonical | plugins depend on protocols | Target | package RFC | not importable | Accepted, absent | Target / Accepted |
| Entrypoints | cacheroute.entrypoints |
demo scripts and CLIs | entrypoints wire services | Target | package RFC | not importable | Accepted, absent | Target / Accepted |
cacheroute, cacheroute.compat, cacheroute.observability, cacheroute.observability.v1, cacheroute.runtime, cacheroute.topology, cacheroute.cache, cacheroute.routing, cacheroute.contracts, cacheroute.contracts.v1, cacheroute_compat, UI, UI.client_ui, UI.client_ui.static, UI.client_ui.templates, UI.kdn_ui, UI.proxy_ui, UI.proxy_ui.static, client, client.taskset, core, data, data.CacheRoute_dataset, data.CacheRoute_dataset.knowledge_document, instance, instance.TPOT_predictor, instance.TTFT_predictor, instance.TTFT_predictor.data, instance.pclient, instance.resource_agent, instance.resource_agent.src, instance.resource_dashboard, instance.resource_dashboard.static, kdn_server, kdn_server.KV_database, kdn_server.contracts, kdn_server.domain, kdn_server.gateway, kdn_server.sclient, kdn_server.text_database, kdn_server.text_database.blocks, kdn_server.util, model, proxy, proxy.metrics, proxy.metrics.data, proxy.queue, proxy.resource, proxy.sclient, proxy.strategy, scheduler, scheduler.knowledge, scheduler.resource, scheduler.strategy, store, util.