Phase 2A: canonicalize RuntimeProfile and the KDN v1 contract foundation

[rickisba]

Context

Issue #159 defines cacheroute.runtime and cacheroute.contracts.v1 as canonical package owners. Issue #157 keeps the old root packages only as temporary compatibility locations.

The current KDN contract foundation still lives under kdn_server.contracts. Its base envelope imports RuntimeProfile from kdn_server.domain, so simply copying the contracts into src/cacheroute would create a forbidden dependency from canonical contracts back into a deployable root component.

This Issue starts the first substantive Python ownership migration. It moves the smallest dependency-light slice that can be made canonical without pulling the complete KDN domain and gateway implementation into one PR.

Refs #159
Refs #157

Decision

Create canonical implementations for:

• cacheroute.runtime.profiles.RuntimeProfile;
• cacheroute.contracts.v1.common;
• cacheroute.contracts.v1.errors.

The old paths remain temporarily import-compatible, but must become thin forwarding layers with object identity preserved.

This PR changes real Python type ownership and import direction. It is not a documentation-only or governance-only phase.

Canonical package layout

src/cacheroute/
├── runtime/
│   ├── __init__.py
│   └── profiles.py
└── contracts/
    ├── __init__.py
    └── v1/
        ├── __init__.py
        ├── common.py
        └── errors.py

Do not add another functional top-level directory.

RuntimeProfile migration

Move the implementation of RuntimeProfile from kdn_server/domain/models.py into src/cacheroute/runtime/profiles.py.

Preserve exactly:

• enum member names and wire values;
• normalize behavior;
• resolve_startup behavior;
• resolve_auto alias;
• use of cacheroute.compat.runtime.normalize_runtime_profile;
• exception behavior for invalid values.

Update kdn_server/domain/models.py to import the canonical RuntimeProfile instead of defining a second class.

The following identities must hold:

from cacheroute.runtime import RuntimeProfile as canonical
from kdn_server.domain import RuntimeProfile as legacy

assert legacy is canonical

Do not keep a duplicate RuntimeProfile implementation under kdn_server.

Contract foundation migration

Move the implementation of these modules into the canonical namespace:

• kdn_server/contracts/common.py -> cacheroute.contracts.v1.common;
• kdn_server/contracts/errors.py -> cacheroute.contracts.v1.errors.

Canonical common.py must import RuntimeProfile from cacheroute.runtime, never from kdn_server.

Preserve all existing public behavior and wire values, including:

• KDN_CONTRACT_VERSION;
• GATEWAY_CONTRACT_VERSION;
• ENDPOINT_ID_PATTERN;
• SupportState truthiness;
• utc_now;
• ContractModel frozen/extra behavior and validated model_copy;
• VersionedMessage validation and field names;
• GatewayTargetedRequest validation;
• TokenReference;
• TokenInput validation;
• OutcomeCode values;
• ContractErrorDetail and ContractError alias.

The canonical package must remain dependency-light. Importing it must not import:

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

Compatibility paths

Keep these old modules temporarily:

• kdn_server.contracts.common;
• kdn_server.contracts.errors.

They must contain documentation plus imports/re-exports only. No validators, constants, classes, functions, aliases, or business logic may be independently implemented there.

Preserve object identity for every exported symbol. Examples:

from cacheroute.contracts.v1.common import VersionedMessage as canonical
from kdn_server.contracts.common import VersionedMessage as legacy
assert legacy is canonical

from cacheroute.contracts.v1.errors import OutcomeCode as canonical_code
from kdn_server.contracts.errors import OutcomeCode as legacy_code
assert legacy_code is canonical_code

Update kdn_server.contracts.__init__ so its public API continues to work while resolving the migrated base symbols from canonical implementations.

Do not move knowledge.py or cache_service.py in this PR. They still depend on KDN domain models that require their own reviewed migration slice.

Import updates

Update first-party implementation imports that consume only the migrated foundation to use canonical paths where doing so is clear and does not expand scope.

At minimum audit:

• kdn_server.contracts.knowledge;
• kdn_server.contracts.cache_service;
• kdn_server.gateway.*;
• test/kdn;
• module strings, dynamic imports, monkeypatch targets, and documentation snippets.

Rules:

• production implementation should prefer canonical imports;
• compatibility tests may intentionally import old paths;
• no service behavior change;
• no broad formatting or unrelated import cleanup.

Packaging

Update the explicit setuptools package list to include:

• cacheroute.runtime;
• cacheroute.contracts;
• cacheroute.contracts.v1.

Keep all existing transitional runtime packages.

Do not switch to automatic discovery.

Do not change project dependencies.

Governance and tests

Add tests proving:

1. canonical/legacy object identity for RuntimeProfile, common contract symbols, and error symbols;
2. old common/errors modules are import-only forwarding shims;
3. canonical imports do not load kdn_server or heavy/runtime service packages;
4. cacheroute.__init__ remains metadata-only;
5. source-checkout and installed-wheel imports resolve correctly;
6. serialization, validation, enum values, defaults, and error behavior remain unchanged;
7. stale implementation references are rejected while explicit compatibility references remain narrowly allowlisted.

Update repository governance for the new canonical packages without weakening the root package parity rules.

Update wheel tests so the canonical subpackages are present and import from the isolated installation.

Documentation

Update only detailed architecture/migration documentation needed to record this implementation phase.

Do not modify the root README.

Do not copy this Issue body into repository Markdown.

Non-goals

• moving kdn_server.contracts.knowledge;
• moving kdn_server.contracts.cache_service;
• moving CacheArtifact, CacheOperationTask, CacheReplicaObservation, LMCacheEndpoint, or queue models;
• moving KDN gateways or service code;
• changing wire fields or values;
• changing routing, cache, registration, heartbeat, inference, vLLM, LMCache, or Redis behavior;
• adding unified CLI or application factories;
• removing the root kdn_server package;
• creating cacheroute.core.

Required validation

Run from a clean checkout with Python 3:

python3 -m pip install -e . --no-build-isolation
python3 -m compileall -q src kdn_server test
python3 -m pytest -q test/test_runtime_compat.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_repository_governance.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

Also run a fresh-process isolation check proving that importing:

import cacheroute.runtime
import cacheroute.contracts
import cacheroute.contracts.v1
import cacheroute.contracts.v1.common
import cacheroute.contracts.v1.errors

does not load kdn_server or heavy third-party runtime packages.

Inspect the built wheel from outside the repository and report the installed paths of the canonical and legacy modules.

Acceptance criteria

• RuntimeProfile has one implementation under cacheroute.runtime.
• kdn_server.domain.RuntimeProfile is the same object as the canonical type.
• common and error contract foundations have one implementation under cacheroute.contracts.v1.
• old common/errors modules are thin import-only forwarding shims.
• all public wire values and validation behavior are unchanged.
• canonical imports are dependency-light and do not import kdn_server.
• editable install, source checkout, wheel build, and isolated wheel imports pass.
• KDN and Instance capability regression suites pass.
• root README is unchanged.
• no service, gateway, full contract, or external integration migration is included.
• exact test results and changed files are reported in the PR body.

Closes this Issue only when the implementation and compatibility tests are complete.

Refs #159
Refs #157