Centralized trace-header bridge: mint + forward traceparent [Story-1140]

Story 1140Epic None16 files · +1505/−161

PR #283 · pramaan-io/pramaan-app · merged 2026-06-10

Why this matters

One request, ten gateways — and X-Ray shows... nothing.

Why story 1140 had to centralise the trace stamp.

One forgotten header = the whole journey goes dark.

The fix — One source, one stamp, every hop — or the trace goes dark.

How it flows

sequenceDiagram
  autonumber
  participant browser as Browser
  participant proxy as proxy.ts
  participant helper as outbound-headers
  participant backend as Backend (Lambda)
  participant control as Env / kill switch
  browser->>proxy: request enters at the edge
  proxy->>proxy: valid inbound traceparent? respect it
  proxy->>proxy: else: mint + sample (default 0.1)
  proxy->>helper: stamp traceparent + correlation id
  helper->>backend: every gateway / bridge reuses the stamp
  control->>control: PRAMAAN_OTEL_DISABLED=1 → mint/forward off, correlation stays

Files changed (16)

File	±
`AGENTS.md`	+19
`docs/obs/log-shape.schema.json`	+10
`docs/walkthroughs/story-1140-walkthrough.html`	+402
`scripts/debug/README.md`	+6
`src/lib/bridge.ts`	+5 −55
`src/lib/gateway.ts`	+27 −59
`src/lib/outbound-headers.ts` ★	+116
`src/lib/proxy-observability.ts`	+9
`src/lib/public-bridge.ts`	+4 −46
`src/lib/trace.ts` ★	+113
`src/proxy.ts` ★	+29 −1
`tests/unit/lib/outbound-headers.test.ts`	+188
`tests/unit/lib/proxy-observability.test.ts`	+6
`tests/unit/lib/trace-propagation-paths.test.ts`	+254
`tests/unit/lib/trace.test.ts`	+172
`tests/unit/proxy-trace.test.ts`	+145