Correlation begins at the government API edge

What the public implementation shows

CorrelationIdMiddleware accepts X-Correlation-Id or generates one, echoes it on responses, and bill creation stores it on BillCreated events.

The context is established before endpoint execution and flows into both technical logging and business event evidence. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleThe first API boundary should establish the context every later record can carry.

The decision behind the mechanism

One entry-point mechanism avoids each authority or module inventing a different trace convention.

If correlation begins after bill persistence, the authority log and gateway event can no longer be joined deterministically. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Validate inbound correlation values before logging.
• Generate one when the caller omits it.
• Echo it on every response.
• Persist it with key business events.

How the control should be operated

The identifier format, maximum size, trust treatment, propagation headers, and logging scope should be consistent across clients and callbacks.

A revenue authority can follow one request through response, event polling, and later notification. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.