Unify the Tenant CRD with enterprise-api -provision-tenant (lightweight)

Closes a gap named across CLAUDE.md/docs/architecture.md/deploy/README.md
since early Phase 4: the operator's Tenant CRD and -provision-tenant
were two disconnected mechanisms. The operator's reconciler generated a
K8s Secret with a locally-generated random password that authenticated
against nothing (nothing ever called ClickHouse to create a matching
user), and unconditionally claimed status.phase=Active the moment a
Tenant object existed -- actively misleading, not just incomplete.

Two unification shapes were considered (surfaced to the user via
AskUserQuestion, given the real difference in blast radius): the
operator's reconcile loop becoming a second real actor (new Postgres +
ClickHouse admin credentials flowing into the K8s controller, plus real
reconcile-loop idempotency/retry design for an inherently one-shot
external side effect), or keeping -provision-tenant as the sole real
actor and having it also sync its result into the CRD. Went with the
lighter option.

enterprise/internal/tenantcrd (new): a Syncer using the K8s dynamic
client (unstructured.Unstructured + a GroupVersionResource, not
deploy/operator's typed Tenant struct -- avoids a cross-module Go
dependency between two independently-versioned modules for one type).
Upserts the Tenant object, creates/updates a Secret with the *real*
ClickHouse credentials owned by that Tenant via an OwnerReference, then
patches status.{clickHouseDatabaseName,clickHouseSecretRef,
tantivyIndexPath}. Idempotent and safe to retry: never rotates a
credential across a re-sync, never overwrites a pre-existing
spec.displayName a human/GitOps process set.

cmd/enterprise-api/main.go's runProvisionTenant calls Sync when
TENANT_CRD_NAMESPACE is set (empty = no-op, same shape as every other
optional dependency in this codebase). Its "already active" refusal is
now split: ClickHouse re-provisioning is still refused (rotating a live
credential would break every open connection for no benefit), but CR
sync alone is now retryable using the credentials already on file in
rbacstore -- needed for retrying a previously-failed sync, or
backfilling CR sync for a tenant provisioned before this existed.

deploy/operator's reconciler rewritten to match: it never claims
PhaseActive on its own initiative anymore, only once
status.ClickHouseDatabaseName is non-empty (the field -provision-tenant,
and only -provision-tenant, sets). Phase is now a pure function of
{spec.suspended, status.ClickHouseDatabaseName != ""} recomputed every
reconcile, not toggled in place -- fixes a related bug the old code
would have hit once suspension was involved: un-suspending an
already-provisioned tenant needs to return straight to Active, which
isn't derivable from "last observed phase was Suspended" alone. The
reconciler no longer creates or manages any Secret, dropped its
`secrets` RBAC grant entirely, and gained zero new dependencies.

Helm chart: enterprise-api gets its own ServiceAccount/Role/RoleBinding
(get/list/create tenants, get/update/patch tenants/status, get/create/
update secrets -- least-privilege, scoped to the release namespace, not
a ClusterRole) and a TENANT_CRD_NAMESPACE env var, both gated on
tenantOperator.enabled. tenant-operator's ClusterRole loses the
secrets grant it no longer needs.

Verified in this environment: enterprise/internal/tenantcrd's tests run
against k8s.io/client-go's fake dynamic + typed clientsets (real client
library, fake transport, no cluster needed); deploy/operator's rewritten
tenant_controller_test.go runs against controller-runtime's fake
client, including new regression tests for the "must not claim Active
without confirmation" and "un-suspending returns to Active, not
Provisioning" properties; helm template + parsing the rendered YAML
confirms the RBAC split renders exactly as designed under both
tenantOperator.enabled=true/false. Not verified: an actual
-provision-tenant run against a real cluster with the operator watching
(no live cluster in this environment, same disclosed limitation as the
rest of /deploy). Docs updated in lockstep: CLAUDE.md, docs/architecture.md,
deploy/README.md, deploy/helm/sentry/README.md (including a corrected
"Trying the two-tenant example" walkthrough), phase-4-runbook.md (new
§11), enterprise/README.md. Also fixed two unrelated stale claims found
along the way: docs/architecture.md still said docker-compose.yml ran
plain api unconditionally (fixed in an earlier commit, doc not updated
then), and enterprise-api's own main.go doc comment still said Helm/
docker-compose wiring wasn't built yet.

deploy/operator/api/v1alpha1/tenant_types.go

