# Learnings: NATS Port Dynamic Allocation Fix

## Problem
- Hardcoded `NATS_PORT = 4222` caused test failures when port 4222 was occupied by system services
- F4 flagged this as scope-fidelity drift

## Solution
- Added `_find_open_port()` helper using `socket.socket().bind(("127.0.0.1", 0))` to find available port
- Updated `nats_server` fixture to yield `(bool, int)` tuple instead of just bool
- Updated `_start_nats_container(port: int)` to accept dynamic port parameter
- Wired dynamic port through all test methods using `nats_url = f"nats://127.0.0.1:{port}"`

## Key Implementation Details
1. Port discovery happens in fixture before container start
2. Same port used for Docker `-p {port}:{port}` mapping and NATS URL
3. Fixture returns `(False, 0)` when Docker/server unavailable to preserve skip behavior
4. Cleanup via `_stop_nats_container()` preserved in `finally` block

## Verification Results
- `pytest tests/demo/test_nats.py -q`: 9 passed, 2 skipped (Docker unavailable in CI)
- `basedpyright tests/demo/test_nats.py`: 0 errors, 1 warning (reportAny on socket.getsockname)

## Files Modified
- `tests/demo/test_nats.py` only (as required)