docs: plan isolated Redis follow capacity

[samuv]

Summary

• Defines the accepted behavior and exact interfaces for an isolated, bounded Redis follow pool.
• Proposes ADR 0328 for atomic durability/follow client generations, fail-fast follower admission, and store-owned shutdown.
• Records the watch_capacity Go/server/TypeScript contract, mecak8s CLI and Helm defaults, and the narrow ADR 0240 supersession needed to force-close follow clients safely.

Development stage

• Plan / Interface — Bounded/Architectural behavioral and exact-interface contract; no implementation
• Implementation — based on an approved, merged Plan / Interface PR
• Combined — compact one-task Bounded/Architectural exception; no separate plan PR,
  and the in-PR plan declares **Expected tasks:** 1, a non-placeholder
  **Combined rationale:**, and no runtime/public/operator/persistence/trust-boundary
  interface change (None — rationale; workflow-only meta-changes may review process
  docs/skills here)
• Spike / Routine — acceptance-plan spine exempt; Spike evidence does not ship as-is

Contract linkage

• Work classification: Architectural
• Classification rationale: Changes exported Go and TypeScript error contracts, operator CLI/Helm configuration, and ownership of process-lifetime Redis clients and follower goroutines.
• Decision record: ADR 0328
• Human waiver of spine: No
• Acceptance plan: Redis follow capacity
• Human decisions resolved and recorded: Yes
• Plan / Interface PR: This PR
• Approved commit baseline: N/A until this PR merges
• Combined/exemption rationale: N/A — Split delivery

Interface conformance

• No protobuf schema change.
• Additive port.ErrEventFollowCapacity and stable watch_capacity mapping; gRPC uses RESOURCE_EXHAUSTED, while the HTTP watch retains 200 and emits a terminal SSE error frame.
• TypeScript WatchConnection resumes watch_capacity from its last processed cursor; MECATL_ERROR_CODES adds the stable code without a new error class.
• mecak8s adds --redis-follow-pool-size and --redis-max-followers, both default 32; Helm adds redis.follow.poolSize and redis.follow.maxFollowers with the same defaults.
• Effective configuration must satisfy 1 ≤ maxFollowers ≤ poolSize.

Issue relationship

Relates to #876

Type of change

• Behavioral/interface plan
• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation/process
• Other (describe):

Test plan

Baseline checks

• Acceptance-plan checker
• Linting (task lint)
• Offline test suite (task test)
• Offline demo (go run ./cmd/mecademo)
• Markdown changed: docs generation/link checks (task docs)
• User docs/user-facing behavior changed: site build (task site:build)
• Guarded engine API affected: compatibility check (task api:check)
• Intentional engine API change: task api:update + engine/CHANGELOG.md
• Landed plan: strict acceptance trace (task ac-trace-strict)
• Final implementation review: /panel-review

Plan-only checks completed:

• bash .claude/skills/to-acceptance-plan/scripts/check-acceptance-plan.sh docs/acceptance/redis-follow-capacity.md
• bash .claude/skills/to-acceptance-plan/scripts/check-acceptance-plan-test.sh
• task docs
• advisory devils-advocate pass, with all six correctness findings folded into the contract

Runtime, API-update, site, and panel gates belong to the implementation PR.

Changes

File	Change
docs/acceptance/redis-follow-capacity.md	Records four scenarios, nineteen acceptance criteria, exact interfaces, and exclusions.
docs/adr/0328-isolated-redis-follow-capacity.md	Proposes the durable client, admission, lifecycle, and operator-bound decisions.
docs/acceptance/README.md, docs/adr/README.md	Index the proposed plan and ADR.

User-facing change

None yet. This PR defines the reviewed contract; implementation follows only after merge.

Special notes for reviewers

Please focus on the two separate bounds (poolSize versus maxFollowers), per-cycle credential-generation leasing, the admission/Close race, TypeScript reconnect behavior, and ADR 0328's narrow supersession of ADR 0240 for isolated follow clients only.

The implementation will use the released github.com/stacklok/toolhive-core v0.0.46 redisconn API.