[Step 6] Redis runtime (locks, cache, idempotency, rate limit) (pkg/runtime)

[haydercyber]

Goal — REFACTOR_PLAN.md Step 6

Add the Redis runtime layer in api/pkg/runtime. Redis is for Control Plane runtime coordination only (per BRD §10.1, FR-15) — rate limits, short-lived cache, distributed locks, job coordination, agent heartbeat cache. No secret values, ever. Agents do not connect to Redis.

Scope

• go-redis/v9 client, configured from env (URL, pool size, TLS)
• Idempotency helper: WithIdempotencyKey(ctx, key, fn) — single-execution guarantee per (key, TTL)
• Distributed lock helper (SETNX + lease + renewal): used by worker to serialize job execution
• Per-API-key + per-tenant rate limiter (sliding window)
• Pub/Sub primitives for worker-side notifications
• Wire /readyz to fail-open when Redis is unreachable for read-only operations, fail-closed when writes are required

Acceptance criteria

• Integration tests against a real Redis (testcontainers or CI service container)
• A simulated double-submit of the same idempotency key returns the cached first result, not two executions
• Two concurrent workers contending for the same lock → exactly one acquires it; the loser gets a typed ErrLockHeld
• Code review checklist explicitly verifies that no SetValue(secretValue.Bytes ...) shows up in the runtime layer
• Agent has no pkg/runtime import — enforced by a CI lint that fails if agent/... ever imports api/pkg/runtime

Hard rules (CLAUDE.md / BRD)

• Redis is private to the Control Plane (BRD §10.1, §15 Runtime dependency exposure, §24)
• No secret values in Redis values, keys, or pub/sub payloads (BRD §11, FR-04)

References

• BRD §9 (Control Plane Runtime row), §10.1, §13 FR-15, §15, §24
• REFACTOR_PLAN §6 row 6

Dependencies

• api scaffold (Step 4)
• Postgres storage (Step 5)