Phase 2B: canonicalize cache, topology, and routing domain state models #174

Context

PR #173 completed Issue #172 by moving RuntimeProfile and the shared KDN v1 common/error contract foundation into canonical cacheroute packages. The remaining dependency-light v1 domain state still lives in kdn_server/domain/models.py, even though Issues #139 and #140 already defined and validated its behavior.

This Issue performs the next ownership migration required by the architecture in #159 and the migration Epic in #157. It moves existing models without redesigning their wire behavior or introducing service, Gateway I/O, observability, or policy changes.

Refs #172
Refs #173
Refs #159
Refs #157
Refs #139
Refs #140
Refs #137

Decision

Create canonical ownership for the remaining v1 domain state under the existing src/cacheroute namespace:

src/cacheroute/
├── runtime/
│   └── state.py
├── topology/
│   ├── __init__.py
│   └── lmcache.py
├── cache/
│   ├── __init__.py
│   └── models.py
└── routing/
    ├── __init__.py
    └── queue.py

Do not add a functional repository-root directory. Do not create cacheroute.core.

Canonical ownership

cacheroute.runtime.state

Own the lightweight shared state infrastructure currently used by these domain models:

• StrEnum;
• Snapshot;
• StateTransitionError;
• shared UTC, canonical-ID, non-empty-string, and validation helpers that are genuinely reused across the migrated domains.

Keep this module lightweight and free of service imports and import-time side effects.

cacheroute.topology.lmcache

Own:

• LMCacheGatewayProfile;
• LMCacheEndpoint.

Preserve endpoint identity, generation, validation, serialization, and next_generation behavior exactly.

cacheroute.cache.models

Own:

• ObservationSource;
• ObservationConfidence;
• ObservationState;
• CacheOperationType;
• CacheOperationState;
• CacheArtifact;
• CacheReplicaObservation;
• CacheOperationTask.

Preserve stable IDs, adapter ordering, runtime-profile validation, freshness and expiry semantics, endpoint-generation checks, Legacy projection behavior, operation transition tables, retryable/terminal properties, timestamps, serialization, and all validation error behavior.

cacheroute.cache may depend on cacheroute.runtime and cacheroute.topology. cacheroute.topology must not depend on cacheroute.cache or services.

cacheroute.routing.queue

Own:

• QueueState;
• QueueWork.

Preserve IDs, timestamps, transition tables, idempotent same-state transitions, retryable/terminal properties, and error details exactly. Keep queue policy and process-global Proxy state out of this package.

Compatibility paths

Keep the existing public compatibility surface:

• kdn_server.domain;
• kdn_server.domain.models.

After migration, kdn_server/domain/models.py must be an import-only forwarding shim containing documentation and imports/re-exports only. It must not retain independent validators, enums, ID helpers, transition tables, functions, or model implementations.

All old and canonical paths must preserve Python object identity, for example:

from cacheroute.cache import CacheArtifact as canonical
from kdn_server.domain import CacheArtifact as legacy
assert legacy is canonical

Apply the same identity requirement to every migrated class and enum.

Import audit

Update first-party implementation imports where the owning canonical package is clear. Audit all of the following:

• kdn_server.contracts.knowledge;
• kdn_server.contracts.cache_service;
• kdn_server.gateway.*;
• Scheduler, Proxy, Instance, client, store, model, and utility modules that consume these models;
• normal imports;
• dynamic imports and module strings;
• subprocess and application targets;
• test monkeypatch paths;
• serialization/type checks;
• documentation snippets and relative links.

Rules:

• production implementation should prefer canonical imports;
• compatibility tests may intentionally import kdn_server.domain;
• do not perform unrelated import cleanup or formatting;
• do not change service behavior.

Dependency boundaries

Canonical runtime, topology, cache, and routing modules must not import:

• kdn_server;
• Scheduler, Proxy, Instance, client, store, model, or UI packages;
• FastAPI, Redis, NumPy, Torch, sentence-transformers, vLLM, or LMCache;
• deployable service implementations.

Pydantic and Python standard-library dependencies used by the existing models are allowed.

