Phase 1A: remove repository-only namespaces from the CacheRoute wheel #170

Context

The package architecture RFC in #159 and migration Epic #157 require the final wheel to contain only the canonical cacheroute namespace and explicitly approved temporary compatibility shims.

The current Phase A packaging map still installs repository-support namespaces together with transitional runtime packages. In particular, pyproject.toml currently includes:

• doc, doc.blog, doc.integrations;
• env and Docker/configuration subpackages;
• log and log.scheduler;
• scripts;
• test and test.kdn.

These are repository documentation, deployment configuration, experiment artifacts, operational scripts, and tests. They are not public runtime Python packages and must not be present in the wheel.

This is the first focused implementation step under Phase 1. It intentionally does not move Scheduler, Proxy, Instance, KDN, UI, client, model, store, or utility code into the canonical namespace.

Refs #159
Refs #157

Decision

Remove only clearly repository-owned namespaces from the installed wheel in this Issue:

• doc and doc.*;
• env and env.*;
• log and log.*;
• scripts and scripts.*;
• test and test.*.

Keep their repository directories and source-checkout workflows unchanged.

Do not add __init__.py files to these directories and do not relocate their contents in this phase.

The explicit transitional package list remains in place for root runtime packages until their focused migrations are completed.

Deferred from this Issue

data

Do not remove or move data in this PR.

The repository contains dataset/knowledge-document material and manifests that reference repository data paths. Before changing wheel treatment, a separate focused audit must identify:

• Python imports, dynamic module strings, and file-path consumers;
• knowledge manifests and default dataset paths;
• Docker, configuration, and mounted-volume references;
• tests and demos that require source-tree data;
• which files are runtime package data versus research artifacts.

Do not create cacheroute.data.

Unified CLI and application factories

Do not add the cacheroute <scheduler|proxy|instance|kdn|dev> command in this PR. Entry points require a separate focused Issue after the wheel boundary is clean and tested.

Required implementation

Packaging

Update pyproject.toml so the package list no longer includes any of:

• doc, doc.*;
• env, env.*;
• log, log.*;
• scripts, scripts.*;
• test, test.*.

Do not change declared project dependencies.

Do not switch to broad automatic package discovery yet.

Do not remove transitional runtime packages such as core, client, scheduler, proxy, instance, kdn_server, store, model, util, UI, or data in this phase.

Governance

Update package-discovery governance so repository-only namespaces are excluded deliberately rather than added back to the package list.

The exclusions must cover each repository-owned namespace and descendants:

• doc, doc.*;
• env, env.*;
• log, log.*;
• scripts, scripts.*;
• test, test.*.

Keep the root-directory allowlist; these directories remain valid repository categories.

Add explicit assertions that none of the repository-only namespaces is configured as an installed package.

Do not weaken parity checks for the remaining transitional runtime packages.

Wheel contract

Update wheel tests so they verify both:

1. the exact interim top-level runtime package allowlist; and
2. the absence of repository-only namespaces and representative files.

The interim top-level wheel set should remain limited to the currently required transitional runtime surface:

• UI;
• cacheroute;
• cacheroute_compat;
• client;
• core;
• data;
• instance;
• kdn_server;
• model;
• proxy;
• scheduler;
• store;
• util.

The wheel must not contain top-level entries for:

• doc;
• env;
• log;
• scripts;
• test.

The existing required runtime package-data checks for UI, dashboard, predictors, model configuration, and metrics must continue to pass.

Source-checkout behavior

Removing a namespace from the wheel must not make its repository files unusable from a source checkout.

Keep direct execution of existing operational scripts and pytest collection working from the repository tree. Do not convert repository scripts into installed modules in this phase.

Audit and report any normal imports, dynamic imports, module strings, subprocess commands, or python -m invocations that rely on the removed namespaces being importable from an installed wheel. Fix only references required to preserve documented runtime behavior; do not migrate unrelated code.

Documentation

Update only the detailed packaging/migration documentation needed to record the new interim wheel boundary.

Do not modify the root README.

Do not delete or replace existing documentation introductions.

Architecture constraints

• No new functional top-level directory.
• No service or domain directory migration.
• No cacheroute.core.
• No cacheroute.data.
• No new placeholder canonical package.
• No wire-format, routing, queueing, cache, registration, or inference behavior change.
• No changes to vLLM or LMCache integration behavior.
• No direct modification of production entrypoint semantics.

Required validation

Run from a clean checkout with Python 3:

python3 -m pip install -e . --no-build-isolation
python3 -m compileall -q src test scripts client core scheduler proxy instance kdn_server store model util UI
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/test_runtime_compat.py
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

Inspect the built wheel from outside the repository and report:

• exact top-level package names;
• confirmation that doc, env, log, scripts, and test are absent;
• confirmation that required UI, dashboard, predictor, model, and metrics package data remains present;
• confirmation that cacheroute, cacheroute.compat, cacheroute.observability, and cacheroute_compat import from the installed environment;
• confirmation that the existing transitional runtime public imports still resolve from the installed wheel when declared dependencies are available.

Acceptance criteria

• doc and descendants are not installed packages.
• env and descendants are not installed packages.
• log and descendants are not installed packages.
• scripts and descendants are not installed packages.
• test and descendants are not installed packages.
• Repository directories remain in place and source-checkout workflows remain usable.
• The interim wheel top-level allowlist is exact and tested.
• Required runtime package data is unchanged.
• Remaining transitional runtime package parity is still enforced.
• data remains unchanged pending a focused consumer/package-data audit.
• No service migration, unified CLI, or runtime behavior change is included.
• Root README is unchanged.
• Exact validation results and wheel contents are reported in the PR body.

Refs #159
Refs #157