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

Audience: Concelier operators wiring advisory-observation events into downstream consumers.

Concelier publishes advisory.observation.updated@1 events through a PostgreSQL outbox, with an optional NATS JetStream transport for fan-out beyond the database. This guide covers configuration, the publish flow, and the operational signals to watch.

Configuration (`appsettings.yaml`)

advisoryObservationEvents:
  enabled: false            # set true to publish beyond PostgreSQL outbox
  transport: "postgres"     # "postgres" (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: publishing disabled, transport postgres; the subject and stream are as shown above.

Publish flow

The observation sink writes the event to the advisory_observation_events table (idempotent on observationHash).
A background worker dequeues unpublished rows, publishes them via the configured transport, then stamps publishedAt.
If the transport is disabled or unavailable, the outbox accumulates safely; re-enabling resumes publishing from where it left off.

Operational notes

Ensure NATS JetStream is reachable before enabling transport: nats to avoid retry noise.
The stream is auto-created if missing using the configured subject; message size is capped at 512 KiB.
The dead-letter subject is reserved but not yet wired — keep it for future schema-validation failures.
Backlog monitoring: count rows in advisory_observation_events where published_at IS NULL.

Testing

Without NATS: leave enabled: false; the service continues writing to the outbox only.
With NATS: run a local nats-server -js, then set enabled: true and transport: nats. Verify published messages on the subject:
```
nats sub concelier.advisory.observation.updated.v1
```

Demo review notes (2025-11-25)

The attestation demo emits the StellaOps.Concelier.Advisory.Observations meter, with an events_published_total counter and an outbox_backlog gauge. Ensure these metrics are scraped with tenant labels.
Backlog guard: alert when outbox_backlog > 500 for 10 minutes while transport: nats. The recommended SLO is P95 publish latency under 2 s.
For air-gapped runs the transport is disabled; confirm the background worker stays paused (enabled: false) to avoid noisy retries, and resume only after mirror bundles are restored.
The TRX from the /internal/attestations/verify suite for the current demo build lives at TestResults/concelier-attestation/web.trx; keep it alongside the dashboards for reproducibility.