up

docs/ARCHITECTURE_SCANNER.md

@@ -42,6 +42,35 @@ src/
 
 Analyzer assemblies and buildx generators are packaged as **restart-time plug-ins** under `plugins/scanner/**` with manifests; services must restart to activate new plug-ins.
 
+### 1.1 Queue backbone (Redis / NATS)
+
+`StellaOps.Scanner.Queue` exposes a transport-agnostic contract (`IScanQueue`/`IScanQueueLease`) used by the WebService producer and Worker consumers. Sprint 9 introduces two first-party transports:
+
+- **Redis Streams** (default). Uses consumer groups, deterministic idempotency keys (`scanner:jobs:idemp:*`), and supports lease claim (`XCLAIM`), renewal, exponential-backoff retries, and a `scanner:jobs:dead` stream for exhausted attempts.
+- **NATS JetStream**. Provisions the `SCANNER_JOBS` work-queue stream + durable consumer `scanner-workers`, publishes with `MsgId` for dedupe, applies backoff via `NAK` delays, and routes dead-lettered jobs to `SCANNER_JOBS_DEAD`.
+
+Metrics are emitted via `Meter` counters (`scanner_queue_enqueued_total`, `scanner_queue_retry_total`, `scanner_queue_deadletter_total`), and `ScannerQueueHealthCheck` pings the active backend (Redis `PING`, NATS `PING`). Configuration is bound from `scanner.queue`:
+
+```yaml
+scanner:
+  queue:
+    kind: redis # or nats
+    redis:
+      connectionString: "redis://queue:6379/0"
+      streamName: "scanner:jobs"
+    nats:
+      url: "nats://queue:4222"
+      stream: "SCANNER_JOBS"
+      subject: "scanner.jobs"
+      durableConsumer: "scanner-workers"
+      deadLetterSubject: "scanner.jobs.dead"
+    maxDeliveryAttempts: 5
+    retryInitialBackoff: 00:00:05
+    retryMaxBackoff: 00:02:00
+```
+
+The DI extension (`AddScannerQueue`) wires the selected transport, so future additions (e.g., RabbitMQ) only implement the same contract and register.
+
 **Runtime form‑factor:** two deployables
 
 * **Scanner.WebService** (stateless REST)