feat(write-stream): WALM-116 relayer write-stream redesign

.gitignore

@@ -125,6 +125,9 @@ railway-*.md
 # Personal/internal planning notes — never include in repo
 plans/
 .local-plans/
+# But allow Superpowers plans/specs that are part of the design record.
+!docs/superpowers/plans/
+!docs/superpowers/specs/
 
 # Benchmark archives + working analysis notes
 # Kept locally under
@@ -137,3 +140,6 @@ claudedocs/
 
 # Temp File
 temp/
+
+# Superpowers brainstorming session files
+.superpowers/

docs/relayer/observability.md

@@ -66,6 +66,11 @@ Core relayer metrics:
 | `memwal_sidecar_failures_total` | `operation`, `reason` | Sidecar transport and HTTP failures |
 | `memwal_db_query_duration_seconds` | `operation`, `status` | PostgreSQL and pgvector query latency |
 | `memwal_db_pool_connections` | `state` | PostgreSQL pool `open` and `idle` gauges |
+| `memwal_write_stream_permits_total` | none | Configured permit ceiling |
+| `memwal_write_stream_permits_available` | none | Permits currently free |
+| `memwal_write_stream_waiters_total` | none | Tasks waiting for a permit |
+| `memwal_write_stream_acquired_total` | `result` | Permit acquisition outcomes |
+| `memwal_write_stream_rejected_total` | `route` | Requests rejected with `429` |
 
 Example Prometheus scrape config:
 

docs/relayer/self-hosting.md

@@ -98,6 +98,15 @@ By default, the relayer enforces rate limits and storage quotas via Redis to pre
 - `RATE_LIMIT_STORAGE_BYTES` — max storage per user in bytes (default: 1 GB, `1073741824`)
 - `REDIS_URL` — required to track sliding windows for rate limits (default: `redis://localhost:6379`)
 
+### Write-stream concurrency
+
+| Variable | Default | Description |
+|---|---|---|
+| `WRITE_STREAM_MAX_CONCURRENCY` | `8` | Maximum concurrent active write operations (prep + upload) |
+| `WRITE_STREAM_ACQUIRE_TIMEOUT_MS` | `5000` | Handler wait for a write slot before returning `429` |
+
+Tune `WRITE_STREAM_MAX_CONCURRENCY` down to reduce sidecar pressure, or up to increase throughput when the sidecar has headroom. Keep it below `WALRUS_UPLOAD_MAX_CONCURRENCY` so the sidecar safety net remains meaningful.
+
 ### Defaults
 
 - `PORT` defaults to `8000`