Minimal trace bridge: mint + forward traceparent [Story-1141]

Story 1141Epic None8 files · +951/−0

PR #212 · pramaan-io/pramaan-admin · merged 2026-06-10

Why this matters

When the pager rings at 2am, can you trace one user request end to end?

Why a missing traceparent bridge costs you hours of grep, not minutes of answer.

No validation at the proxy = the trace dies before Lambda ever sees it.

The fix — Validate the inbound, mint if missing, forward every hop — one request, one trace, end to end.

How it flows

sequenceDiagram
  autonumber
  participant fe as Frontend
  participant px as Proxy
  participant gw as Gateway
  participant lb as Lambda
  participant cfg as Config
  fe->>px: request (maybe traceparent)
  px->>px: validate or mint
  px->>gw: forward + traceparent
  gw->>lb: outbound + traceparent
  lb->>lb: join X-Ray trace
  cfg-->>px: kill switch ON
  px->>px: strip + skip mint

Files changed (8)

File±
AGENTS.md+18
docs/walkthroughs/story-1141-walkthrough.html+210
src/lib/gateway.ts ★+45
src/lib/trace-context.ts ★+127
src/proxy.ts ★+23
tests/unit/lib/gateway-trace.test.ts+243
tests/unit/lib/trace-context.test.ts+165
tests/unit/proxy.test.ts+120