Epic: migrate CacheRoute to the RFC-defined canonical package architecture

[rickisba]

Status

PR #158 completed the Phase A namespace foundation:

• established src/cacheroute;
• moved the compatibility implementation to cacheroute.compat;
• retained a tested temporary cacheroute_compat forwarding shim;
• reserved cacheroute.observability;
• added source-checkout, wheel, package-parity, Markdown-link, bootstrap, and root-directory governance checks.

This Issue remains open. Phase A did not complete the repository migration.

Target architecture

The original target tree in this Issue mirrored deployment processes directly under cacheroute and is superseded by the reviewed architecture in:

• RFC: redesign CacheRoute package architecture around contracts, domains, integrations, services, and entrypoints #159 — contracts, domains, integrations, services, plugins, entrypoints, packaging policy, dependency direction, and migration phases.
• doc/architecture/package-architecture-rfc.md after the architecture-guidance PR is merged.

The canonical top-level Python packages are planned as:

cacheroute.contracts
cacheroute.runtime
cacheroute.topology
cacheroute.knowledge
cacheroute.cache
cacheroute.routing
cacheroute.observability
cacheroute.integrations
cacheroute.services
cacheroute.plugins
cacheroute.entrypoints
cacheroute.compat

Do not introduce a generic cacheroute.core dumping ground. Do not mechanically move current root directories into matching package names.

Architectural rules

• Stable cross-process schemas live under versioned cacheroute.contracts packages.
• CacheRoute-owned domain packages do not import FastAPI, Redis, vLLM, LMCache, or deployable service implementations.
• vLLM, LMCache, Redis, and embedding-specific code lives under cacheroute.integrations and implements CacheRoute-owned ports.
• Scheduler, Proxy, Instance, and KDN implementations live under cacheroute.services and must not import one another's internal modules.
• CLI, Uvicorn application factories, demo orchestration, settings composition, and dependency injection live under cacheroute.entrypoints.
• cacheroute.compat contains temporary compatibility only, never permanent implementations.
• cacheroute.__init__ remains empty or metadata-only.
• No new functional top-level directory may be added without a dedicated architecture Issue.
• The root README remains a high-level overview; detailed architecture stays under doc/.

Target repository categories

src/cacheroute/
tests/
examples/
doc/
scripts/
env/
crates/

tests, doc, scripts, env, logs, and generated data must not be installed as Python packages. Runtime package data must be owned by the package that consumes it.

Migration phases

Phase 0 — architecture foundation

• Merge PR Phase A: establish the canonical cacheroute src namespace #158.
• Merge the RFC: redesign CacheRoute package architecture around contracts, domains, integrations, services, and entrypoints #159 architecture guidance into AGENTS.md and doc/architecture.
• Add automated forbidden-dependency and wheel-allowlist checks.

Phase 1 — packaging and entrypoints

• Remove tests, documentation, scripts, deployment configuration, logs, and generated data from the wheel.
• Introduce one supported CLI: cacheroute <scheduler|proxy|instance|kdn|dev>.
• Add application factories and entrypoint smoke tests.
• Preserve current scripts through narrow temporary wrappers until replacements pass.

Phase 2 — contracts and dependency-light domains

• Move kdn_server/contracts to cacheroute.contracts.v1.
• Move Runtime Profile, lifecycle, capability, and topology/resource models into their owning domains.
• Preserve old imports only through tested thin shims with removal milestones.

Phase 3 — external integrations

• Add cacheroute.integrations.vllm.
• Add cacheroute.integrations.lmcache implementing Cache Runtime ports.
• Isolate Legacy Redis behavior under cacheroute.integrations.redis.
• Move embedding implementations under cacheroute.integrations.embeddings.

Phase 4 — services

Migrate in separate reviewable PRs:

1. KDN;
2. Scheduler;
3. Proxy;
4. Instance.

Each migration must audit and update normal and dynamic imports, module strings, Uvicorn targets, subprocess commands, Docker/CI/config paths, tests and monkeypatch targets, packaging, README links, and operational entrypoints.

Phase 5 — UI, development orchestration, and native components

• Co-locate UI assets with their owning service packages.
• Move demos to cacheroute.entrypoints.dev or examples.
• Review the Resource Agent as a focused native-component migration, potentially under crates/.

Phase 6 — compatibility cleanup

• Remove obsolete root runtime packages.
• Remove transition package lists and direct-source bootstraps.
• Remove expired import shims, including cacheroute_compat at its documented milestone.
• Switch packaging to canonical src-only discovery.

Coordination

• RFC: redesign CacheRoute package architecture around contracts, domains, integrations, services, and entrypoints #159 defines the target architecture.
• v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 remains open.
• PR docs: research unified v1 LMCache observability for #141 #156 must rebase onto the merged namespace foundation, move its implementation into src/cacheroute/observability, resolve its existing review findings, and avoid introducing a permanent root package.
• Do not resume broad production instrumentation until the observability contract package is reviewed in its canonical location.

Required validation

Each migration PR must report exact results for its applicable commands and include:

• editable install;
• compileall;
• focused CPU-only regression suites;
• dependency-light import isolation;
• source-checkout entrypoint tests;
• repository-wide stale import and module-string scans;
• local Markdown-link validation;
• clean-copy wheel build and isolated install;
• wheel top-level package allowlist;
• git diff --check.

Completion criteria

This Epic may close only when:

• RFC: redesign CacheRoute package architecture around contracts, domains, integrations, services, and entrypoints #159 architecture boundaries are reflected in the implementation;
• canonical contracts, domains, integrations, services, plugins, and entrypoints are established;
• vLLM and LMCache dependencies are isolated behind integration boundaries and domain ports;
• service packages do not import another service's internals;
• only cacheroute and explicitly approved temporary shims enter the wheel;
• root runtime package directories are removed;
• existing runtime behavior, wire values, commands, Docker/CI paths, and documentation links remain validated;
• compatibility shims have explicit removal milestones and no duplicate implementations;
• v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141 observability work resides at cacheroute.observability.

Refs #159
Refs #141

[rickisba]

Phase 1A is now tracked by #170.

Scope: remove repository-only doc, env, log, scripts, and test namespaces from the wheel while preserving all current root runtime packages, runtime package data, direct source-checkout scripts, and behavior.

data and the unified CLI are explicitly deferred to separate focused audits. This keeps the first implementation PR small and avoids combining packaging cleanup with service or entrypoint migration.

Refs #159

[rickisba]

Phase 2 implementation begins with #172.

This is the first real Python ownership migration after the packaging boundary work: canonicalize RuntimeProfile and the dependency-light KDN v1 contract foundation under src/cacheroute, while retaining old paths only as identity-preserving forwarding shims.

The full knowledge/cache-service contracts and their cache/topology domain models remain separate follow-up slices.