Initial commit

docs/library-decisions/2026-05-14-@opentelemetry/api-logs.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/api-logs"
+version: "^0.55.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/api-logs license
+  - npm view @opentelemetry/api-logs version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/api-logs license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/api-logs` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community under the CNCF as part of the unified OTel JS repository. Versioned alongside the SDK packages; the 0.55.x line is current and aligns with the SDK release cycle.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §4 designates `@opentelemetry/api-logs` as the Logs API for `OtelLogger` in `core-shared/instrumentation/`. Feature packages interact with logging only via the `ILogger` interface (ADR-014 R34); they do not import this package directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/api-logs` is the only OTel Logs API in the workspace. It complements `@opentelemetry/api` (traces) and `@opentelemetry/sdk-metrics` (metrics) to form the complete three-signal OTel pipeline. No competing logging API is present.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/api-logs` is a pure API package with no network communication or data transmission. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/api-logs` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/otel-logger.ts` implements `ILogger` using `@opentelemetry/api-logs` to emit log records via the OTel Logs API (ADR-017 §4). `packages/core-audit` also depends on it for structured audit log emission.
+
+## Prompt: replaces
+
+`OtelLogger` replaces the former `SentryLogger` which called Sentry SDK methods directly. `@opentelemetry/api-logs` provides the vendor-neutral log emission surface so that the downstream exporter (Sentry via `@sentry/opentelemetry`) can be swapped without touching logger code.
+
+## Prompt: migration-cost-out
+
+Hard. `@opentelemetry/api-logs` is called in every `OtelLogger` log-emission path in `core-shared`. Moving to a different logs API (e.g., a custom abstraction) would require rewriting both the logger implementation and the OTel SDK initialization. The `ILogger` interface boundary (ADR-014) limits blast radius to `core-shared`.
+
+## Prompt: alternatives-considered
+
+1. **Winston / Pino as the log API** — Considered before ADR-017. Rejected because a separate log library alongside OTel would create a split-pipeline problem: traces and logs would travel through different channels, losing correlation.
+2. **Sentry SDK breadcrumb API directly** — Rejected in ADR-017: direct Sentry coupling prevents vendor swap without code changes.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/api.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/api"
+version: "^1.9.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/api license
+  - npm view @opentelemetry/api version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/api license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/api` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community under the CNCF. The 1.x stable API line receives regular releases; the project is a CNCF incubating project with broad industry backing.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 explicitly permits `@opentelemetry/api` for use within `core-shared/instrumentation/` without restriction. Feature packages use it via the `ITracer`/`ILogger` interfaces only; they do not import this package directly (ESLint boundary rules, ADR-010).
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/api` is the CNCF-standard instrumentation API. No competing tracing API is present in the workspace. The API package is the stable, zero-dependency interface layer intentionally kept separate from SDK implementations.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/api` is a pure instrumentation API with no network communication, telemetry transmission, or data storage. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/api` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/` consumes `@opentelemetry/api` to implement `OtelTracer` and `OtelLogger` (ADR-017). `packages/core-audit` also depends on it for span context propagation in audit records.
+
+## Prompt: replaces
+
+Prior to ADR-017, `core-shared` used Sentry SDK methods directly in `SentryTracer` and `SentryLogger`. `@opentelemetry/api` replaces direct Sentry SDK calls as the instrumentation substrate, allowing vendor swaps via exporter configuration rather than code rewrites.
+
+## Prompt: migration-cost-out
+
+Hard. `@opentelemetry/api` is the instrumentation interface called throughout `core-shared/instrumentation/`. Migrating away means replacing all span creation, context propagation, and log emission with a different API. The interfaces (`ITracer`, `ILogger`, `IMetrics`) in ADR-014 isolate feature packages, but the core instrumentation layer itself is deeply coupled to the OTel API shape.
+
+## Prompt: alternatives-considered
+
+1. **Sentry SDK directly** — Rejected in ADR-017: couples the impl to Sentry forever; vendor swap requires rewriting every `*Tracer`/`*Logger` pair.
+2. **OpenCensus** — CNCF predecessor to OpenTelemetry; reached end-of-life and merged into OpenTelemetry. Not viable.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/context-async-hooks.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/context-async-hooks"
+version: "^1.28.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/context-async-hooks license
+  - npm view @opentelemetry/context-async-hooks version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/context-async-hooks license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/context-async-hooks` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. Versioned with the OTel JS SDK at 1.x; the package tracks Node.js async_hooks API stability and receives updates alongside the SDK.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 mandates OTel as the instrumentation substrate. `@opentelemetry/context-async-hooks` provides the Node.js `AsyncLocalStorage`-based context manager required for automatic span propagation across async boundaries. It lives exclusively in `core-shared/instrumentation/otel/` and `core-audit` init paths.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/context-async-hooks` is the standard OTel context manager for Node.js. No competing context propagation mechanism is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/context-async-hooks` is a pure context propagation adapter with no network communication or data transmission. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/context-async-hooks` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/` registers `AsyncLocalStorageContextManager` from this package during OTel SDK init to enable automatic trace context propagation across Node.js async operations. `packages/core-audit` depends on it for span context in audit records.
+
+## Prompt: replaces
+
+Replaces the manual context threading that would otherwise be required to pass span context through async call chains. Without this package, every async function would need to explicitly forward a context argument — defeating the automatic propagation guarantee of OTel.
+
+## Prompt: migration-cost-out
+
+Low. `@opentelemetry/context-async-hooks` is registered in one place during OTel SDK initialization. Swapping to a different context manager (e.g., `@opentelemetry/context-zone` for browser) is a one-line change in the SDK init file.
+
+## Prompt: alternatives-considered
+
+1. **`@opentelemetry/context-zone`** — Zone.js-based context manager designed for Angular/browser environments. Not applicable for a Node.js server; `async_hooks` is the correct primitive for server-side async context.
+2. **Manual context passing** — Thread context explicitly through every function signature. Rejected: error-prone at scale and defeats the auto-instrumentation value of the OTel SDK.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/instrumentation-http.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/instrumentation-http"
+version: "^0.55.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/instrumentation-http license
+  - npm view @opentelemetry/instrumentation-http version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/instrumentation-http license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/instrumentation-http` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community as the first-party HTTP instrumentation plugin. The 0.55.x line is current and tracks the OTel SDK release cycle.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §11 explicitly enables HTTP auto-instrumentation in `initOtelServerNode`. The plugin is configured with query-string stripping on `http.url.path` and a path ignore list (`/_health`, `/_otel-export`) to prevent noise and PII leakage. Restricted to `core-shared/instrumentation/otel/` init paths.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/instrumentation-http` is the standard OTel HTTP auto-instrumentation. No competing HTTP span emitter is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/instrumentation-http` is a pure instrumentation plugin with no independent data transmission. Spans it emits are routed through the configured OTel exporter (Sentry via `@sentry/opentelemetry`). EU residency is governed by the exporter configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/instrumentation-http` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` registers `HttpInstrumentation` with query-string redaction and path ignore rules (ADR-017 §11). This eliminates manual span creation for every incoming HTTP request and outgoing HTTP call.
+
+## Prompt: replaces
+
+Manual `tracer.startSpan()` / `tracer.endSpan()` wrapping around every `http.IncomingMessage` handler and `http.request()` call site. The auto-instrumentation patches Node.js core `http` and `https` modules to emit spans automatically.
+
+## Prompt: migration-cost-out
+
+Low. `HttpInstrumentation` is registered in one init file. Removing it means disabling the plugin registration and optionally adding manual spans at HTTP boundaries — localized to the SDK init and any call sites that relied on automatic context propagation.
+
+## Prompt: alternatives-considered
+
+1. **Manual HTTP spans** — No plugin needed, but requires wrapping every `http.request` and route handler explicitly. Rejected: high boilerplate, easy to miss call sites, loses automatic context propagation headers.
+2. **`dd-trace` HTTP plugin** — Datadog-specific. Rejected in ADR-017: vendor lock-in; OTel plugin achieves the same coverage with vendor-neutral output.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/instrumentation-pg.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/instrumentation-pg"
+version: "^0.50.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/instrumentation-pg license
+  - npm view @opentelemetry/instrumentation-pg version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/instrumentation-pg license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/instrumentation-pg` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community as the first-party PostgreSQL (`pg`) instrumentation plugin. The 0.50.x line is current and tracks the OTel SDK release cycle.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §11 explicitly enables pg auto-instrumentation in `initOtelServerNode` with `enhancedDatabaseReporting: false` to prevent SQL statement capture (PII protection for WHERE clauses). Restricted to `core-shared/instrumentation/otel/` init paths.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/instrumentation-pg` is the standard OTel PostgreSQL auto-instrumentation. No competing database span emitter is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/instrumentation-pg` is a pure instrumentation plugin with no independent data transmission. Spans are routed through the configured OTel exporter. EU residency is governed by the exporter configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/instrumentation-pg` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` registers `PgInstrumentation` with `enhancedDatabaseReporting: false` (ADR-017 §11, R32). This emits database spans for every Payload CMS PostgreSQL query without capturing full SQL text that may contain PII.
+
+## Prompt: replaces
+
+Manual database span wrapping around every `pg` query call site. The auto-instrumentation patches the `pg` module to emit spans automatically, including connection pooling and query timing data.
+
+## Prompt: migration-cost-out
+
+Low. `PgInstrumentation` is registered in one init file. Removing it means disabling the plugin and optionally adding manual spans at `pg` query call sites — localized to the SDK init.
+
+## Prompt: alternatives-considered
+
+1. **Manual pg spans** — No plugin needed, but requires wrapping every Payload CMS / pg query explicitly. Rejected: Payload's query layer abstracts away direct `pg` calls, making manual wrapping impractical without forking Payload internals.
+2. **`pg-monitor` or query logging middleware** — Log-based approach with no OTel integration. Rejected: produces log entries outside the trace pipeline, losing span correlation.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/instrumentation-undici.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/instrumentation-undici"
+version: "^0.10.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/instrumentation-undici license
+  - npm view @opentelemetry/instrumentation-undici version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/instrumentation-undici license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/instrumentation-undici` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 0.10.x line is current and tracks the OTel SDK release cycle. Undici is the HTTP client used by Node.js `fetch` and Next.js server-side requests.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §11 explicitly enables undici auto-instrumentation in `initOtelServerNode`. Undici is the underlying client for Node.js `fetch()` calls including Next.js server components and API route fetch calls. Restricted to `core-shared/instrumentation/otel/` init paths.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/instrumentation-undici` is the standard OTel undici auto-instrumentation. No competing undici span emitter is present in the workspace. It complements `instrumentation-http` (Node.js http module) for full outbound request coverage.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/instrumentation-undici` is a pure instrumentation plugin with no independent data transmission. Spans are routed through the configured OTel exporter. EU residency is governed by the exporter configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/instrumentation-undici` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` registers `UndiciInstrumentation` (ADR-017 §11). This captures outbound fetch calls from Next.js server components and API routes without manual span wrapping.
+
+## Prompt: replaces
+
+Manual span wrapping around `fetch()` and undici `request()` calls. Since Node.js 18+, `fetch` is built on undici, meaning `instrumentation-http` alone would miss `fetch`-based outbound calls. This plugin fills the gap.
+
+## Prompt: migration-cost-out
+
+Low. `UndiciInstrumentation` is registered in one init file. Removing it means disabling the plugin; outbound `fetch` calls would lose automatic spans but no code outside the init file would change.
+
+## Prompt: alternatives-considered
+
+1. **`instrumentation-http` alone** — Sufficient for direct `http.request()` calls but misses `fetch()`/undici calls in Next.js server components. Rejected as incomplete coverage.
+2. **Manual fetch wrapper** — Wrapping every `fetch` call with span creation. Rejected: Next.js makes fetch calls internally (e.g., during RSC rendering), making exhaustive wrapping impractical.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/instrumentation.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/instrumentation"
+version: "^0.55.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/instrumentation license
+  - npm view @opentelemetry/instrumentation version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/instrumentation license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/instrumentation` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community as the base package for auto-instrumentation plugins. The 0.55.x line is current and tracks the SDK release cycle.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §11 enables auto-instrumentations (HTTP, undici, pg) in `initOtelServerNode`. `@opentelemetry/instrumentation` provides the base `InstrumentationBase` class and registration utilities required by all instrumentation plugins. It lives in `core-shared/instrumentation/otel/` init paths only.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/instrumentation` is the standard OTel plugin infrastructure. No competing auto-instrumentation framework is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/instrumentation` is a pure instrumentation framework with no network communication or data transmission. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/instrumentation` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` uses `@opentelemetry/instrumentation` to register the HTTP, undici, and pg instrumentation plugins (ADR-017 §11). These auto-instrumentations eliminate manual span creation for common I/O operations.
+
+## Prompt: replaces
+
+Manual span wrapping around HTTP calls, database queries, and fetch operations. `@opentelemetry/instrumentation` enables the auto-instrumentation plugins that patch Node.js built-ins and popular libraries to emit spans automatically, replacing boilerplate `tracer.startSpan()` calls.
+
+## Prompt: migration-cost-out
+
+Low. `@opentelemetry/instrumentation` is used only at SDK init time to register plugin instances. Removing it requires unregistering the auto-instrumentation plugins and optionally adding manual spans at call sites — a localized change in the init file.
+
+## Prompt: alternatives-considered
+
+1. **Manual span instrumentation only** — No auto-instrumentation base package needed, but every HTTP call and DB query would require explicit span wrapping. Rejected: high boilerplate cost, easy to miss call sites.
+2. **DD-trace or other APM SDK** — Vendor-specific auto-instrumentation agents. Rejected in ADR-017: vendor lock-in; OTel auto-instrumentations achieve the same coverage with vendor-neutral output.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/resources.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/resources"
+version: "^1.27.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/resources license
+  - npm view @opentelemetry/resources version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/resources license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/resources` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 1.27.x line is on the stable 1.x track and receives regular releases. Stable versioning reflects the maturity of the resources specification.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/resources` to `**/instrumentation/otel/**` and app init paths. The `Resource` class is used in `initOtelServerNode` to attach service name, version, and environment attributes to all telemetry signals. Feature packages never import it directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/resources` is the standard OTel resource detection package. No competing resource attribution mechanism is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/resources` is a pure configuration package that attaches static metadata to telemetry signals. It has no network communication or data transmission. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/resources` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` uses `Resource` to tag all OTel signals with `service.name`, `service.version`, and `deployment.environment` attributes, enabling filtering by service in Sentry and future backends.
+
+## Prompt: replaces
+
+Manual tag propagation that would otherwise require attaching service metadata to every span and log record individually. `Resource` is set once at SDK init time and propagates to all signals automatically.
+
+## Prompt: migration-cost-out
+
+Low. `@opentelemetry/resources` is used in one SDK init file. Removing it means losing automatic service metadata on signals — signals would still be emitted but lose `service.name` attribution unless manually added to each span.
+
+## Prompt: alternatives-considered
+
+1. **Manual span attributes** — Set `service.name` on every `startSpan()` call. Rejected: error-prone at scale; resources are a first-class OTel concept designed for this exact purpose.
+2. **Sentry release/environment config** — Sentry SDK accepts `release` and `environment` directly. Rejected: Sentry-specific; OTel Resource is the vendor-neutral mechanism that works with any exporter.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/sdk-logs.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/sdk-logs"
+version: "^0.55.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/sdk-logs license
+  - npm view @opentelemetry/sdk-logs version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/sdk-logs license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/sdk-logs` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 0.55.x line is current and tracks the OTel JS SDK release cycle. The Logs signal is in active specification development within CNCF.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/sdk-logs` to `**/instrumentation/otel/**` and app init paths. `LoggerProvider` and `SimpleLogRecordProcessor` / `BatchLogRecordProcessor` are configured exclusively in `core-shared/instrumentation/otel/init-otel-server-node.ts`. Feature packages use only `@opentelemetry/api-logs` (the stable API), never the SDK directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/sdk-logs` is the OTel Logs SDK implementation. No competing log pipeline SDK is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/sdk-logs` is the log pipeline infrastructure with no independent data transmission. All log records it processes are forwarded through the configured exporter (Sentry via `@sentry/opentelemetry`). EU residency is governed by the exporter's DSN configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/sdk-logs` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` instantiates `LoggerProvider` and registers `PiiScrubLogRecordProcessor` followed by `SentryLogRecordProcessor` from `@sentry/opentelemetry`. The PII scrub processor runs before the Sentry exporter (ADR-017 §7).
+
+## Prompt: replaces
+
+The former `SentryLogger` which called Sentry SDK's `captureException` and breadcrumb APIs directly. `@opentelemetry/sdk-logs` provides the pipeline infrastructure that decouples log emission from the backend exporter.
+
+## Prompt: migration-cost-out
+
+Hard. `@opentelemetry/sdk-logs` is the log pipeline backbone. Removing it requires replacing the entire log processing chain — provider, processors, and exporter wiring — in `core-shared`. The `ILogger` boundary (ADR-014) isolates feature packages, but the core log pipeline is non-trivially coupled to the OTel SDK.
+
+## Prompt: alternatives-considered
+
+1. **Winston + transport** — A well-established Node.js logger with pluggable transports. Rejected in ADR-017: separate pipeline from traces means no automatic span-log correlation; correlation requires manual trace ID injection into every log message.
+2. **Pino** — High-performance JSON logger. Same rejection reason as Winston: separate pipeline, no automatic context propagation from OTel spans.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/sdk-metrics.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/sdk-metrics"
+version: "^1.27.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/sdk-metrics license
+  - npm view @opentelemetry/sdk-metrics version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/sdk-metrics license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/sdk-metrics` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 1.27.x line is on the stable 1.x track; the metrics specification is stable within CNCF.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/sdk-metrics` to `**/instrumentation/otel/**` and app init paths. `MeterProvider` is configured in `core-shared/instrumentation/otel/init-otel-server-node.ts`. Feature packages use only `@opentelemetry/api`'s `metrics` API (indirectly via `IMetrics`), never the SDK directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/sdk-metrics` is the OTel metrics SDK implementation. No competing metrics SDK is present in the workspace. The `IMetrics` interface (ADR-017 §10) is backed exclusively by this package.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/sdk-metrics` is the metrics pipeline infrastructure with no independent data transmission. All metrics are forwarded through the configured exporter. EU residency is governed by the exporter's DSN configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/sdk-metrics` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` instantiates `MeterProvider` and backs the `OtelMetrics` implementation of `IMetrics` (ADR-017 §10). The three `IMetrics` methods (`counter`, `histogram`, `gauge`) map to OTel counter, histogram, and UpDownCounter instruments.
+
+## Prompt: replaces
+
+ADR-014 had no `IMetrics` signal. `@opentelemetry/sdk-metrics` introduces the metrics signal as the SDK backing for the new `IMetrics` interface (ADR-017 §10). It supersedes any ad-hoc counter increment patterns that would otherwise have been added without a unified metrics pipeline.
+
+## Prompt: migration-cost-out
+
+Hard. `@opentelemetry/sdk-metrics` backs the `OtelMetrics` implementation used throughout `core-shared`. Replacing it requires implementing the three `IMetrics` instruments with a different metrics SDK and re-registering with the OTel SDK. The `IMetrics` interface (ADR-017 §10) isolates feature packages from the SDK details.
+
+## Prompt: alternatives-considered
+
+1. **Prometheus client (`prom-client`)** — Popular Node.js metrics library. Rejected in ADR-017: separate pipeline from traces/logs; no automatic span context on metrics; would require a second init path alongside OTel.
+2. **Statsd / DogStatsD** — Rejected: requires a separate collector sidecar; UDP-based with no context propagation; vendor-coupling concern for DogStatsD.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/sdk-node.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/sdk-node"
+version: "^0.55.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/sdk-node license
+  - npm view @opentelemetry/sdk-node version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/sdk-node license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/sdk-node` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 0.55.x line is current and tracks the OTel JS SDK release cycle. `sdk-node` is the meta-package that wires together the trace, log, metric, and auto-instrumentation subsystems for Node.js.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/sdk-node` to `**/instrumentation/otel/**` and app init paths. `NodeSDK` is instantiated once in `core-shared/instrumentation/otel/init-otel-server-node.ts`. Feature packages never instantiate or import it directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/sdk-node` is the standard Node.js OTel SDK meta-package. No competing OTel SDK bootstrapper is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/sdk-node` is the SDK bootstrapper with no independent data transmission. All signals it routes pass through the configured exporters. EU residency is governed by the exporter DSN configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/sdk-node` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` uses `NodeSDK` to bootstrap the full OTel pipeline: resource detection, context propagation, trace/log/metric providers, `SentrySpanProcessor`, `PiiScrubSpanProcessor`, and all auto-instrumentation plugins (ADR-017).
+
+## Prompt: replaces
+
+The former `initSentryServerNode` function which called Sentry SDK init methods directly. `NodeSDK` from `sdk-node` provides the unified bootstrapper that wires the complete OTel pipeline in a single `sdk.start()` call, replacing the need to manually construct and register each provider.
+
+## Prompt: migration-cost-out
+
+Hard. `NodeSDK` is the single init entry point for the entire OTel server pipeline. Replacing it requires manually constructing and registering trace provider, log provider, metric provider, context manager, propagator, and all instrumentation plugins — essentially reimplementing what `NodeSDK` provides. The `ITracer`/`ILogger`/`IMetrics` boundaries (ADR-014/017) isolate feature code but the init layer itself is deeply coupled.
+
+## Prompt: alternatives-considered
+
+1. **Manual SDK assembly** — Constructing `TracerProvider`, `LoggerProvider`, `MeterProvider` individually without `NodeSDK`. Rejected: high boilerplate; `NodeSDK` handles shutdown hooks, context manager registration, and propagator setup automatically.
+2. **`@opentelemetry/auto-instrumentations-node`** — A higher-level meta-package that bundles many plugins. Rejected: includes instrumentations the workspace doesn't need; ADR-017 §11 specifies exactly which plugins to enable (http, undici, pg) for minimal scope.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/sdk-trace-base.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/sdk-trace-base"
+version: "^1.27.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/sdk-trace-base license
+  - npm view @opentelemetry/sdk-trace-base version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/sdk-trace-base license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/sdk-trace-base` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community on the stable 1.x track. The 1.27.x line is current; the tracing specification is stable within CNCF.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/sdk-trace-base` to `**/instrumentation/otel/**` and app init paths. `SpanProcessor` and `ReadableSpan` types from this package are used to implement `PiiScrubSpanProcessor` in `core-shared`. `packages/core-audit` also uses `ReadableSpan` for span context in audit records.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/sdk-trace-base` is the OTel trace SDK foundation. No competing trace SDK is present in the workspace.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/sdk-trace-base` is the tracing SDK infrastructure with no independent data transmission. Spans are forwarded through configured processors and exporters. EU residency is governed by the exporter DSN configuration.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/sdk-trace-base` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/pii-scrub-span-processor.ts` implements `SpanProcessor` from `@opentelemetry/sdk-trace-base` to scrub PII attributes before spans reach the Sentry exporter (ADR-017 §7). `packages/core-audit` uses `ReadableSpan` for audit record correlation.
+
+## Prompt: replaces
+
+The former `SentryTracer` which called Sentry SDK span methods directly. `@opentelemetry/sdk-trace-base` provides the `SpanProcessor` extension point that enables the `PiiScrubSpanProcessor` — a vendor-neutral, pre-export PII scrubbing layer.
+
+## Prompt: migration-cost-out
+
+Hard. `@opentelemetry/sdk-trace-base` types (`SpanProcessor`, `ReadableSpan`) are used in both `core-shared` PII scrub implementation and `core-audit`. Replacing it means adopting a different span processing abstraction and rewriting both the processor and audit span-context integration.
+
+## Prompt: alternatives-considered
+
+1. **Sentry `beforeSendTransaction` hook** — Sentry-native PII scrubbing hook. Rejected in ADR-017 §7: runs inside Sentry after OTel conversion; the OTel processor layer runs earlier and is vendor-agnostic, so any future exporter also sees clean data.
+2. **No span processor, rely on Sentry scrubbing rules** — Rejected: Sentry-specific configuration; future exporter additions would need their own scrubbing configured separately.
+
+See ADR-017 for the full decision rationale.

docs/library-decisions/2026-05-14-@opentelemetry/semantic-conventions.md

@@ -0,0 +1,87 @@
+---
+package: "@opentelemetry/semantic-conventions"
+version: "^1.27.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: adr-017
+filter-results:
+  license: Apache-2.0
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: n/a
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @opentelemetry/semantic-conventions license
+  - npm view @opentelemetry/semantic-conventions version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: Apache-2.0 -->
+
+`npm view @opentelemetry/semantic-conventions license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@opentelemetry/semantic-conventions` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Actively maintained by the OpenTelemetry community. The 1.27.x line is on the stable 1.x track. Semantic conventions are a CNCF specification that evolves across OTel SDK releases.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+ADR-017 §8 restricts `@opentelemetry/semantic-conventions` to `**/instrumentation/otel/**` and app init paths. Attribute name constants from this package are used in `core-shared/instrumentation/otel/` to label span attributes consistently (e.g., `SEMATTRS_DB_SYSTEM`, `SEMATTRS_HTTP_METHOD`). Feature packages never import it directly.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@opentelemetry/semantic-conventions` is the canonical OTel attribute name registry. No competing attribute-naming package is present in the workspace. Using this package prevents hard-coded string attribute names that diverge from the OTel spec.
+
+## Filter: eu-residency
+
+<!-- Result: n/a -->
+
+`@opentelemetry/semantic-conventions` is a pure constants package with no network communication or data transmission. EU residency does not apply.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/semantic-conventions` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`packages/core-shared/src/instrumentation/otel/` uses semantic convention constants to name span attributes on HTTP instrumentation config, pg instrumentation config, and custom spans. Consistent attribute naming enables Sentry and any future backend to parse spans correctly.
+
+## Prompt: replaces
+
+Hard-coded string attribute names (e.g., `"http.method"`, `"db.system"`) that would otherwise be scattered across instrumentation code without a canonical reference. Semantic conventions provide typed, versioned constants with IDE autocompletion and forwards-compatibility guarantees.
+
+## Prompt: migration-cost-out
+
+Low. `@opentelemetry/semantic-conventions` is a constants-only package. Removing it means replacing constant references with hard-coded strings in `core-shared` instrumentation code — a mechanical change with no behavioral impact.
+
+## Prompt: alternatives-considered
+
+1. **Hard-coded string constants** — Define attribute names as local `const` values. Rejected: diverges from the OTel specification over time as attributes are renamed or deprecated; loses IDE-navigable documentation links.
+2. **No attribute naming standard** — Each developer picks attribute names ad-hoc. Rejected: breaks Sentry query grouping, dashboard filters, and any backend that relies on spec-compliant attribute names for parsing.
+
+See ADR-017 for the full decision rationale.