---
id: 08-backfill-traces
epic: library-evaluation-policy
title: Backfill library traces for existing feature- and core-tier runtime deps
type: technical-story
status: done
feature: docs
depends-on: [01-trace-schema-foundation]
blocks: []
created: 2026-05-14T06:52:02+02:00
updated: 2026-05-14T19:16:52.691Z
---

## Goal

Write approved library trace files dated 2026-05-14 in `docs/library-decisions/` for every existing runtime dependency in feature- and core-tier packages, grouped by ADR provenance into four commits. No package.json is changed; these commits are pure trace-file additions.

## Why

Without backfill, every existing dep becomes a pre-commit-hook failure the first time someone touches a `package.json` — the enforcement gate would fire retroactively. Backfill establishes the baseline so the gate is additive (new deps require traces) rather than disruptive (old deps fail immediately). Grouping by ADR cluster makes the commit history readable and keeps each commit focused on a coherent rationale.

## Done when

- All runtime deps in `packages/` (feature- and core-tier) have a corresponding `docs/library-decisions/YYYY-MM-DD-<name>.md` with `decision: approved`, `date: 2026-05-14`, and the relevant `adr` citation (or `null` for un-cited deps).
- Four commits land, one per cluster:
  - **ADR-002 cluster**: `inversify`, `reflect-metadata`.
  - **ADR-014 cluster**: `@sentry/node`, `@sentry/nextjs`, `@sentry/react`, and any other Sentry packages present.
  - **ADR-017 cluster**: `@opentelemetry/api`, `@opentelemetry/sdk-node`, and any other OTel packages present.
  - **Un-cited cluster**: `payload`, `@trpc/server`, `zod`, `superjson`, and any remaining runtime deps not covered by an ADR.
- All trace files pass `validateTrace()` from `schema.mjs` (Story 01).
- `pnpm lint && pnpm fallow:audit` pass after all four commits.

## In scope

- `docs/library-decisions/<date>-<name>.md` trace files — one per dep.
- Four conventional commits: `chore(deps): backfill library traces for <cluster>`.

## Out of scope

- Deps in `apps/*` — app-tier is out of scope per the PRD.
- devDeps in any tier — exempt from traces.
- Changing any `package.json` — backfill is trace-only.
- Optional core packages not yet installed in the workspace — covered by Story 07 (generator pre-shipped traces) when they are scaffolded.

## Tasks

- [x] Inventory all runtime deps in `packages/` (run `jq '.dependencies // {} | keys' packages/*/package.json packages/core-*/package.json` or equivalent); write approved trace files for the ADR-002 cluster (`inversify`, `reflect-metadata`) in `docs/library-decisions/`; commit as `chore(deps): backfill library traces for ADR-002 cluster`.
- [x] Write approved trace files for the ADR-014 cluster (Sentry packages); commit as `chore(deps): backfill library traces for ADR-014 cluster`.
- [x] Write approved trace files for the ADR-017 cluster (OpenTelemetry packages); commit as `chore(deps): backfill library traces for ADR-017 cluster`.
- [x] Write approved trace files for the un-cited cluster (`payload`, `@trpc/server`, `zod`, `superjson`, and any remaining runtime deps); commit as `chore(deps): backfill library traces for un-cited cluster`; all gates pass after this final commit.