Importing each canonical package must have no import-time I/O, environment mutation, network access, subprocess launch, or sys.path mutation.

Packaging

Update the explicit setuptools package list to include:

• cacheroute.topology;
• cacheroute.cache;
• cacheroute.routing.

Keep cacheroute.runtime and all currently approved transitional packages. Do not switch to automatic discovery and do not change project dependencies.

The clean wheel must include the new canonical modules and preserve the temporary kdn_server.domain compatibility surface.

Governance and tests

Add focused tests proving:

1. canonical/legacy object identity for every migrated class and enum;
2. kdn_server.domain.models is an import-only forwarding shim;
3. each canonical package is dependency-light and does not import services or external runtime/storage SDKs;
4. stable IDs, enum wire values, serialization, immutability, validation, transition tables, same-state idempotency, retryable/terminal properties, freshness, expiry, endpoint generation, and Legacy projection remain unchanged;
5. source-checkout imports resolve correctly;
6. clean-copy wheel build succeeds;
7. isolated wheel imports resolve from site-packages and preserve canonical/legacy identity;
8. stale implementation references and duplicate definitions are rejected by governance tests;
9. existing KDN, Instance capability, and relevant routing/queue regression suites pass.

Do not weaken existing package parity, root-directory governance, forbidden-dependency checks, Markdown-link validation, or wheel allowlists.

Documentation

Update only detailed architecture and migration documentation required to record canonical ownership and temporary compatibility paths.

• Do not modify the root README.
• Do not delete or replace existing documentation introductions.
• Do not copy this Issue body into repository Markdown.

Non-goals

• moving kdn_server.contracts.knowledge or kdn_server.contracts.cache_service implementations;
• changing contract fields or wire values;
• implementing KDN, LMCache, Redis, vLLM, or embedding I/O;
• moving Gateway implementations;
• migrating Scheduler, Proxy, Instance, or KDN services;
• implementing observability from v0.1.10-4: Add Unified v1 LMCache Gateway, Tier, Adapter, and Queue Observability #141;
• implementing queueing, admission, routing, placement, cache-value, eviction, or maintenance policy;
• adding CLI or application factories;
• removing root service packages;
• removing temporary compatibility shims;
• changing the root README.

Required validation

Run from a clean checkout with Python 3 and report exact results:

python3 -m pip install -e . --no-build-isolation
python3 -m compileall -q src kdn_server test
python3 -m pytest -q test/test_repository_governance.py
python3 -m pytest -q test/test_namespace_layout.py
python3 -m pytest -q test/test_source_checkout_imports.py
python3 -m pytest -q test/test_wheel_install.py -m "not network" -s
python3 -m pytest -q test/kdn
python3 -m pytest -q test/test_instance_capability.py test/test_instance_capability_registration.py
python3 -m build --no-isolation
git diff --check

Add and run a focused canonical-domain migration suite covering all moved models and identity guarantees.

Also run fresh-process checks proving that importing:

import cacheroute.runtime.state
import cacheroute.topology
import cacheroute.cache
import cacheroute.routing

does not load kdn_server, service packages, or prohibited heavy/runtime SDKs.

Inspect the built wheel from outside the repository and report installed module paths for canonical and compatibility modules.

Acceptance criteria

• Every migrated model and enum has exactly one implementation under its canonical cacheroute owner.
• kdn_server.domain and kdn_server.domain.models re-export the same objects by identity.
• kdn_server/domain/models.py is an import-only forwarding shim.
• No public field, default, enum value, stable ID, transition, validation, freshness, generation, or Legacy projection behavior changes.
• Canonical packages are dependency-light and do not import services or external runtime/storage SDKs.
• Production imports prefer canonical owners where in scope.
• Explicit packaging, clean wheel build, and isolated installation pass.
• KDN, Instance capability, source-checkout, namespace, governance, and wheel regression tests pass.
• Root README is unchanged.
• No service, Gateway I/O, observability, policy, or external integration migration is included.
• Exact changed files and test results are reported in the PR body.

Closes this Issue only when implementation, compatibility, packaging, and regression validation are complete.

Refs #159
Refs #157
Refs #137