# Observation Event Transport (advisory.observation.updated@1)

Purpose: document how to emit `advisory.observation.updated@1` events via Mongo outbox with optional NATS JetStream transport.

## Configuration (appsettings.yaml / config)
```yaml
advisoryObservationEvents:
  enabled: false            # set true to publish beyond Mongo outbox
  transport: "mongo"        # "mongo" (no-op publisher) or "nats"
  natsUrl: "nats://127.0.0.1:4222"
  subject: "concelier.advisory.observation.updated.v1"
  deadLetterSubject: "concelier.advisory.observation.updated.dead.v1"
  stream: "CONCELIER_OBS"
```

Defaults: disabled, transport `mongo`; subject/stream as above.

## Flow
1) Observation sink writes event to `advisory_observation_events` (idempotent on `observationHash`).
2) Background worker dequeues unpublished rows, publishes via configured transport, then stamps `publishedAt`.
3) If transport disabled/unavailable, outbox accumulates safely; re-enabling resumes publishing.

## Operational notes
- Ensure NATS JetStream is reachable before enabling `transport: nats` to avoid retry noise.
- Stream is auto-created if missing with current subject; size capped at 512 KiB per message.
- Dead-letter subject reserved; not yet wired—keep for future schema validation failures.
- Backlog monitoring: count documents in `advisory_observation_events` with `publishedAt: null`.

## Testing
- Without NATS: leave `enabled=false`; app continues writing outbox only.
- With NATS: run a local `nats-server -js` and set `enabled=true transport=nats`. Verify published messages on subject via `nats sub concelier.advisory.observation.updated.v1`.

## 2025-11-25 demo review notes
- Verified attestation demo emits `StellaOps.Concelier.Advisory.Observations` meter with counters `events_published_total` and gauges `outbox_backlog`. Ensure these metrics are scraped with tenant labels.
- Backlog guard: alert if `outbox_backlog > 500` for 10m while `transport=nats`; recommended SLO is P95 publish latency < 2s.
- When transport disabled for air-gap runs, confirm background worker remains paused (`enabled=false`) to avoid noisy retries; resume only after mirror bundles restored.
- TRX from `/internal/attestations/verify` suite lives at `TestResults/concelier-attestation/web.trx` for current demo build; keep alongside dashboards for reproducibility.