CAC-264: Clarify repository boundaries and clean up adapter contracts

[fredericsun]

Summary

This PR follows up on #174 by establishing clearer repository ownership boundaries before the remaining source-layout migration.

It:

• removes obsolete CacheBackendType values and deprecated provider-rendering seams;
• moves built-in storage and runtime adapters under internal/adapters/builtin;
• centralizes shipping adapter composition in internal/adapters/builtin.New;
• preserves pkg/adapters as the build-time out-of-tree extension contract;
• removes unshipped CacheBackend compatibility fields and fallback paths;
• makes structured backend.Binding support a required runtime adapter contract;
• updates CRDs, generated code, samples, smoke assertions, tests, and documentation;
• adds docs/design/repository-boundaries.md as the source of truth for the remaining Phase A–C restructuring.

The CacheBackend compatibility removal is intentional: inference-cache has not been formally deployed, so this PR does not add conversion or forwarding behavior for the removed resource shape.

Out-of-tree runtime adapters must now implement SupportsBinding and accept *backend.Binding directly in engine/router injection methods. A nil binding consistently means host-only operation.

This PR does not change protobuf compatibility, LookupRoute wire paths, legacy vLLM metric names, Kubernetes Event compatibility reads, or runtime plugin-loading behavior.

Linked issues

Part of CAC-264.

Follow-up to CAC-259 and #174.

Checklist

Vendor-neutral naming (required — see CONTRIBUTING.md)

• No oci / oracle / *.oci.com / oraclecloud.com in any API group, CRD group, proto package, gRPC service/package, Kubernetes namespace, image registry, Helm chart, or Go module path.
• Any cloud-specific (incl. OCI) integration lives in an isolated, optional adapter (pkg/adapters/.../) — never in core controllers, CRD types, the proto contract, or default config.
• No Oracle/OCI domain or namespace in sample manifests, README, or default values.
• Pre-commit naming guard passed (make install-hooks once, then it runs on every commit).

Quality

• make build and make test pass locally.
  • go test ./... and go test -race ./... pass.
• make lint clean (gofmt + go vet).
  • Changed Go files are formatted and git diff --check passes.
• make manifests generate produces no drift (generated code committed).
  • CRD and deepcopy output were regenerated and committed.
• New/changed behavior has unit tests.
• Operator-facing change (CRD columns/fields, .status, CLI, gRPC/HTTP, install bundle/RBAC, samples)? If so, the install-smoke gate asserts it (see CONTRIBUTING.md).
• CI is green.

Contracts (only if touching CRDs or proto)

• Change matches the tech spec (or the spec is updated in the same PR).
• Backward compatibility considered for v1alpha1 consumers (engines, gateway clients).
  • Removed CacheBackend fields were not formally deployed; no resource conversion is included.
  • The out-of-tree Go adapter interface change is explicitly documented.
• If proto/ changed, docs/design/grpc-contract.md is updated to match (the pre-commit hook enforces this).
  • N/A: proto/ is unchanged.
