From 370b5a894ff5b7175bbb5924a696951c130dbc85 Mon Sep 17 00:00:00 2001
From: Story Crater Bot <19826264+Riotpiaole@users.noreply.github.com>
Date: Mon, 17 Aug 2026 12:17:39 -0700
Subject: [PATCH] (chore) add worker queue

---
 CLAUDE.md                          | 12 ++++++++++++
 k8s/queues/agent-worker-queue.yaml | 14 ++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 k8s/queues/agent-worker-queue.yaml

diff --git a/CLAUDE.md b/CLAUDE.md
index f748448..60d7587 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,3 +33,15 @@ Client Service Pod N ----/                    ↓
 - Horizontal scaling: add more `kmsvc` service replicas—Kafka rebalances automatically
 - HA: Redis Sentinel/Cluster recommended for production (design.md §9) — currently standalone
 - Monitoring: Kafka consumer-group lag, Redis pending/inflight keys, visibility timeouts
+
+## Temporal Namespace Registration — Always Automatic, Never Manual
+
+**Never manually run `temporal operator namespace create` (or the CLI/UI equivalent) for a namespace that a Queue's `temporal.io/namespace` label will reference.** `queue-operator`'s `reconcileTemporalWorker` (`internal/operator/queue_controller.go`) registers the Temporal namespace itself — idempotently, via `TemporalNamespaceRegisterer.RegisterNamespace` (`internal/operator/temporal_namespace.go`, real impl in `internal/temporal/client.go`) — before creating the `TemporalWorker` CR. This runs on every reconcile of every Queue carrying that label, so the namespace and its worker always exist together.
+
+**The only steps to bring up a new Temporal namespace + worker are:**
+1. Apply a `Queue` CR with `metadata.labels["temporal.io/namespace"] = "<namespace>"`.
+2. That's it. `queue-operator` registers the namespace, creates `TemporalWorker/worker-<namespace>` in the `temporal` namespace, and its backing Deployment.
+
+**Why this matters:** before this existed, a Queue's `temporal.io/namespace` label was trusted as-is with no verification — a typo'd or never-registered namespace silently produced a worker pod polling a namespace that doesn't exist, with no error surfaced anywhere until someone noticed workflows never executing. Manually pre-creating the namespace masks this — don't do it, let the operator own it.
+
+One `TemporalWorker` per Temporal namespace serves *all* Queues labeled with that namespace (not one worker per Queue) — see the type doc on `TemporalWorkerSpec` in `apis/kmsvc/v1/temporalworker_types.go`.
diff --git a/k8s/queues/agent-worker-queue.yaml b/k8s/queues/agent-worker-queue.yaml
new file mode 100644
index 0000000..f33ceef
--- /dev/null
+++ b/k8s/queues/agent-worker-queue.yaml
@@ -0,0 +1,14 @@
+apiVersion: kmsvc.io/v1
+kind: Queue
+metadata:
+  name: agent-worker-queue
+  namespace: sqs
+  labels:
+    temporal.io/namespace: production
+spec:
+  visibilityTimeoutSeconds: 30
+  messageRetentionPeriodSeconds: 345600
+  maxReceiveCount: 5
+  partitionsPerShard: 1
+  minShards: 1
+  maxShards: 1