@@ -8,15 +8,20 @@ import (
 // /docs/phase-4-isolation-design.md: every tenant-resolution path
 // elsewhere must refuse to serve a tenant not in PhaseActive, checked
 // server-side (today, against enterprise/internal/rbacstore's tenants
-// table -- this CR is a K8s-native *view* of the same state machine at
-// the deployment-topology layer, not a second source of truth. Reconciling
-// the two together is exactly the kind of tenant-provisioning wiring
-// named as deferred in /docs/phase-4-runbook.md's task 6 section: today
-// this operator only manages the K8s-side artifact (a per-tenant
-// ClickHouse credential Secret + a ConfigMap recording the tenant's
-// database name/index path), not the actual `CREATE DATABASE`/`CREATE
-// USER`/`GRANT` calls against ClickHouse -- that's
-// enterprise/internal/tenantprovision, still unbuilt.
+// table -- this CR is a K8s-native *view* of that same state machine,
+// kept honest rather than a second, independently-guessed source of
+// truth. `enterprise-api -provision-tenant` (the actual actor -- real
+// `CREATE DATABASE`/`CREATE USER`/`GRANT` calls against ClickHouse, and
+// the real rbacstore writes) is the only writer of
+// TenantStatus.ClickHouseDatabaseName/ClickHouseSecretRef/
+// TantivyIndexPath, once real provisioning succeeds -- see
+// internal/controller/tenant_controller.go's doc comment for how
+// TenantReconciler derives Phase/Conditions from those fields rather
+// than fabricating its own "provisioned" claim. This is the "lightweight
+// unification" named in CLAUDE.md/docs/phase-4-runbook.md's "two
+// independent provisioning mechanisms" gap: -provision-tenant stays the
+// real actor; this operator's reconcile loop never touches Postgres or
+// ClickHouse and gained no new credentials.
 type TenantPhase string
 
 const (
@@ -47,23 +52,43 @@ type TenantSpec struct {
 	Suspended bool `json:"suspended,omitempty"`
 }
 
-// TenantStatus is observed state -- only the controller writes this.
+// TenantStatus is observed state, with split ownership as of the
+// "lightweight unification" (see TenantPhase's doc comment):
+// ClickHouseDatabaseName/ClickHouseSecretRef/TantivyIndexPath are
+// written only by enterprise-api's -provision-tenant, once real
+// ClickHouse provisioning actually succeeds -- this controller only
+// reads them (to compute Phase/Conditions) and never invents a value
+// for them. Phase/Conditions/ObservedGeneration remain
+// controller-written, computed fresh on every reconcile from Spec plus
+// whatever -provision-tenant has (or hasn't) reported.
 type TenantStatus struct {
 	// +optional
 	Phase TenantPhase `json:"phase,omitempty"`
 
-	// ClickHouseDatabaseName is derived (today: same as the Tenant's own
-	// Name) rather than settable in Spec -- see task 2's design: no
-	// tenant traffic authenticates as ClickHouse's `default` user, and a
+	// ClickHouseDatabaseName is set by enterprise-api -provision-tenant
+	// once ClickHouse provisioning for this tenant actually succeeds --
+	// empty means "not yet provisioned," which TenantReconciler reads as
+	// PhaseProvisioning (see tenant_controller.go). Today it's always
+	// equal to the Tenant's own Name (see task 2's design: no tenant
+	// traffic authenticates as ClickHouse's `default` user, and a
 	// database name that could diverge from the tenant identifier is a
-	// bookkeeping foot-gun this type avoids by construction.
+	// bookkeeping foot-gun this type avoids by construction) but isn't
+	// itself computed by this package -- -provision-tenant sets it
+	// directly from what it actually created.
 	// +optional
 	ClickHouseDatabaseName string `json:"clickHouseDatabaseName,omitempty"`
 
 	// ClickHouseSecretRef names the Secret (same namespace) holding this
-	// tenant's dedicated, narrowly-granted ClickHouse credentials -- see
-	// tenant_controller.go's reconcileSecret. Never the cluster-wide
-	// CLICKHOUSE_PASSWORD docker-compose.yml uses today.
+	// tenant's dedicated, narrowly-granted ClickHouse credentials --
+	// created by enterprise-api -provision-tenant (enterprise/internal/
+	// tenantcrd), owned by this Tenant object via an OwnerReference so
+	// K8s garbage-collects it on Tenant deletion regardless of which
+	// process created it. This controller no longer creates or manages
+	// any Secret itself -- see tenant_controller.go's doc comment for
+	// why a controller-generated placeholder credential (the pre-
+	// unification behavior) was actively misleading, not just
+	// incomplete. Never the cluster-wide CLICKHOUSE_PASSWORD
+	// docker-compose.yml uses today.
 	// +optional
 	ClickHouseSecretRef string `json:"clickHouseSecretRef,omitempty"`