feature: split operator config contract across schema, validation, and canonical translation

[Xunzhuo]

Describe the feature

Create a dedicated cleanup workstream for the Kubernetes operator config contract so schema declaration, webhook validation, controller-side canonical translation, and sample-fixture coverage stop collapsing into the same broad change surface.

Primary files and seams:

• deploy/operator/api/v1alpha1/semanticrouter_types.go
• deploy/operator/api/v1alpha1/semanticrouter_webhook.go
• deploy/operator/api/v1alpha1/sample_validation_test.go
• deploy/operator/api/v1alpha1/semanticrouter_webhook_test.go
• deploy/operator/controllers/canonical_config_builder.go
• deploy/operator/config/samples/**

Primary layer

global level

Why this layer?

This is a contract-boundary cleanup across multiple operator ownership layers rather than a single feature limited to one signal or plugin surface.

Why do you need this feature?

The current repo audit confirmed that operator config evolution still requires too many synchronized edits across different seams:

• CRD schema in semanticrouter_types.go
• semantic validation in semanticrouter_webhook.go
• canonical v0.3 translation in canonical_config_builder.go
• sample/webhook regression fixtures under the operator API tree

The local rules already acknowledge these hotspots:

• deploy/operator/api/v1alpha1/AGENTS.md
• deploy/operator/controllers/AGENTS.md

And the debt is tracked in docs/agent/tech-debt/td-028-operator-config-contract-boundary-collapse.md with execution planning in docs/agent/plans/pl-0009-fleet-sim-optimizer-and-operator-config-boundary-ratchet.md, but there is currently no dedicated GitHub issue for external contributors.

Additional context

Suggested acceptance criteria:

• new operator config features no longer require parallel edits across schema, webhook validation, and canonical translation unless the change is intentionally cross-cutting
• schema families and validation helpers are factored into narrower modules instead of widening semanticrouter_types.go / semanticrouter_webhook.go
• canonical_config_builder.go delegates family-specific translation into adjacent helpers
• operator sample-fixture updates follow those narrower seams instead of one large builder/schema hotspot
• validation includes the operator harness path (make generate-crd and the relevant agent gates for touched files)

This is a strong help wanted candidate, but not a good first issue: contributors need to understand CRD schema, admission validation, controller translation, and sample-fixture coupling before changing it.