• If CRD API types (api/v1alpha1/*_types.go) or the proto contract changed, the documentation is updated to match — the docs site (site/) and/or the design docs (docs/). CI enforces this (make verify-docs-sync); add the no-docs-needed label to waive a genuinely doc-exempt change.

[linear-code]

CAC-264

[github-actions]

Codex review

Files reviewed

• api/v1alpha1/

  • [reviewed] cachebackend_effective.go, cachebackend_effective_test.go, cachebackend_types.go, cachebackend_types_test.go
  • [skipped — generated] zz_generated.deepcopy.go

• config/crd/bases/

  • [skipped — generated] inferencecache.io_cachebackends.yaml

• config/samples/

  • [reviewed] cache_v1alpha1_cachebackend.yaml, cachebackend-cpu-override.yaml

• docs/cli/

  • [reviewed] doctor.md

• docs/concepts/

  • [reviewed] cachebackend-engine-binding.md, cachebackend-engine-overrides.md

• docs/design/

  • [reviewed] cachebackend-api.md, grpc-tls.md, kvevent-subscriber-wiring.md, lmcache-server-persistence.md, repository-boundaries.md, sglang-lmcache-mp-mode.md

• docs/observability/

  • [reviewed] alerts.md

• docs/reference-stack/

  • [reviewed] README.md

• docs/reference-stack/manifests/sglang-lmcache/

  • [reviewed] README.md

• docs/reference-stack/scripts/

  • [reviewed] canary_c2_reconcile.sh, canary_c6_engine_wiring.sh, default_install_smoke.sh

• hack/verify-samples/

  • [reviewed] admission_test.go

• internal/adapters/builtin/

  • [reviewed] boundaries_test.go, registry.go, registry_test.go

• internal/adapters/builtin/runtime/

  • [reviewed] contract_aliases_test.go, doc.go, lmcachecheck.go, lmcachecheck_script_test.go, lmcachecheck_test.go, sglang_hicache.go, sglang_hicache_test.go, sglang_lmcache.go, sglang_lmcache_test.go, sglang_lmcache_wire.go, vllm_lmcache.go, vllm_lmcache_test.go, vllm_lmcache_wire.go, vllm_lmcache_wire_test.go

• internal/adapters/builtin/storage/

  • [reviewed] effective_config.go, lmcache_server.go, mooncake.go, redis.go, redis_test.go, registry.go, registry_test.go

• internal/controller/

  • [reviewed] cachebackend_autoscaling_test.go, cachebackend_controller.go, cachebackend_controller_test.go, cachebackend_engine_compat.go, cachebackend_events_only_integration_test.go, cachebackend_events_test.go, cachebackend_hostnetwork_test.go, cachebackend_kvevent_gate_test.go, cachebackend_matched_pods_test.go, cachebackend_probe.go, cachebackend_probe_integration_test.go, cachebackend_probe_test.go, cachebackend_resources_integration_test.go, cachebackend_schema_trim_integration_test.go, cachebackend_t2degraded_test.go, contract_coverage_sweep_test.go, integration_test.go

• internal/webhook/pod/

  • [reviewed] doc.go, envtest_integration_test.go, podinjector.go, podinjector_test.go

• internal/webhook/v1alpha1/

  • [reviewed] cachebackend_defaulter_envtest_test.go, cachebackend_webhook.go, cachebackend_webhook_test.go

• pkg/adapters/runtime/

  • [reviewed] adapter.go, adapter_test.go, doc.go, kernelcheck.go, kvevent_subscriber.go, reference.go, wire_contract.go
  • [reviewed — deleted] provider_compat.go, vllm_lmcache_kernelcheck.go, vllm_mooncake.go, vllm_mooncake_test.go

• pkg/adapters/runtime/external/

  • [reviewed — deleted] doc.go, external.go, external_test.go

• pkg/adapters/runtime/sglang/

  • [reviewed — deleted] doc.go

• pkg/cli/doctor/checks/

  • [reviewed] cachebackend.go, checks_test.go

• site/content/en/docs/concepts/

  • [reviewed] architecture.md, cachebackend.md

• site/content/en/docs/developer-guide/

  • [reviewed] _index.md

• site/content/en/docs/reference/

  • [reviewed] crd-api.md

• site/content/en/docs/tasks/

  • [reviewed] bind-an-engine.md, deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:295 — The served v1alpha1 schema removes previously accepted fields (backendConfig, top-level resources, endpoint, integration.engine, and integration.firstEventTimeout), makes runtime required, and removes existing CacheBackendType values without conversion or forwarding support. This directly violates the review requirement that v1alpha1 retain backward compatibility; existing manifests and persisted objects will be rejected or pruned.

• pkg/adapters/runtime/adapter.go:43 — The public out-of-tree extension interface gains a required SupportsBinding method and replaces both injection method signatures. Every existing third-party adapter consequently stops compiling, despite pkg/adapters being presented as the stable extension contract; introduce a versioned interface or compatibility adapter.

Should-fix

None.

Nit

• docs/reference-stack/manifests/sglang-lmcache/README.md:16 — The documentation references internal/adapters/builtin/storage/redis_l2.go, but this PR renamed that implementation to redis.go. The source link/path is therefore stale.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:295, pkg/adapters/runtime/adapter.go:43
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): findings above at: docs/reference-stack/manifests/sglang-lmcache/README.md:16

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

api/v1alpha1/

• [reviewed] cachebackend_effective.go
• [reviewed] cachebackend_effective_test.go
• [reviewed] cachebackend_types.go
• [reviewed] cachebackend_types_test.go
• [skipped — generated] zz_generated.deepcopy.go

cmd/inferencecache/

• [reviewed] doctor_integration_test.go

config/crd/bases/

• [skipped — generated] inferencecache.io_cachebackends.yaml

config/samples/

• [reviewed] cache_v1alpha1_cachebackend.yaml
• [reviewed] cachebackend-cpu-override.yaml

docs/cli/

• [reviewed] doctor.md

docs/concepts/

• [reviewed] cachebackend-engine-binding.md
• [reviewed] cachebackend-engine-overrides.md

docs/design/

• [reviewed] cachebackend-api.md
• [reviewed] grpc-tls.md
• [reviewed] kvevent-subscriber-wiring.md
• [reviewed] lmcache-server-persistence.md
• [reviewed] repository-boundaries.md
• [reviewed] sglang-lmcache-mp-mode.md

docs/observability/

• [reviewed] alerts.md

docs/reference-stack/

• [reviewed] README.md

docs/reference-stack/manifests/sglang-lmcache/

• [reviewed] README.md

docs/reference-stack/scripts/

• [reviewed] canary_c2_reconcile.sh
• [reviewed] canary_c6_engine_wiring.sh
• [reviewed] default_install_smoke.sh

hack/verify-samples/

• [reviewed] admission_test.go
• [reviewed] main.go

internal/adapters/builtin/

• [reviewed] boundaries_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/adapters/builtin/runtime/

• [reviewed] contract_aliases_test.go
• [reviewed] doc.go
• [reviewed] lmcachecheck.go
• [reviewed] lmcachecheck_script_test.go
• [reviewed] lmcachecheck_test.go
• [reviewed] sglang_hicache.go
• [reviewed] sglang_hicache_test.go
• [reviewed] sglang_lmcache.go
• [reviewed] sglang_lmcache_test.go
• [reviewed] sglang_lmcache_wire.go
• [reviewed] vllm_lmcache.go
• [reviewed] vllm_lmcache_test.go
• [reviewed] vllm_lmcache_wire.go
• [reviewed] vllm_lmcache_wire_test.go

internal/adapters/builtin/storage/

• [reviewed] effective_config.go
• [reviewed] lmcache_server.go
• [reviewed] mooncake.go
• [reviewed] redis.go
• [reviewed] redis_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/controller/

• [reviewed] cachebackend_autoscaling_test.go
• [reviewed] cachebackend_controller.go
• [reviewed] cachebackend_controller_test.go
• [reviewed] cachebackend_engine_compat.go
• [reviewed] cachebackend_events_only_integration_test.go
• [reviewed] cachebackend_events_test.go
• [reviewed] cachebackend_hostnetwork_test.go
• [reviewed] cachebackend_kvevent_gate_test.go
• [reviewed] cachebackend_matched_pods_test.go
• [reviewed] cachebackend_mooncake_hostnetwork_integration_test.go
• [reviewed] cachebackend_probe.go
• [reviewed] cachebackend_probe_integration_test.go
• [reviewed] cachebackend_probe_test.go
• [reviewed] cachebackend_resources_integration_test.go
• [reviewed] cachebackend_schema_trim_integration_test.go
• [reviewed] cachebackend_t2degraded_test.go
• [reviewed] contract_coverage_sweep_test.go
• [reviewed] integration_test.go

internal/webhook/pod/

• [reviewed] doc.go
• [reviewed] envtest_integration_test.go
• [reviewed] podinjector.go
• [reviewed] podinjector_test.go

internal/webhook/v1alpha1/

• [reviewed] cachebackend_defaulter_envtest_test.go
• [reviewed] cachebackend_webhook.go
• [reviewed] cachebackend_webhook_test.go

pkg/adapters/runtime/

• [reviewed] adapter.go
• [reviewed] adapter_test.go
• [reviewed] doc.go
• [reviewed] kernelcheck.go
• [reviewed] kvevent_subscriber.go
• [reviewed] reference.go
• [reviewed] wire_contract.go
• [reviewed] deleted provider_compat.go
• [reviewed] deleted vllm_lmcache_kernelcheck.go
• [reviewed] deleted vllm_mooncake.go
• [reviewed] deleted vllm_mooncake_test.go

pkg/adapters/runtime/external/

• [reviewed] deleted doc.go
• [reviewed] deleted external.go
• [reviewed] deleted external_test.go

pkg/adapters/runtime/sglang/

• [reviewed] deleted doc.go

pkg/cli/doctor/checks/

• [reviewed] cachebackend.go
• [reviewed] checks_test.go

site/content/en/docs/concepts/

• [reviewed] architecture.md
• [reviewed] cachebackend.md

site/content/en/docs/developer-guide/

• [reviewed] _index.md

site/content/en/docs/reference/

• [reviewed] crd-api.md

site/content/en/docs/tasks/

• [reviewed] bind-an-engine.md
• [reviewed] deploy-a-cache-backend.md

Findings

Blocking

None.

Should-fix

• docs/reference-stack/manifests/sglang-lmcache/README.md:16 — The renamed Redis implementation is referenced as internal/adapters/builtin/storage/redis_l2.go, but the file is now redis.go. This leaves the updated repository-boundary documentation pointing to a nonexistent source file.

Nit

• docs/design/sglang-lmcache-mp-mode.md:415 — The phased-delivery history still refers generically to the removed enginewire.go; the implementation now lives in internal/adapters/builtin/runtime/sglang_lmcache_wire.go. Updating the reference would make the migration documentation internally consistent.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: docs/reference-stack/manifests/sglang-lmcache/README.md:16, docs/design/sglang-lmcache-mp-mode.md:415
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): Clean

Verdict

approve-with-nits

[codecov]

Codecov Report

❌ Patch coverage is 91.47727% with 30 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/adapters/builtin/runtime/lmcachecheck.go	85.29%	5 Missing and 5 partials ⚠️
internal/webhook/v1alpha1/cachebackend_webhook.go	93.58%	5 Missing ⚠️
internal/webhook/pod/podinjector.go	50.00%	3 Missing and 1 partial ⚠️
pkg/adapters/runtime/wire_contract.go	93.65%	3 Missing and 1 partial ⚠️
...nternal/adapters/builtin/runtime/sglang_hicache.go	82.35%	3 Missing ⚠️
api/v1alpha1/cachebackend_effective.go	80.00%	0 Missing and 1 partial ⚠️
internal/adapters/builtin/runtime/vllm_lmcache.go	95.83%	0 Missing and 1 partial ⚠️
internal/controller/cachebackend_controller.go	93.33%	0 Missing and 1 partial ⚠️
internal/controller/cachebackend_engine_compat.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Codex review

Files reviewed

api/v1alpha1

• [reviewed] cachebackend_effective.go
• [reviewed] cachebackend_effective_test.go
• [reviewed] cachebackend_types.go
• [reviewed] cachebackend_types_test.go
• [skipped — generated] zz_generated.deepcopy.go

cmd/inferencecache

• [reviewed] doctor_integration_test.go

config/crd/bases

• [skipped — generated] inferencecache.io_cachebackends.yaml

config/samples

• [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml
• [reviewed] cache_v1alpha1_cachebackend.yaml
• [reviewed] cachebackend-cpu-override.yaml

docs/cli

• [reviewed] doctor.md

docs/concepts

• [reviewed] cachebackend-engine-binding.md
• [reviewed] cachebackend-engine-overrides.md

docs/design

• [reviewed] cachebackend-api.md
• [reviewed] grpc-tls.md
• [reviewed] kvevent-subscriber-wiring.md
• [reviewed] lmcache-server-persistence.md
• [reviewed] repository-boundaries.md
• [reviewed] sglang-lmcache-mp-mode.md

docs/observability

• [reviewed] alerts.md

docs/reference-stack

• [reviewed] README.md
• [reviewed] VERSIONS.md
• [reviewed] manifests/sglang-lmcache/README.md
• [reviewed] manifests/sglang-lmcache/deployment.yaml
• [reviewed] scripts/canary_c2_reconcile.sh
• [reviewed] scripts/canary_c6_engine_wiring.sh
• [reviewed] scripts/default_install_smoke.sh

hack/verify-samples

• [reviewed] admission_test.go
• [reviewed] main.go

internal/adapters/builtin

• [reviewed] boundaries_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/adapters/builtin/runtime

• [reviewed] contract_aliases_test.go
• [reviewed] doc.go
• [reviewed] lmcachecheck.go
• [reviewed] lmcachecheck_script_test.go
• [reviewed] lmcachecheck_test.go
• [reviewed] sglang_hicache.go
• [reviewed] sglang_hicache_test.go
• [reviewed] sglang_lmcache.go
• [reviewed] sglang_lmcache_test.go
• [reviewed] sglang_lmcache_wire.go
• [reviewed] vllm_lmcache.go
• [reviewed] vllm_lmcache_test.go
• [reviewed] vllm_lmcache_wire.go
• [reviewed] vllm_lmcache_wire_test.go

internal/adapters/builtin/storage

• [reviewed] effective_config.go
• [reviewed] lmcache_server.go
• [reviewed] mooncake.go
• [reviewed] redis.go
• [reviewed] redis_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/controller

• [reviewed] cachebackend_autoscaling_test.go
• [reviewed] cachebackend_controller.go
• [reviewed] cachebackend_controller_test.go
• [reviewed] cachebackend_engine_compat.go
• [reviewed] cachebackend_events_only_integration_test.go
• [reviewed] cachebackend_events_test.go
• [reviewed] cachebackend_hostnetwork_test.go
• [reviewed] cachebackend_kvevent_gate_test.go
• [reviewed] cachebackend_matched_pods_test.go
• [reviewed] cachebackend_mooncake_hostnetwork_integration_test.go
• [reviewed] cachebackend_probe.go
• [reviewed] cachebackend_probe_integration_test.go
• [reviewed] cachebackend_probe_test.go
• [reviewed] cachebackend_resources_integration_test.go
• [reviewed] cachebackend_schema_trim_integration_test.go
• [reviewed] cachebackend_t2degraded_test.go
• [reviewed] contract_coverage_sweep_test.go
• [reviewed] integration_test.go

internal/webhook/pod

• [reviewed] doc.go
• [reviewed] envtest_integration_test.go
• [reviewed] podinjector.go
• [reviewed] podinjector_test.go

internal/webhook/v1alpha1

• [reviewed] cachebackend_defaulter_envtest_test.go
• [reviewed] cachebackend_webhook.go
• [reviewed] cachebackend_webhook_test.go

pkg/adapters/runtime

• [reviewed] adapter.go
• [reviewed] adapter_test.go
• [reviewed] doc.go
• [reviewed] external/doc.go (deleted)
• [reviewed] external/external.go (deleted)
• [reviewed] external/external_test.go (deleted)
• [reviewed] kernelcheck.go
• [reviewed] kvevent_subscriber.go
• [reviewed] provider_compat.go (deleted)
• [reviewed] reference.go
• [reviewed] sglang/doc.go (deleted)
• [reviewed] vllm_lmcache_kernelcheck.go (deleted)
• [reviewed] vllm_mooncake.go (deleted)
• [reviewed] vllm_mooncake_test.go (deleted)
• [reviewed] wire_contract.go

pkg/cli/doctor/checks

• [reviewed] cachebackend.go
• [reviewed] checks_test.go

site/content/en/docs

• [reviewed] concepts/architecture.md
• [reviewed] concepts/cachebackend.md
• [reviewed] developer-guide/_index.md
• [reviewed] reference/crd-api.md
• [reviewed] tasks/bind-an-engine.md
• [reviewed] tasks/deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:21 — The served v1alpha1 enum removes AIBrix, Mooncake, NIXL, and External. Existing resources using those accepted values will fail validation on update, violating the required backward-compatibility rule.

• api/v1alpha1/cachebackend_types.go:298 — spec.runtime changes from optional with an effective VLLM default to required. Existing persisted resources without the field can no longer be updated unless migrated first.

• api/v1alpha1/cachebackend_types.go:295 — The PR removes served fields including backendConfig, top-level resources, endpoint, and compatibility integration fields without conversion or forwarding. Kubernetes will prune those values, and the old resource semantics cannot be preserved; “not formally deployed” does not satisfy the stated requirement that v1alpha1 remain backward-compatible.

Should-fix

• pkg/adapters/runtime/adapter.go:44 — Verify: adding SupportsBinding and changing both injection signatures is a source-breaking change to the documented out-of-tree extension package. External adapters will stop compiling, so this needs an explicit supported-contract versioning or migration policy rather than being described as preserving the existing contract.

Nit

• internal/webhook/v1alpha1/cachebackend_webhook.go:77 — The defaulter documentation still says nested defaults include engine and firstEventTimeout, although both were removed from spec.integration. This now misdocuments the persisted API behavior.

• internal/adapters/builtin/runtime/vllm_lmcache.go:220 — The comment directs new tests to the deleted pkg/adapters/runtime/internal/ location. It should point to the new built-in runtime package.

• internal/adapters/builtin/storage/registry.go:1 — The package comment says “Package provider” while the package is now named storage.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:21, api/v1alpha1/cachebackend_types.go:295, api/v1alpha1/cachebackend_types.go:298, pkg/adapters/runtime/adapter.go:44, internal/webhook/v1alpha1/cachebackend_webhook.go:77
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): findings above at: internal/adapters/builtin/runtime/vllm_lmcache.go:220, internal/adapters/builtin/storage/registry.go:1

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

api/v1alpha1

• [reviewed] cachebackend_effective.go
• [reviewed] cachebackend_effective_test.go
• [reviewed] cachebackend_types.go
• [reviewed] cachebackend_types_test.go
• [skipped — generated] zz_generated.deepcopy.go

cmd/inferencecache

• [reviewed] doctor_integration_test.go

config/crd/bases

• [skipped — generated] inferencecache.io_cachebackends.yaml

config/samples

• [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml
• [reviewed] cache_v1alpha1_cachebackend.yaml
• [reviewed] cachebackend-cpu-override.yaml

docs/cli

• [reviewed] doctor.md

docs/concepts

• [reviewed] cachebackend-engine-binding.md
• [reviewed] cachebackend-engine-overrides.md

docs/design

• [reviewed] cachebackend-api.md
• [reviewed] grpc-tls.md
• [reviewed] kvevent-subscriber-wiring.md
• [reviewed] lmcache-server-persistence.md
• [reviewed] repository-boundaries.md
• [reviewed] sglang-lmcache-mp-mode.md

docs/observability

• [reviewed] alerts.md

docs/reference-stack

• [reviewed] README.md
• [reviewed] VERSIONS.md
• [reviewed] manifests/sglang-lmcache/README.md
• [reviewed] manifests/sglang-lmcache/deployment.yaml
• [reviewed] scripts/canary_c2_reconcile.sh
• [reviewed] scripts/canary_c6_engine_wiring.sh
• [reviewed] scripts/default_install_smoke.sh

hack/verify-samples

• [reviewed] admission_test.go
• [reviewed] main.go

internal/adapters/builtin

• [reviewed] boundaries_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/adapters/builtin/runtime

• [reviewed] contract_aliases_test.go
• [reviewed] doc.go
• [reviewed] lmcachecheck.go
• [reviewed] lmcachecheck_script_test.go
• [reviewed] lmcachecheck_test.go
• [reviewed] sglang_hicache.go
• [reviewed] sglang_hicache_test.go
• [reviewed] sglang_lmcache.go
• [reviewed] sglang_lmcache_test.go
• [reviewed] sglang_lmcache_wire.go
• [reviewed] vllm_lmcache.go
• [reviewed] vllm_lmcache_test.go
• [reviewed] vllm_lmcache_wire.go
• [reviewed] vllm_lmcache_wire_test.go

internal/adapters/builtin/storage

• [reviewed] effective_config.go
• [reviewed] lmcache_server.go
• [reviewed] mooncake.go
• [reviewed] redis.go
• [reviewed] redis_test.go
• [reviewed] registry.go
• [reviewed] registry_test.go

internal/controller

• [reviewed] cachebackend_autoscaling_test.go
• [reviewed] cachebackend_controller.go
• [reviewed] cachebackend_controller_test.go
• [reviewed] cachebackend_engine_compat.go
• [reviewed] cachebackend_events_only_integration_test.go
• [reviewed] cachebackend_events_test.go
• [reviewed] cachebackend_hostnetwork_test.go
• [reviewed] cachebackend_kvevent_gate_test.go
• [reviewed] cachebackend_matched_pods_test.go
• [reviewed] cachebackend_mooncake_hostnetwork_integration_test.go
• [reviewed] cachebackend_probe.go
• [reviewed] cachebackend_probe_integration_test.go
• [reviewed] cachebackend_probe_test.go
• [reviewed] cachebackend_resources_integration_test.go
• [reviewed] cachebackend_schema_trim_integration_test.go
• [reviewed] cachebackend_t2degraded_test.go
• [reviewed] contract_coverage_sweep_test.go
• [reviewed] integration_test.go

internal/webhook/pod

• [reviewed] doc.go
• [reviewed] envtest_integration_test.go
• [reviewed] podinjector.go
• [reviewed] podinjector_test.go

internal/webhook/v1alpha1

• [reviewed] cachebackend_defaulter_envtest_test.go
• [reviewed] cachebackend_webhook.go
• [reviewed] cachebackend_webhook_test.go

pkg/adapters/runtime

• [reviewed] adapter.go
• [reviewed] adapter_test.go
• [reviewed] doc.go
• [reviewed] external/doc.go (deleted)
• [reviewed] external/external.go (deleted)
• [reviewed] external/external_test.go (deleted)
• [reviewed] kernelcheck.go
• [reviewed] kvevent_subscriber.go
• [reviewed] provider_compat.go (deleted)
• [reviewed] reference.go
• [reviewed] sglang/doc.go (deleted)
• [reviewed] vllm_lmcache_kernelcheck.go (deleted)
• [reviewed] vllm_mooncake.go (deleted)
• [reviewed] vllm_mooncake_test.go (deleted)
• [reviewed] wire_contract.go

pkg/cli/doctor/checks

• [reviewed] cachebackend.go
• [reviewed] checks_test.go

site/content/en/docs

• [reviewed] concepts/architecture.md
• [reviewed] concepts/cachebackend.md
• [reviewed] developer-guide/_index.md
• [reviewed] reference/crd-api.md
• [reviewed] tasks/bind-an-engine.md
• [reviewed] tasks/deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:296 — This makes spec.runtime required while removing served v1alpha1 fields such as integration.engine, integration.firstEventTimeout, backendConfig, top-level resources, and endpoint. Existing persisted manifests can no longer round-trip or update, violating the review’s explicit v1alpha1 backward-compatibility requirement; the absence of formal deployments does not satisfy that contract.

Should-fix

None.

Nit

• internal/webhook/v1alpha1/cachebackend_webhook.go:849 — The comment still claims an unset runtime defaults to vLLM, but ResolveRuntimeID now returns an empty ID and the schema requires spec.runtime. Update the comment so it describes the implemented contract.
• api/v1alpha1/cachebackend_types.go:491 — The Go documentation links to [enginewire.IntegrationRole], but that package/symbol reference was removed during the adapter move. Replace it with the current helper or plain text.
• internal/webhook/v1alpha1/cachebackend_webhook.go:584 — This second [enginewire.IntegrationRole] reference is likewise stale after internalizing the engine-wire implementation.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:296, internal/webhook/v1alpha1/cachebackend_webhook.go:849, api/v1alpha1/cachebackend_types.go:491, internal/webhook/v1alpha1/cachebackend_webhook.go:584
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): Clean

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

• api/v1alpha1/

  • [reviewed] cachebackend_effective.go
  • [reviewed] cachebackend_effective_test.go
  • [reviewed] cachebackend_types.go
  • [reviewed] cachebackend_types_test.go
  • [skipped — generated] zz_generated.deepcopy.go

• cmd/inferencecache/

  • [reviewed] doctor_integration_test.go

• config/crd/bases/

  • [skipped — generated] inferencecache.io_cachebackends.yaml

• config/samples/

  • [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml
  • [reviewed] cache_v1alpha1_cachebackend.yaml
  • [reviewed] cachebackend-cpu-override.yaml

• docs/cli/

  • [reviewed] doctor.md

• docs/concepts/

  • [reviewed] cachebackend-engine-binding.md
  • [reviewed] cachebackend-engine-overrides.md

• docs/design/

  • [reviewed] cachebackend-api.md
  • [reviewed] grpc-tls.md
  • [reviewed] kvevent-subscriber-wiring.md
  • [reviewed] lmcache-server-persistence.md
  • [reviewed] repository-boundaries.md
  • [reviewed] sglang-lmcache-mp-mode.md

• docs/observability/

  • [reviewed] alerts.md

• docs/reference-stack/

  • [reviewed] README.md
  • [reviewed] VERSIONS.md
  • [reviewed] manifests/sglang-lmcache/README.md
  • [reviewed] manifests/sglang-lmcache/deployment.yaml
  • [reviewed] scripts/canary_c2_reconcile.sh
  • [reviewed] scripts/canary_c6_engine_wiring.sh
  • [reviewed] scripts/default_install_smoke.sh

• hack/verify-samples/

  • [reviewed] admission_test.go
  • [reviewed] main.go

• internal/adapters/builtin/

  • [reviewed] boundaries_test.go
  • [reviewed] registry.go
  • [reviewed] registry_test.go

• internal/adapters/builtin/runtime/

  • [reviewed] contract_aliases_test.go
  • [reviewed] doc.go
  • [reviewed] lmcachecheck.go
  • [reviewed] lmcachecheck_script_test.go (moved)
  • [reviewed] lmcachecheck_test.go (moved)
  • [reviewed] sglang_hicache.go (moved)
  • [reviewed] sglang_hicache_test.go (moved)
  • [reviewed] sglang_lmcache.go (moved)
  • [reviewed] sglang_lmcache_test.go (moved)
  • [reviewed] sglang_lmcache_wire.go (moved)
  • [reviewed] vllm_lmcache.go (moved)
  • [reviewed] vllm_lmcache_test.go (moved)
  • [reviewed] vllm_lmcache_wire.go (moved)
  • [reviewed] vllm_lmcache_wire_test.go (moved)

• internal/adapters/builtin/storage/

  • [reviewed] effective_config.go (moved)
  • [reviewed] lmcache_server.go (moved)
  • [reviewed] mooncake.go (moved)
  • [reviewed] redis.go (moved)
  • [reviewed] redis_test.go (moved)
  • [reviewed] registry.go (moved)
  • [reviewed] registry_test.go (moved)

• internal/controller/

  • [reviewed] cachebackend_autoscaling_test.go
  • [reviewed] cachebackend_controller.go
  • [reviewed] cachebackend_controller_test.go
  • [reviewed] cachebackend_engine_compat.go
  • [reviewed] cachebackend_events_only_integration_test.go
  • [reviewed] cachebackend_events_test.go
  • [reviewed] cachebackend_hostnetwork_test.go
  • [reviewed] cachebackend_kvevent_gate_test.go
  • [reviewed] cachebackend_matched_pods_test.go
  • [reviewed] cachebackend_mooncake_hostnetwork_integration_test.go
  • [reviewed] cachebackend_probe.go
  • [reviewed] cachebackend_probe_integration_test.go
  • [reviewed] cachebackend_probe_test.go
  • [reviewed] cachebackend_resources_integration_test.go
  • [reviewed] cachebackend_schema_trim_integration_test.go
  • [reviewed] cachebackend_t2degraded_test.go
  • [reviewed] contract_coverage_sweep_test.go
  • [reviewed] integration_test.go

• internal/webhook/pod/

  • [reviewed] doc.go
  • [reviewed] envtest_integration_test.go
  • [reviewed] podinjector.go
  • [reviewed] podinjector_test.go

• internal/webhook/v1alpha1/

  • [reviewed] cachebackend_defaulter_envtest_test.go
  • [reviewed] cachebackend_webhook.go
  • [reviewed] cachebackend_webhook_test.go

• pkg/adapters/backend/provider/

  • [reviewed] effective_config.go (moved)
  • [reviewed] lmcache_server.go (moved)
  • [reviewed] mooncake.go (moved)
  • [reviewed] provider.go (moved)
  • [reviewed] provider_test.go (moved)
  • [reviewed] redis_l2.go (moved)
  • [reviewed] redis_l2_test.go (moved)

• pkg/adapters/runtime/

  • [reviewed] adapter.go
  • [reviewed] adapter_test.go
  • [reviewed] doc.go
  • [reviewed] external/doc.go (deleted)
  • [reviewed] external/external.go (deleted)
  • [reviewed] external/external_test.go (deleted)
  • [reviewed] internal/enginewire/enginewire.go (moved)
  • [reviewed] internal/enginewire/enginewire_test.go (moved)
  • [reviewed] internal/enginewire/sglang_mp.go (moved)
  • [reviewed] kernelcheck.go
  • [reviewed] kernelcheck_script_test.go (moved)
  • [reviewed] kernelcheck_test.go (moved)
  • [reviewed] kvevent_subscriber.go
  • [reviewed] provider_compat.go (deleted)
  • [reviewed] reference.go
  • [reviewed] sglang/doc.go (deleted)
  • [reviewed] sglang/hicache.go (moved)
  • [reviewed] sglang/hicache_test.go (moved)
  • [reviewed] sglang/sglang.go (moved)
  • [reviewed] sglang/sglang_test.go (moved)
  • [reviewed] vllm_lmcache.go (moved)
  • [reviewed] vllm_lmcache_kernelcheck.go (deleted)
  • [reviewed] vllm_lmcache_test.go (moved)
  • [reviewed] vllm_mooncake.go (deleted)
  • [reviewed] vllm_mooncake_test.go (deleted)
  • [reviewed] wire_contract.go

• pkg/cli/doctor/checks/

  • [reviewed] cachebackend.go
  • [reviewed] checks_test.go

• site/content/en/docs/

  • [reviewed] concepts/architecture.md
  • [reviewed] concepts/cachebackend.md
  • [reviewed] developer-guide/_index.md
  • [reviewed] reference/crd-api.md
  • [reviewed] tasks/bind-an-engine.md
  • [reviewed] tasks/deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:293 — This makes spec.runtime required while also removing spec.backendConfig, top-level spec.resources, spec.endpoint, spec.integration.engine, and spec.integration.firstEventTimeout from the served v1alpha1 shape. That is a breaking CRD change explicitly prohibited by the review contract; absence of formal deployments does not preserve API compatibility.

• api/v1alpha1/cachebackend_types.go:306 — Adding an enum limited to LMCache and SGLangHiCache rejects previously valid persisted AIBrix, Mooncake, NIXL, and External values on subsequent writes. This is another incompatible tightening of the same served v1alpha1 API without conversion or compatibility handling.

Should-fix

None.

Nit

• internal/controller/cachebackend_controller.go:158 — Comments at lines 158–175 and 528–533 still describe external ownership through removed spec.endpoint and a deleted “passthrough adapter.” They should name spec.remoteStorage.endpoint and the structured external binding path.

• internal/webhook/pod/podinjector.go:560 — The endpoint-source comment still calls the external field spec.endpoint; the implemented source is spec.remoteStorage.endpoint.

• internal/adapters/builtin/runtime/vllm_lmcache_wire.go:87 — The comment says a separate External passthrough adapter calls this helper and sources spec.endpoint, but that adapter and field are removed by this PR. The vLLM adapter now handles external LMCache bindings directly.

• internal/controller/cachebackend_controller_test.go:1335 — Multiple changed test comments still refer to mirroring or validating removed spec.endpoint (including lines 1391, 1433, and 1632), making the new structured-binding tests misleading.

• internal/controller/integration_test.go:604 — The comment identifies removed spec.endpoint as the external readiness signal; it should identify spec.remoteStorage.endpoint.

• internal/webhook/pod/podinjector_test.go:1093 — Several changed test comments still describe the removed External type and spec.endpoint source (also lines 1151, 1231–1234, 1278–1280, 1317, 1376, and 1412). They should describe external ownership and spec.remoteStorage.endpoint.

• internal/webhook/v1alpha1/cachebackend_webhook_test.go:1738 — The endpoint-validation comment still names removed spec.endpoint.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:293, api/v1alpha1/cachebackend_types.go:306
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): findings above at: internal/controller/cachebackend_controller.go:158, internal/webhook/pod/podinjector.go:560, internal/adapters/builtin/runtime/vllm_lmcache_wire.go:87, internal/controller/cachebackend_controller_test.go:1335, internal/controller/integration_test.go:604, internal/webhook/pod/podinjector_test.go:1093, internal/webhook/v1alpha1/cachebackend_webhook_test.go:1738

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

api

• [reviewed] api/v1alpha1/cachebackend_effective.go
• [reviewed] api/v1alpha1/cachebackend_effective_test.go
• [reviewed] api/v1alpha1/cachebackend_types.go
• [reviewed] api/v1alpha1/cachebackend_types_test.go
• [skipped — generated] api/v1alpha1/zz_generated.deepcopy.go

cmd

• [reviewed] cmd/inferencecache/doctor_integration_test.go

config

• [skipped — generated] config/crd/bases/inferencecache.io_cachebackends.yaml
• [reviewed] config/samples/_test/cachebackend-invalid-scale-to-zero-no-min.yaml
• [reviewed] config/samples/cache_v1alpha1_cachebackend.yaml
• [reviewed] config/samples/cachebackend-cpu-override.yaml

docs

• [reviewed] docs/cli/doctor.md
• [reviewed] docs/concepts/cachebackend-engine-binding.md
• [reviewed] docs/concepts/cachebackend-engine-overrides.md
• [reviewed] docs/design/cachebackend-api.md
• [reviewed] docs/design/grpc-tls.md
• [reviewed] docs/design/kvevent-subscriber-wiring.md
• [reviewed] docs/design/lmcache-server-persistence.md
• [reviewed] docs/design/repository-boundaries.md
• [reviewed] docs/design/sglang-lmcache-mp-mode.md
• [reviewed] docs/observability/alerts.md
• [reviewed] docs/reference-stack/README.md
• [reviewed] docs/reference-stack/VERSIONS.md
• [reviewed] docs/reference-stack/manifests/sglang-lmcache/README.md
• [reviewed] docs/reference-stack/manifests/sglang-lmcache/deployment.yaml
• [reviewed] docs/reference-stack/scripts/canary_c2_reconcile.sh
• [reviewed] docs/reference-stack/scripts/canary_c6_engine_wiring.sh
• [reviewed] docs/reference-stack/scripts/default_install_smoke.sh

hack

• [reviewed] hack/verify-samples/admission_test.go
• [reviewed] hack/verify-samples/main.go

internal/adapters

• [reviewed] internal/adapters/builtin/boundaries_test.go
• [reviewed] internal/adapters/builtin/registry.go
• [reviewed] internal/adapters/builtin/registry_test.go
• [reviewed] internal/adapters/builtin/runtime/contract_aliases_test.go
• [reviewed] internal/adapters/builtin/runtime/doc.go
• [reviewed] internal/adapters/builtin/runtime/lmcachecheck.go
• [reviewed] internal/adapters/builtin/runtime/lmcachecheck_script_test.go
• [reviewed] internal/adapters/builtin/runtime/lmcachecheck_test.go
• [reviewed] internal/adapters/builtin/runtime/sglang_hicache.go
• [reviewed] internal/adapters/builtin/runtime/sglang_hicache_test.go
• [reviewed] internal/adapters/builtin/runtime/sglang_lmcache.go
• [reviewed] internal/adapters/builtin/runtime/sglang_lmcache_test.go
• [reviewed] internal/adapters/builtin/runtime/sglang_lmcache_wire.go
• [reviewed] internal/adapters/builtin/runtime/vllm_lmcache.go
• [reviewed] internal/adapters/builtin/runtime/vllm_lmcache_test.go
• [reviewed] internal/adapters/builtin/runtime/vllm_lmcache_wire.go
• [reviewed] internal/adapters/builtin/runtime/vllm_lmcache_wire_test.go
• [reviewed] internal/adapters/builtin/storage/effective_config.go
• [reviewed] internal/adapters/builtin/storage/lmcache_server.go
• [reviewed] internal/adapters/builtin/storage/mooncake.go
• [reviewed] internal/adapters/builtin/storage/redis.go
• [reviewed] internal/adapters/builtin/storage/redis_test.go
• [reviewed] internal/adapters/builtin/storage/registry.go
• [reviewed] internal/adapters/builtin/storage/registry_test.go

internal/controller

• [reviewed] internal/controller/cachebackend_autoscaling_test.go
• [reviewed] internal/controller/cachebackend_controller.go
• [reviewed] internal/controller/cachebackend_controller_test.go
• [reviewed] internal/controller/cachebackend_engine_compat.go
• [reviewed] internal/controller/cachebackend_events_only_integration_test.go
• [reviewed] internal/controller/cachebackend_events_test.go
• [reviewed] internal/controller/cachebackend_hostnetwork_test.go
• [reviewed] internal/controller/cachebackend_kvevent_gate_test.go
• [reviewed] internal/controller/cachebackend_matched_pods_test.go
• [reviewed] internal/controller/cachebackend_mooncake_hostnetwork_integration_test.go
• [reviewed] internal/controller/cachebackend_probe.go
• [reviewed] internal/controller/cachebackend_probe_integration_test.go
• [reviewed] internal/controller/cachebackend_probe_test.go
• [reviewed] internal/controller/cachebackend_resources_integration_test.go
• [reviewed] internal/controller/cachebackend_schema_trim_integration_test.go
• [reviewed] internal/controller/cachebackend_t2degraded_test.go
• [reviewed] internal/controller/contract_coverage_sweep_test.go
• [reviewed] internal/controller/integration_test.go

internal/webhook

• [reviewed] internal/webhook/pod/doc.go
• [reviewed] internal/webhook/pod/envtest_integration_test.go
• [reviewed] internal/webhook/pod/podinjector.go
• [reviewed] internal/webhook/pod/podinjector_test.go
• [reviewed] internal/webhook/v1alpha1/cachebackend_defaulter_envtest_test.go
• [reviewed] internal/webhook/v1alpha1/cachebackend_webhook.go
• [reviewed] internal/webhook/v1alpha1/cachebackend_webhook_test.go

pkg

• [reviewed] pkg/adapters/runtime/adapter.go
• [reviewed] pkg/adapters/runtime/adapter_test.go
• [reviewed] pkg/adapters/runtime/doc.go
• [reviewed] pkg/adapters/runtime/external/doc.go
• [reviewed] pkg/adapters/runtime/external/external.go
• [reviewed] pkg/adapters/runtime/external/external_test.go
• [reviewed] pkg/adapters/runtime/kernelcheck.go
• [reviewed] pkg/adapters/runtime/kvevent_subscriber.go
• [reviewed] pkg/adapters/runtime/provider_compat.go
• [reviewed] pkg/adapters/runtime/reference.go
• [reviewed] pkg/adapters/runtime/sglang/doc.go
• [reviewed] pkg/adapters/runtime/vllm_lmcache_kernelcheck.go
• [reviewed] pkg/adapters/runtime/vllm_mooncake.go
• [reviewed] pkg/adapters/runtime/vllm_mooncake_test.go
• [reviewed] pkg/adapters/runtime/wire_contract.go
• [reviewed] pkg/cli/doctor/checks/cachebackend.go
• [reviewed] pkg/cli/doctor/checks/checks_test.go

site

• [reviewed] site/content/en/docs/concepts/architecture.md
• [reviewed] site/content/en/docs/concepts/cachebackend.md
• [reviewed] site/content/en/docs/developer-guide/_index.md
• [reviewed] site/content/en/docs/reference/crd-api.md
• [reviewed] site/content/en/docs/tasks/bind-an-engine.md
• [reviewed] site/content/en/docs/tasks/deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:298 — This makes spec.runtime required while removing previously served fields and accepted cache types without a conversion or migration path. Existing v1alpha1 objects will be pruned or become invalid on update, directly violating the project’s stated requirement that CRD changes remain backward-compatible.

Should-fix

• site/content/en/docs/reference/crd-api.md:20 — The PR rewrites the compatibility documentation to permit breaking v1alpha1 changes. Changing the documentation does not resolve the contract violation; retain the compatibility promise and introduce a new API version or migration path for this cleanup.
• docs/design/repository-boundaries.md:239 — The design declares the breaking cleanup acceptable solely because no formal deployment occurred. Repository policy requires compatibility for v1alpha1 consumers, so this plan needs to specify conversion, forwarding, or versioning instead of asserting that none is needed.

Nit

None.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:298, site/content/en/docs/reference/crd-api.md:20, docs/design/repository-boundaries.md:239
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): Clean

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

• api/v1alpha1/

  • [reviewed] cachebackend_effective.go
  • [reviewed] cachebackend_effective_test.go
  • [reviewed] cachebackend_types.go
  • [reviewed] cachebackend_types_test.go
  • [skipped — generated] zz_generated.deepcopy.go

• cmd/inferencecache/

  • [reviewed] doctor_integration_test.go

• config/crd/bases/

  • [skipped — generated] inferencecache.io_cachebackends.yaml

• config/samples/

  • [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml
  • [reviewed] cache_v1alpha1_cachebackend.yaml
  • [reviewed] cachebackend-cpu-override.yaml

• docs/cli/

  • [reviewed] doctor.md

• docs/concepts/

  • [reviewed] cachebackend-engine-binding.md
  • [reviewed] cachebackend-engine-overrides.md

• docs/design/

  • [reviewed] cachebackend-api.md
  • [reviewed] grpc-tls.md
  • [reviewed] kvevent-subscriber-wiring.md
  • [reviewed] lmcache-server-persistence.md
  • [reviewed] repository-boundaries.md
  • [reviewed] sglang-lmcache-mp-mode.md

• docs/observability/

  • [reviewed] alerts.md

• docs/reference-stack/

  • [reviewed] README.md
  • [reviewed] VERSIONS.md
  • [reviewed] manifests/sglang-lmcache/README.md
  • [reviewed] manifests/sglang-lmcache/deployment.yaml
  • [reviewed] scripts/canary_c2_reconcile.sh
  • [reviewed] scripts/canary_c6_engine_wiring.sh
  • [reviewed] scripts/default_install_smoke.sh

• hack/verify-samples/

  • [reviewed] admission_test.go
  • [reviewed] main.go

• internal/adapters/builtin/

  • [reviewed] boundaries_test.go
  • [reviewed] registry.go
  • [reviewed] registry_test.go

• internal/adapters/builtin/runtime/

  • [reviewed] contract_aliases_test.go
  • [reviewed] doc.go
  • [reviewed] lmcachecheck.go
  • [reviewed] lmcachecheck_script_test.go
  • [reviewed] lmcachecheck_test.go
  • [reviewed] sglang_hicache.go
  • [reviewed] sglang_hicache_test.go
  • [reviewed] sglang_lmcache.go
  • [reviewed] sglang_lmcache_test.go
  • [reviewed] sglang_lmcache_wire.go
  • [reviewed] vllm_lmcache.go
  • [reviewed] vllm_lmcache_test.go
  • [reviewed] vllm_lmcache_wire.go
  • [reviewed] vllm_lmcache_wire_test.go

• internal/adapters/builtin/storage/

  • [reviewed] effective_config.go
  • [reviewed] lmcache_server.go
  • [reviewed] mooncake.go
  • [reviewed] redis.go
  • [reviewed] redis_test.go
  • [reviewed] registry.go
  • [reviewed] registry_test.go

• internal/controller/

  • [reviewed] cachebackend_autoscaling_test.go
  • [reviewed] cachebackend_controller.go
  • [reviewed] cachebackend_controller_test.go
  • [reviewed] cachebackend_engine_compat.go
  • [reviewed] cachebackend_events_only_integration_test.go
  • [reviewed] cachebackend_events_test.go
  • [reviewed] cachebackend_hostnetwork_test.go
  • [reviewed] cachebackend_kvevent_gate_test.go
  • [reviewed] cachebackend_matched_pods_test.go
  • [reviewed] cachebackend_mooncake_hostnetwork_integration_test.go
  • [reviewed] cachebackend_probe.go
  • [reviewed] cachebackend_probe_integration_test.go
  • [reviewed] cachebackend_probe_test.go
  • [reviewed] cachebackend_resources_integration_test.go
  • [reviewed] cachebackend_schema_trim_integration_test.go
  • [reviewed] cachebackend_t2degraded_test.go
  • [reviewed] contract_coverage_sweep_test.go
  • [reviewed] integration_test.go

• internal/webhook/pod/

  • [reviewed] doc.go
  • [reviewed] envtest_integration_test.go
  • [reviewed] podinjector.go
  • [reviewed] podinjector_test.go

• internal/webhook/v1alpha1/

  • [reviewed] cachebackend_defaulter_envtest_test.go
  • [reviewed] cachebackend_webhook.go
  • [reviewed] cachebackend_webhook_test.go

• pkg/adapters/runtime/

  • [reviewed] adapter.go
  • [reviewed] adapter_test.go
  • [reviewed] doc.go
  • [reviewed] external/doc.go (deleted)
  • [reviewed] external/external.go (deleted)
  • [reviewed] external/external_test.go (deleted)
  • [reviewed] kernelcheck.go
  • [reviewed] kvevent_subscriber.go
  • [reviewed] provider_compat.go (deleted)
  • [reviewed] reference.go
  • [reviewed] sglang/doc.go (deleted)
  • [reviewed] vllm_lmcache_kernelcheck.go (deleted)
  • [reviewed] vllm_mooncake.go (deleted)
  • [reviewed] vllm_mooncake_test.go (deleted)
  • [reviewed] wire_contract.go

• pkg/cli/doctor/checks/

  • [reviewed] cachebackend.go
  • [reviewed] checks_test.go

• site/content/en/docs/

  • [reviewed] concepts/architecture.md
  • [reviewed] concepts/cachebackend.md
  • [reviewed] developer-guide/_index.md
  • [reviewed] reference/crd-api.md
  • [reviewed] tasks/bind-an-engine.md
  • [reviewed] tasks/deploy-a-cache-backend.md

Findings

Blocking

api/v1alpha1/cachebackend_types.go:295 — This removes served v1alpha1 fields (backendConfig, top-level resources, endpoint, integration.engine, and integration.firstEventTimeout) without conversion or compatibility handling. Existing objects/manifests lose or reject data, violating the review requirement that v1alpha1 CRD changes remain backward-compatible.

api/v1alpha1/cachebackend_types.go:298 — Making spec.runtime required is another breaking change for existing v1alpha1 manifests that relied on the prior VLLM/default or integration.engine behavior. Lack of formal deployment does not preserve the published API contract required by this review.

Should-fix

None.

Nit

docs/design/grpc-tls.md:12 — The document links DefaultPolicyServerGRPCAddress to deleted file pkg/adapters/runtime/lmcache_shared.go. Point this reference at its current source file.

internal/adapters/builtin/runtime/doc.go:16 — Package documentation likewise names deleted pkg/adapters/runtime/lmcache_shared.go. Update the repository-boundary documentation to the actual shared-helper location.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:295, api/v1alpha1/cachebackend_types.go:298
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): findings above at: docs/design/grpc-tls.md:12, internal/adapters/builtin/runtime/doc.go:16

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

• api/v1alpha1/
  • cachebackend_effective.go [reviewed]
  • cachebackend_effective_test.go [reviewed]
  • cachebackend_types.go [reviewed]
  • cachebackend_types_test.go [reviewed]
  • zz_generated.deepcopy.go [skipped — generated]
• cmd/inferencecache/
  • doctor_integration_test.go [reviewed]
• config/crd/bases/
  • inferencecache.io_cachebackends.yaml [skipped — generated]
• config/samples/
  • _test/cachebackend-invalid-scale-to-zero-no-min.yaml [reviewed]
  • cache_v1alpha1_cachebackend.yaml [reviewed]
  • cachebackend-cpu-override.yaml [reviewed]
• docs/cli/
  • doctor.md [reviewed]
• docs/concepts/
  • cachebackend-engine-binding.md [reviewed]
  • cachebackend-engine-overrides.md [reviewed]
• docs/design/
  • cachebackend-api.md [reviewed]
  • grpc-tls.md [reviewed]
  • kvevent-subscriber-wiring.md [reviewed]
  • lmcache-server-persistence.md [reviewed]
  • repository-boundaries.md [reviewed]
  • sglang-lmcache-mp-mode.md [reviewed]
• docs/observability/
  • alerts.md [reviewed]
• docs/reference-stack/
  • README.md [reviewed]
  • VERSIONS.md [reviewed]
  • manifests/sglang-lmcache/README.md [reviewed]
  • manifests/sglang-lmcache/deployment.yaml [reviewed]
  • scripts/canary_c2_reconcile.sh [reviewed]
  • scripts/canary_c6_engine_wiring.sh [reviewed]
  • scripts/default_install_smoke.sh [reviewed]
• hack/verify-samples/
  • admission_test.go [reviewed]
  • main.go [reviewed]
• internal/adapters/builtin/
  • boundaries_test.go [reviewed]
  • registry.go [reviewed]
  • registry_test.go [reviewed]
• internal/adapters/builtin/runtime/
  • contract_aliases_test.go [reviewed]
  • doc.go [reviewed]
  • lmcachecheck.go [reviewed]
  • lmcachecheck_script_test.go [reviewed]
  • lmcachecheck_test.go [reviewed]
  • sglang_hicache.go [reviewed]
  • sglang_hicache_test.go [reviewed]
  • sglang_lmcache.go [reviewed]
  • sglang_lmcache_test.go [reviewed]
  • sglang_lmcache_wire.go [reviewed]
  • vllm_lmcache.go [reviewed]
  • vllm_lmcache_test.go [reviewed]
  • vllm_lmcache_wire.go [reviewed]
  • vllm_lmcache_wire_test.go [reviewed]
• internal/adapters/builtin/storage/
  • effective_config.go [reviewed]
  • lmcache_server.go [reviewed]
  • mooncake.go [reviewed]
  • redis.go [reviewed]
  • redis_test.go [reviewed]
  • registry.go [reviewed]
  • registry_test.go [reviewed]
• internal/controller/
  • cachebackend_autoscaling_test.go [reviewed]
  • cachebackend_controller.go [reviewed]
  • cachebackend_controller_test.go [reviewed]
  • cachebackend_engine_compat.go [reviewed]
  • cachebackend_events_only_integration_test.go [reviewed]
  • cachebackend_events_test.go [reviewed]
  • cachebackend_hostnetwork_test.go [reviewed]
  • cachebackend_kvevent_gate_test.go [reviewed]
  • cachebackend_matched_pods_test.go [reviewed]
  • cachebackend_mooncake_hostnetwork_integration_test.go [reviewed]
  • cachebackend_probe.go [reviewed]
  • cachebackend_probe_integration_test.go [reviewed]
  • cachebackend_probe_test.go [reviewed]
  • cachebackend_resources_integration_test.go [reviewed]
  • cachebackend_schema_trim_integration_test.go [reviewed]
  • cachebackend_t2degraded_test.go [reviewed]
  • contract_coverage_sweep_test.go [reviewed]
  • integration_test.go [reviewed]
• internal/webhook/pod/
  • doc.go [reviewed]
  • envtest_integration_test.go [reviewed]
  • podinjector.go [reviewed]
  • podinjector_test.go [reviewed]
• internal/webhook/v1alpha1/
  • cachebackend_defaulter_envtest_test.go [reviewed]
  • cachebackend_webhook.go [reviewed]
  • cachebackend_webhook_test.go [reviewed]
• pkg/adapters/runtime/
  • adapter.go [reviewed]
  • adapter_test.go [reviewed]
  • doc.go [reviewed]
  • external/doc.go [reviewed]
  • external/external.go [reviewed]
  • external/external_test.go [reviewed]
  • kernelcheck.go [reviewed]
  • kvevent_subscriber.go [reviewed]
  • provider_compat.go [reviewed]
  • reference.go [reviewed]
  • sglang/doc.go [reviewed]
  • vllm_lmcache_kernelcheck.go [reviewed]
  • vllm_mooncake.go [reviewed]
  • vllm_mooncake_test.go [reviewed]
  • wire_contract.go [reviewed]
• pkg/cli/doctor/checks/
  • cachebackend.go [reviewed]
  • checks_test.go [reviewed]
• site/content/en/docs/
  • concepts/architecture.md [reviewed]
  • concepts/cachebackend.md [reviewed]
  • developer-guide/_index.md [reviewed]
  • reference/crd-api.md [reviewed]
  • tasks/bind-an-engine.md [reviewed]
  • tasks/deploy-a-cache-backend.md [reviewed]

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:298 — spec.runtime changes from optional to required without conversion/defaulting. Existing valid v1alpha1 resources that relied on integration.engine can no longer be created or updated, violating the required CRD backward-compatibility rule.
• api/v1alpha1/cachebackend_types.go:21 — Closing spec.type to LMCache;SGLangHiCache removes previously served AIBrix, Mooncake, NIXL, and External values. Existing objects using these values become incompatible with the updated schema; the “not formally deployed” rationale does not preserve the stipulated v1alpha1 contract.
• api/v1alpha1/cachebackend_types.go:295 — The served spec drops the JSON fields backendConfig, top-level resources, and endpoint, while CacheBackendIntegrationSpec at line 469 drops engine. Updating an existing object will prune or reject its configuration and alter behavior without a conversion/migration path.

Should-fix

• pkg/adapters/runtime/wire_contract.go:54 — LMCache and Mooncake endpoint validation only checks that the port substring is non-empty, so values such as cache.example:not-a-port, cache.example:0, and cache.example:70000 are accepted. External storage can consequently be marked Ready and then inject an unusable connector URL; validate a numeric port in 1–65535, as the Redis branch already does.

Nit

None.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:21, api/v1alpha1/cachebackend_types.go:295, api/v1alpha1/cachebackend_types.go:298
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): findings above at: pkg/adapters/runtime/wire_contract.go:54

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

api/v1alpha1/

• [reviewed] cachebackend_effective.go, cachebackend_effective_test.go, cachebackend_types.go, cachebackend_types_test.go
• [skipped — generated] zz_generated.deepcopy.go

cmd/inferencecache/

• [reviewed] doctor_integration_test.go

config/crd/bases/

• [skipped — generated] inferencecache.io_cachebackends.yaml

config/samples/

• [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml, cache_v1alpha1_cachebackend.yaml, cachebackend-cpu-override.yaml

docs/cli/

• [reviewed] doctor.md

docs/concepts/

• [reviewed] cachebackend-engine-binding.md, cachebackend-engine-overrides.md

docs/design/

• [reviewed] cachebackend-api.md, grpc-tls.md, kvevent-subscriber-wiring.md, lmcache-server-persistence.md, repository-boundaries.md, sglang-lmcache-mp-mode.md

docs/observability/

• [reviewed] alerts.md

docs/reference-stack/

• [reviewed] README.md, VERSIONS.md
• [reviewed] manifests/sglang-lmcache/README.md, manifests/sglang-lmcache/deployment.yaml
• [reviewed] scripts/canary_c2_reconcile.sh, scripts/canary_c6_engine_wiring.sh, scripts/default_install_smoke.sh

hack/verify-samples/

• [reviewed] admission_test.go, main.go

internal/adapters/builtin/

• [reviewed] boundaries_test.go, registry.go, registry_test.go

internal/adapters/builtin/runtime/

• [reviewed] contract_aliases_test.go, doc.go, lmcachecheck.go, lmcachecheck_script_test.go, lmcachecheck_test.go, sglang_hicache.go, sglang_hicache_test.go, sglang_lmcache.go, sglang_lmcache_test.go, sglang_lmcache_wire.go, vllm_lmcache.go, vllm_lmcache_test.go, vllm_lmcache_wire.go, vllm_lmcache_wire_test.go

internal/adapters/builtin/storage/

• [reviewed] effective_config.go, lmcache_server.go, mooncake.go, redis.go, redis_test.go, registry.go, registry_test.go

internal/controller/

• [reviewed] cachebackend_autoscaling_test.go, cachebackend_controller.go, cachebackend_controller_test.go, cachebackend_engine_compat.go, cachebackend_events_only_integration_test.go, cachebackend_events_test.go, cachebackend_hostnetwork_test.go, cachebackend_kvevent_gate_test.go, cachebackend_matched_pods_test.go, cachebackend_mooncake_hostnetwork_integration_test.go, cachebackend_probe.go, cachebackend_probe_integration_test.go, cachebackend_probe_test.go, cachebackend_resources_integration_test.go, cachebackend_schema_trim_integration_test.go, cachebackend_t2degraded_test.go, contract_coverage_sweep_test.go, integration_test.go

internal/webhook/pod/

• [reviewed] doc.go, envtest_integration_test.go, podinjector.go, podinjector_test.go

internal/webhook/v1alpha1/

• [reviewed] cachebackend_defaulter_envtest_test.go, cachebackend_webhook.go, cachebackend_webhook_test.go

pkg/adapters/runtime/

• [reviewed] adapter.go, adapter_test.go, doc.go, kernelcheck.go, kvevent_subscriber.go, reference.go, wire_contract.go
• [reviewed — deleted] external/doc.go, external/external.go, external/external_test.go, provider_compat.go, sglang/doc.go, vllm_lmcache_kernelcheck.go, vllm_mooncake.go, vllm_mooncake_test.go

pkg/cli/doctor/checks/

• [reviewed] cachebackend.go, checks_test.go

site/content/en/docs/

• [reviewed] concepts/architecture.md, concepts/cachebackend.md, developer-guide/_index.md, reference/crd-api.md, tasks/bind-an-engine.md, tasks/deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:298 — spec.runtime changes from optional/defaulted to required in the existing v1alpha1 version. Existing objects and manifests that relied on the VLLM default can no longer be created or updated, violating the stated requirement that CRD changes remain backward-compatible.

• api/v1alpha1/cachebackend_types.go:21 — Closing spec.type to LMCache;SGLangHiCache removes previously served Mooncake, External, AIBrix, and NIXL values. This rejects existing v1alpha1 resources at schema validation without a new API version or conversion/migration path.

• api/v1alpha1/cachebackend_types.go:295 — The served v1alpha1 spec removes endpoint, backendConfig, top-level resources, integration.engine, and integration.firstEventTimeout. Unknown-field pruning or validation will discard/reject existing configuration, so these removals require retaining compatibility fields or introducing a new version with conversion.

• site/content/en/docs/reference/crd-api.md:20 — The documentation changes the project’s compatibility promise to permit breaking v1alpha1 changes. That directly contradicts this review’s contract requirement rather than resolving the breaking schema changes.

Should-fix

• docs/design/cachebackend-api.md:491 — The Mooncake discussion still links to #backendconfig-keys-managed-lmcache, but the corresponding legacy backendConfig section was removed. Update the link to the typed LMCache wire/configuration section.

Nit

None.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:21, api/v1alpha1/cachebackend_types.go:295, api/v1alpha1/cachebackend_types.go:298, site/content/en/docs/reference/crd-api.md:20, docs/design/cachebackend-api.md:491
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): Clean; git diff --check passed. Tests could not execute because the read-only environment prevented Go from creating its module cache.

Verdict

changes-requested

[github-actions]

Codex review

Files reviewed

• api/v1alpha1/
  • [reviewed] cachebackend_effective.go, cachebackend_effective_test.go, cachebackend_types.go, cachebackend_types_test.go
  • [skipped — generated] zz_generated.deepcopy.go
• cmd/inferencecache/
  • [reviewed] doctor_integration_test.go
• config/crd/bases/
  • [skipped — generated] inferencecache.io_cachebackends.yaml
• config/samples/
  • [reviewed] _test/cachebackend-invalid-scale-to-zero-no-min.yaml, cache_v1alpha1_cachebackend.yaml, cachebackend-cpu-override.yaml
• docs/cli/
  • [reviewed] doctor.md
• docs/concepts/
  • [reviewed] cachebackend-engine-binding.md, cachebackend-engine-overrides.md
• docs/design/
  • [reviewed] cachebackend-api.md, grpc-tls.md, kvevent-subscriber-wiring.md, lmcache-server-persistence.md, repository-boundaries.md, sglang-lmcache-mp-mode.md
• docs/observability/
  • [reviewed] alerts.md
• docs/reference-stack/
  • [reviewed] README.md, VERSIONS.md
• docs/reference-stack/manifests/sglang-lmcache/
  • [reviewed] README.md, deployment.yaml
• docs/reference-stack/scripts/
  • [reviewed] canary_c2_reconcile.sh, canary_c6_engine_wiring.sh, default_install_smoke.sh
• hack/verify-samples/
  • [reviewed] admission_test.go, main.go
• internal/adapters/builtin/
  • [reviewed] boundaries_test.go, registry.go, registry_test.go
• internal/adapters/builtin/runtime/
  • [reviewed] contract_aliases_test.go, doc.go, lmcachecheck.go, lmcachecheck_script_test.go, lmcachecheck_test.go, sglang_hicache.go, sglang_hicache_test.go, sglang_lmcache.go, sglang_lmcache_test.go, sglang_lmcache_wire.go, vllm_lmcache.go, vllm_lmcache_test.go, vllm_lmcache_wire.go, vllm_lmcache_wire_test.go
• internal/adapters/builtin/storage/
  • [reviewed] effective_config.go, lmcache_server.go, mooncake.go, redis.go, redis_test.go, registry.go, registry_test.go
• internal/controller/
  • [reviewed] cachebackend_autoscaling_test.go, cachebackend_controller.go, cachebackend_controller_test.go, cachebackend_engine_compat.go, cachebackend_events_only_integration_test.go, cachebackend_events_test.go, cachebackend_hostnetwork_test.go, cachebackend_kvevent_gate_test.go, cachebackend_matched_pods_test.go, cachebackend_mooncake_hostnetwork_integration_test.go, cachebackend_probe.go, cachebackend_probe_integration_test.go, cachebackend_probe_test.go, cachebackend_resources_integration_test.go, cachebackend_schema_trim_integration_test.go, cachebackend_t2degraded_test.go, contract_coverage_sweep_test.go, integration_test.go
• internal/webhook/pod/
  • [reviewed] doc.go, envtest_integration_test.go, podinjector.go, podinjector_test.go
• internal/webhook/v1alpha1/
  • [reviewed] cachebackend_defaulter_envtest_test.go, cachebackend_webhook.go, cachebackend_webhook_test.go
• pkg/adapters/runtime/
  • [reviewed] adapter.go, adapter_test.go, doc.go, kernelcheck.go, kvevent_subscriber.go, reference.go, wire_contract.go
  • [reviewed — deleted] provider_compat.go, vllm_lmcache_kernelcheck.go, vllm_mooncake.go, vllm_mooncake_test.go
• pkg/adapters/runtime/external/
  • [reviewed — deleted] doc.go, external.go, external_test.go
• pkg/adapters/runtime/sglang/
  • [reviewed — deleted] doc.go
• pkg/cli/doctor/checks/
  • [reviewed] cachebackend.go, checks_test.go
• site/content/en/docs/concepts/
  • [reviewed] architecture.md, cachebackend.md
• site/content/en/docs/developer-guide/
  • [reviewed] _index.md
• site/content/en/docs/reference/
  • [reviewed] crd-api.md
• site/content/en/docs/tasks/
  • [reviewed] bind-an-engine.md, deploy-a-cache-backend.md

Findings

Blocking

• api/v1alpha1/cachebackend_types.go:22 — Removing AIBrix, Mooncake, NIXL, and External from the served v1alpha1 type enum breaks existing objects and manifests. The review contract explicitly requires v1alpha1 compatibility; lack of formal deployment does not make an in-place served-version schema contraction compatible.
• api/v1alpha1/cachebackend_types.go:298 — Making spec.runtime required breaks every previously valid v1alpha1 manifest that relied on the documented vLLM default. Preserve the optional/defaulted representation or introduce a new API version with conversion.
• api/v1alpha1/cachebackend_types.go:295 — Removing spec.backendConfig, top-level spec.resources, spec.endpoint, spec.integration.engine, and spec.integration.firstEventTimeout is another breaking mutation of the same served version. Existing data will be rejected or pruned and the compatibility readers were simultaneously removed, so these fields require preservation or versioned conversion.

Should-fix

None.

Nit

None.

Per-category coverage

1. Vendor-neutral naming: Clean
2. Contract & spec / docs sync: findings above at: api/v1alpha1/cachebackend_types.go:22, api/v1alpha1/cachebackend_types.go:298, api/v1alpha1/cachebackend_types.go:295
3. gRPC fail-open semantics: Clean
4. Quality (tests / error wrapping / package placement / generated drift): Clean

Verdict

changes-requested

[fredericsun]

Maintainer disposition: compatibility findings

We acknowledge the blocking findings and are intentionally not addressing them in this PR.

Inference Cache has not had a formal production deployment, so there are no persisted production CacheBackend resources or supported production manifests that require migration. The removed fields, legacy type spellings, and implicit runtime default belong to an unshipped pre-deployment API shape. CAC-264 deliberately replaces that shape with an explicit spec.runtime and a typed cache/provider/ownership model.

Preserving the legacy fields and enum values, or adding a conversion webhook and another API version, would leave two competing contracts and introduce migration machinery for a contract with no deployed consumers. That would work against the repository-boundary and API-clarity goals of this refactor without protecting any real production workload.

The maintainers are therefore taking a narrow, one-time pre-deployment exception to the general v1alpha1 compatibility rule. This exception is documented in the CRD reference and docs/design/repository-boundaries.md. After the first formal production deployment, breaking CRD changes will require explicit API versioning and a migration or conversion path.

These findings should be treated as an acknowledged maintainer decision for this PR unless evidence identifies an actual deployed resource or supported external consumer that requires compatibility.