Phase A: establish the canonical cacheroute src namespace

[rickisba]

Motivation

• Provide a canonical, dependency-light cacheroute Python namespace under a src/ layout to host compatibility helpers and observability symbols without importing heavyweight runtime services or application config.

Description

• Create src/cacheroute with lightweight __init__.py and add src/cacheroute/compat/runtime.py by migrating the dependency-light compatibility helpers from the old cacheroute_compat implementation while preserving identical behavior and public symbols; add src/cacheroute/observability/__init__.py as an empty dependency-light observability namespace.
• Change packaging to a real src layout by adding package-dir = {"" = "src"} and setting where = ["src"] in pyproject.toml, and remove the placeholder author email that blocked metadata validation.
• Update internal imports to use the new canonical namespace (from cacheroute.compat.runtime import ...) in core/runtime_compat.py and kdn_server/domain/models.py and adjust tests accordingly; add a thin forwarding shim package under src/cacheroute_compat that re-exports the canonical module to preserve backward compatibility for Phase A.
• Add tests and validation hooks: test/test_runtime_compat.py asserts legacy-to-canonical forwarding, test/test_namespace_layout.py validates the canonical namespace remains dependency-light, and test/test_wheel_install.py updated to validate the installed-wheel import surface; keep no duplicate implementations and document the forwarding shim for future removal.

Testing

• Attempted python3 -m pip install -e . with build isolation failed due to environment package-index restrictions (could not download build deps); this is an environment network restriction and not a code error.
• python3 -m pip install -e . --no-build-isolation --no-deps succeeded (editable install without fetching dependencies).
• python3 -m compileall -q src test scripts succeeded.
• python3 -m pytest -q test/test_runtime_compat.py test/test_namespace_layout.py test/test_wheel_install.py succeeded: all tests passed (12 passed).
• git diff --check passed with no whitespace/errors reported.

Notes: The change intentionally limits Phase A to dependency-light packages; core runtime packages (proxy/instance/kdn) were not migrated in this phase and remain discoverable only as source files (they are not packaged under src/ until a follow-up phase). The cacheroute_compat forwarding shim remains in place to avoid breaking consumers and is documented for removal in a future release.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4b3815604c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep canonical imports available in source checkouts

When users follow the documented lightweight-demo flow—installing requirements.txt and running entrypoints from test/—the scripts add only the repository root to sys.path, not src. This import therefore raises ModuleNotFoundError: No module named 'cacheroute' while loading kdn_server.kv_builder; the focused runtime test also fails during collection in a clean checkout unless an undocumented editable install was performed. Add src to the source/test import path or retain a root-visible forwarding bridge.

AGENTS.md reference: AGENTS.md:L91-L96

Useful? React with 👍 / 👎.