feat(instrumentation): close R44 gap — throw-site capture for use cases + controllers

Plan 10 documented R44 (capture at originating-throw layer) but only the
R43 repo leg was wired. captureException had zero call sites in any
controller or use-case body. This commit closes the gap.

Mechanism:
- Extract __sentryReported flag helpers into core-shared/instrumentation/
  reported-flag.ts. SentryLogger switches to importing them; RecordingLogger
  carries an inlined copy (tooling → core boundary disallows the import).
- Add withCapture(logger, tags, fn) higher-order wrapper paralleling
  withSpan. On throw: capture-with-tags, mark, re-throw. Bail if the flag
  was already set — covers the bubbled-from-repo case so each error
  surfaces in the logger exactly once with the inner-most layer's tags.
- Apply withSpan(withCapture(factory)) in every feature's bind-production
  and bind-dev-seed: auth (3 use cases × 3 controllers), blog (3×3),
  marketing-pages (2×2), navigation (1×1), media (3×3). Span is outermost
  so the errored span timing reflects the capture-and-rethrow.
- RecordingLogger.captureException now also honours the flag — test
  capture counts stay honest when both repo and outer layer wrap.

Tests:
- packages/core-shared/src/instrumentation/with-capture.test.ts —
  4 cases covering success, capture-on-throw, mark-on-capture, no-double
  via the flag.
- packages/blog/tests/r44-no-double-capture.test.ts — 3 cases: repo throw
  → 1 capture with repo tags; controller parse fail → 1 capture with
  controller tags; success → 0 captures.

Verification: pnpm test 26/26, pnpm lint 15/15, pnpm typecheck 14/14.

Docs: ADR-014 and the refactor log gain a "Post-merge follow-up" section
recording the gap, the fix, and the underlying lesson (don't describe
intent as shipped state — grep first).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/decisions/adr-014-instrumentation-sentry.md

@@ -68,6 +68,20 @@ The Lazar Nikolov reference repo (`nextjs-clean-architecture`) demonstrates a Se
 - **Pre-existing lint nits surfaced when Task 28's restricted-imports rule lit up `pnpm lint`:** added `argsIgnorePattern: "^_"` to the shared eslint config (matches the underscore convention used throughout the repo); added `globals.node` for `*.{mjs,cjs,js}` and `*.config.{ts,tsx}` so `next.config.mjs`'s `process.env` lints clean; cleared two unused-import / unused-disable nits in marketing-pages and core-testing that were unrelated to instrumentation but blocked the lint gate.
 - **Direct `@repo/core-shared` deps:** `apps/cms` and `apps/web-tanstack` previously had only transitive access to `@repo/core-shared`; both gained explicit `workspace:*` deps so the deep `./instrumentation/sentry/*` subpath imports resolve.
 
+## Post-merge follow-up — closing the R44 gap
+
+Plan 10 as merged shipped repository-side capture (R43) but **not** use-case or controller capture (R44). The ADR/AGENTS docs described the intended capture-rules table as if it were the as-shipped state; in fact every `captureException` call site lived in `infrastructure/repositories/*.repository.ts`. A grep proved it: zero call sites in any controller or use-case body. The user spotted the gap.
+
+**Fix (post-merge commit):**
+
+1. Extracted the `__sentryReported` flag helpers into `core-shared/instrumentation/reported-flag.ts` (`markReported`, `isReported`). `SentryLogger` now imports them; `RecordingLogger` carries an inlined copy (tooling → core import is disallowed by the boundary rule, so duplication is the right tradeoff).
+2. Added `withCapture(logger, tags, fn)` higher-order wrapper at `core-shared/instrumentation/with-capture.ts`, parallel to `withSpan`. On error: capture-with-tags, mark, re-throw — but bail if the flag is already set (covers the bubbled-from-repo case).
+3. Applied `withSpan(withCapture(factory))` to every use case and controller in every feature's `bind-production.ts` and `bind-dev-seed.ts`. Span is outermost so the errored span's timing reflects the capture-and-rethrow.
+4. `RecordingLogger.captureException` now also honours the flag, so test assertions about capture counts stay honest.
+5. Added `packages/blog/tests/r44-no-double-capture.test.ts` to lock the contract: an error originated in the repo is captured once with repo tags; an error originated in the controller (parse failure) is captured once with controller tags; success paths capture nothing.
+
+**Why use cases also wrap, even though current bodies mostly delegate to the repo:** R44's intent is that *any* throw originated locally — output-schema validation, business-rule errors like `AuthenticationError` in `signInUseCase` — gets captured with use-case tags. The wrapper makes the rule uniform; the flag makes it safe.
+
 ## Related
 
 - ADR-008 — per-feature DI containers

docs/superpowers/refactor-logs/2026-05-06-instrumentation-sentry.md

@@ -70,3 +70,19 @@
 - **Vite/TanStack Start typing not yet present in web-tanstack.** The client entry uses `import.meta.env.VITE_*`, but no Vite types are installed since the build infra is a placeholder. A small `src/vite-env.d.ts` declares the env shape for now; replace with `/// <reference types="vite/client" />` when Vite is wired.
 
 - **Spec deviations are usually a sign of a mis-aligned spec, not a wrong implementation.** Three of the deviations above (ipaddress, vertical-feature-spec section number, di-explainer section number) are minor; the vite.config skip and vite-env shim are real architecture decisions worth recording in ADR-014 alongside the major decisions.
+
+## Post-merge follow-up — R44 capture leg was missing
+
+After Plan 10 merged to `main`, the user pushed back on a description I gave of how capture works. A `grep captureException packages/*/src` showed zero call sites in any controller or use-case body — the R44 leg of "throw-site capture" had been **documented but never implemented**. Only repos (R43) actually called `logger.captureException`.
+
+I had described intent as reality both during execution and in the ADR-014 capture-rules table. The lesson is now in `feedback_verify_before_claiming.md`: when describing what code does — especially in the same session as writing it — grep before asserting.
+
+**The fix (one commit on `main`):**
+
+1. Extracted the `__sentryReported` flag helpers into `core-shared/instrumentation/reported-flag.ts`. `SentryLogger` switched to importing them; `RecordingLogger` got an inlined copy (boundary rule disallows tooling → core).
+2. Added `withCapture(logger, tags, fn)` at `core-shared/instrumentation/with-capture.ts` — parallel to `withSpan`. On throw: capture, mark, re-throw — but bail if the flag was already set.
+3. Wrapped every use case and controller in every feature's `bind-production.ts` and `bind-dev-seed.ts` with `withSpan(withCapture(factory))`. Span outermost so the errored span's timing reflects the capture-and-rethrow.
+4. `RecordingLogger` now also honours the flag, so test capture counts are honest across the chain.
+5. Added `packages/blog/tests/r44-no-double-capture.test.ts` proving: (a) repo-originated error → 1 capture with repo tags; (b) controller parse failure → 1 capture with controller tags; (c) success → 0 captures.
+
+Verification: `pnpm test` 26/26, `pnpm lint` 15/15 (warnings only), `pnpm typecheck` 14/14.

packages/auth/src/di/bind-dev-seed.ts

@@ -1,5 +1,6 @@
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -61,17 +62,29 @@ export async function bindDevSeedAuth(tracer: ITracer, logger: ILogger): Promise
   const wrappedSignIn = withSpan(
     tracer,
     { name: "auth.signIn", op: "use-case" },
-    signInUseCase(repo, authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signIn" },
+      signInUseCase(repo, authService),
+    ),
   );
   const wrappedSignUp = withSpan(
     tracer,
     { name: "auth.signUp", op: "use-case" },
-    signUpUseCase(repo, authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signUp" },
+      signUpUseCase(repo, authService),
+    ),
   );
   const wrappedSignOut = withSpan(
     tracer,
     { name: "auth.signOut", op: "use-case" },
-    signOutUseCase(authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signOut" },
+      signOutUseCase(authService),
+    ),
   );
 
   for (const sym of [
@@ -94,7 +107,11 @@ export async function bindDevSeedAuth(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "auth.signIn", op: "controller" },
-        signInController(wrappedSignIn),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signIn" },
+          signInController(wrappedSignIn),
+        ),
       ),
     );
   authContainer
@@ -103,7 +120,11 @@ export async function bindDevSeedAuth(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "auth.signUp", op: "controller" },
-        signUpController(wrappedSignUp),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signUp" },
+          signUpController(wrappedSignUp),
+        ),
       ),
     );
   authContainer
@@ -112,7 +133,11 @@ export async function bindDevSeedAuth(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "auth.signOut", op: "controller" },
-        signOutController(wrappedSignOut),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signOut" },
+          signOutController(wrappedSignOut),
+        ),
       ),
     );
 }

packages/auth/src/di/bind-production.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from "payload";
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -53,21 +54,33 @@ export function bindProductionAuth(
     .bind<IAuthenticationService>(AUTH_SYMBOLS.IAuthenticationService)
     .toConstantValue(authService);
 
-  // Use cases — wrapped with span at bind time
+  // Use cases — wrapped with span + capture at bind time
   const wrappedSignIn = withSpan(
     tracer,
     { name: "auth.signIn", op: "use-case" },
-    signInUseCase(repo, authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signIn" },
+      signInUseCase(repo, authService),
+    ),
   );
   const wrappedSignUp = withSpan(
     tracer,
     { name: "auth.signUp", op: "use-case" },
-    signUpUseCase(repo, authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signUp" },
+      signUpUseCase(repo, authService),
+    ),
   );
   const wrappedSignOut = withSpan(
     tracer,
     { name: "auth.signOut", op: "use-case" },
-    signOutUseCase(authService),
+    withCapture(
+      logger,
+      { feature: "auth", layer: "use-case", name: "auth.signOut" },
+      signOutUseCase(authService),
+    ),
   );
 
   for (const sym of [
@@ -95,7 +108,11 @@ export function bindProductionAuth(
       withSpan(
         tracer,
         { name: "auth.signIn", op: "controller" },
-        signInController(wrappedSignIn),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signIn" },
+          signInController(wrappedSignIn),
+        ),
       ),
     );
   authContainer
@@ -104,7 +121,11 @@ export function bindProductionAuth(
       withSpan(
         tracer,
         { name: "auth.signUp", op: "controller" },
-        signUpController(wrappedSignUp),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signUp" },
+          signUpController(wrappedSignUp),
+        ),
       ),
     );
   authContainer
@@ -113,7 +134,11 @@ export function bindProductionAuth(
       withSpan(
         tracer,
         { name: "auth.signOut", op: "controller" },
-        signOutController(wrappedSignOut),
+        withCapture(
+          logger,
+          { feature: "auth", layer: "controller", name: "auth.signOut" },
+          signOutController(wrappedSignOut),
+        ),
       ),
     );
 }

packages/blog/src/di/bind-dev-seed.ts

@@ -1,5 +1,6 @@
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -52,17 +53,29 @@ export async function bindDevSeedBlog(tracer: ITracer, logger: ILogger): Promise
   const wrappedGetArticles = withSpan(
     tracer,
     { name: "blog.getArticles", op: "use-case" },
-    getArticlesUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.getArticles" },
+      getArticlesUseCase(repo),
+    ),
   );
   const wrappedGetArticleBySlug = withSpan(
     tracer,
     { name: "blog.getArticleBySlug", op: "use-case" },
-    getArticleBySlugUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.getArticleBySlug" },
+      getArticleBySlugUseCase(repo),
+    ),
   );
   const wrappedCreateArticle = withSpan(
     tracer,
     { name: "blog.createArticle", op: "use-case" },
-    createArticleUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.createArticle" },
+      createArticleUseCase(repo),
+    ),
   );
 
   for (const sym of [
@@ -87,7 +100,11 @@ export async function bindDevSeedBlog(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "blog.getArticles", op: "controller" },
-        getArticlesController(wrappedGetArticles),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.getArticles" },
+          getArticlesController(wrappedGetArticles),
+        ),
       ),
     );
   blogContainer
@@ -96,7 +113,11 @@ export async function bindDevSeedBlog(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "blog.getArticleBySlug", op: "controller" },
-        getArticleBySlugController(wrappedGetArticleBySlug),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.getArticleBySlug" },
+          getArticleBySlugController(wrappedGetArticleBySlug),
+        ),
       ),
     );
   blogContainer
@@ -105,7 +126,11 @@ export async function bindDevSeedBlog(tracer: ITracer, logger: ILogger): Promise
       withSpan(
         tracer,
         { name: "blog.createArticle", op: "controller" },
-        createArticleController(wrappedCreateArticle),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.createArticle" },
+          createArticleController(wrappedCreateArticle),
+        ),
       ),
     );
 }

packages/blog/src/di/bind-production.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from "payload";
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -37,21 +38,33 @@ export function bindProductionBlog(
   const repo = new ArticlesRepository(config, tracer, logger);
   blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).toConstantValue(repo);
 
-  // Use cases — wrapped with span at bind time (R41)
+  // Use cases — wrapped with span + capture at bind time (R41, R44)
   const wrappedGetArticles = withSpan(
     tracer,
     { name: "blog.getArticles", op: "use-case" },
-    getArticlesUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.getArticles" },
+      getArticlesUseCase(repo),
+    ),
   );
   const wrappedGetArticleBySlug = withSpan(
     tracer,
     { name: "blog.getArticleBySlug", op: "use-case" },
-    getArticleBySlugUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.getArticleBySlug" },
+      getArticleBySlugUseCase(repo),
+    ),
   );
   const wrappedCreateArticle = withSpan(
     tracer,
     { name: "blog.createArticle", op: "use-case" },
-    createArticleUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "blog", layer: "use-case", name: "blog.createArticle" },
+      createArticleUseCase(repo),
+    ),
   );
 
   if (blogContainer.isBound(BLOG_SYMBOLS.IGetArticlesUseCase)) {
@@ -85,7 +98,11 @@ export function bindProductionBlog(
       withSpan(
         tracer,
         { name: "blog.getArticles", op: "controller" },
-        getArticlesController(wrappedGetArticles),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.getArticles" },
+          getArticlesController(wrappedGetArticles),
+        ),
       ),
     );
   blogContainer
@@ -94,7 +111,11 @@ export function bindProductionBlog(
       withSpan(
         tracer,
         { name: "blog.getArticleBySlug", op: "controller" },
-        getArticleBySlugController(wrappedGetArticleBySlug),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.getArticleBySlug" },
+          getArticleBySlugController(wrappedGetArticleBySlug),
+        ),
       ),
     );
   blogContainer
@@ -103,7 +124,11 @@ export function bindProductionBlog(
       withSpan(
         tracer,
         { name: "blog.createArticle", op: "controller" },
-        createArticleController(wrappedCreateArticle),
+        withCapture(
+          logger,
+          { feature: "blog", layer: "controller", name: "blog.createArticle" },
+          createArticleController(wrappedCreateArticle),
+        ),
       ),
     );
 }

packages/blog/tests/r44-no-double-capture.test.ts

@@ -0,0 +1,141 @@
+// R44 — verify the full chain (controller → use case → repo) wraps with
+// withSpan + withCapture and never double-captures the same error.
+//
+// Each layer's withCapture catch checks the __sentryReported flag (set by
+// the inner-most layer that captured first) and skips. End result: one
+// error → one logger.captureException call, with the inner-most tags.
+
+import { describe, it, expect } from "vitest";
+import {
+  RecordingTracer,
+  RecordingLogger,
+} from "@repo/core-testing/instrumentation";
+import { withSpan, withCapture } from "@repo/core-shared/instrumentation";
+
+import { MockArticlesRepository } from "../src/infrastructure/repositories/articles.repository.mock";
+import { getArticleBySlugUseCase } from "../src/application/use-cases/get-article-by-slug.use-case";
+import { getArticleBySlugController } from "../src/interface-adapters/controllers/get-article-by-slug.controller";
+
+describe("R44 — no double-capture across span/capture-wrapped layers", () => {
+  it("an error originated in the repo is captured exactly once with repo tags", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+
+    // Repo throws on getArticleBySlug for a special slug. We simulate the
+    // throw via a subclass — the production repos call captureException
+    // inside their own try/catch as part of the repo span body.
+    class ThrowingRepo extends MockArticlesRepository {
+      override getArticleBySlug = async (_slug: string) => {
+        const err = new Error("boom from repo");
+        // Mirror what the real repo does: capture with repo tags, mark the
+        // flag (RecordingLogger.captureException does this for us now).
+        logger.captureException(err, {
+          tags: { feature: "blog", repo: "articles", method: "getArticleBySlug" },
+        });
+        throw err;
+      };
+    }
+
+    const repo = new ThrowingRepo(tracer, logger);
+
+    // Wire the use case + controller exactly the way bind-production does.
+    const wrappedUC = withSpan(
+      tracer,
+      { name: "blog.getArticleBySlug", op: "use-case" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "use-case", name: "blog.getArticleBySlug" },
+        getArticleBySlugUseCase(repo),
+      ),
+    );
+    const wrappedCtrl = withSpan(
+      tracer,
+      { name: "blog.getArticleBySlug", op: "controller" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "controller", name: "blog.getArticleBySlug" },
+        getArticleBySlugController(wrappedUC),
+      ),
+    );
+
+    await expect(wrappedCtrl({ slug: "anything" })).rejects.toThrow("boom from repo");
+
+    // R44: exactly one capture. Outer wrappers saw the flag and skipped.
+    expect(logger.captures).toHaveLength(1);
+    const only = logger.captures[0];
+    expect(only?.kind).toBe("exception");
+    if (only?.kind !== "exception") return;
+    expect(only.ctx?.tags).toEqual({
+      feature: "blog",
+      repo: "articles",
+      method: "getArticleBySlug",
+    });
+  });
+
+  it("an error originated in the controller (parse failure) is captured once with controller tags", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+    const repo = new MockArticlesRepository();
+
+    const wrappedUC = withSpan(
+      tracer,
+      { name: "blog.getArticleBySlug", op: "use-case" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "use-case", name: "blog.getArticleBySlug" },
+        getArticleBySlugUseCase(repo),
+      ),
+    );
+    const wrappedCtrl = withSpan(
+      tracer,
+      { name: "blog.getArticleBySlug", op: "controller" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "controller", name: "blog.getArticleBySlug" },
+        getArticleBySlugController(wrappedUC),
+      ),
+    );
+
+    // safeParse fails because slug is missing.
+    await expect(wrappedCtrl({})).rejects.toThrow();
+
+    expect(logger.captures).toHaveLength(1);
+    const only = logger.captures[0];
+    expect(only?.kind).toBe("exception");
+    if (only?.kind !== "exception") return;
+    expect(only.ctx?.tags).toEqual({
+      feature: "blog",
+      layer: "controller",
+      name: "blog.getArticleBySlug",
+    });
+  });
+
+  it("a successful call captures nothing", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+    const repo = new MockArticlesRepository();
+
+    const wrappedUC = withSpan(
+      tracer,
+      { name: "blog.getArticles", op: "use-case" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "use-case", name: "blog.getArticles" },
+        async () => [],
+      ),
+    );
+    const wrappedCtrl = withSpan(
+      tracer,
+      { name: "blog.getArticles", op: "controller" },
+      withCapture(
+        logger,
+        { feature: "blog", layer: "controller", name: "blog.getArticles" },
+        async () => wrappedUC(),
+      ),
+    );
+
+    await expect(wrappedCtrl()).resolves.toEqual([]);
+    expect(logger.captures).toHaveLength(0);
+    void repo;
+  });
+});

packages/core-shared/src/instrumentation/index.ts

@@ -12,6 +12,8 @@ export type {
 export { NoopTracer } from "./noop-tracer";
 export { NoopLogger } from "./noop-logger";
 export { withSpan } from "./with-span";
+export { withCapture } from "./with-capture";
+export { isReported, markReported } from "./reported-flag";
 export { INSTRUMENTATION_SYMBOLS } from "./symbols";
 export { bindNoopInstrumentation } from "./di/bind-noop-instrumentation";
 export {

packages/core-shared/src/instrumentation/reported-flag.ts

@@ -0,0 +1,24 @@
+// Non-enumerable flag used by every ILogger implementation to skip
+// already-reported errors. The flag is non-enumerable so JSON.stringify
+// and {...err} spread won't surface it.
+
+const REPORTED = "__sentryReported" as const;
+
+export function isReported(err: unknown): boolean {
+  return (
+    err !== null &&
+    typeof err === "object" &&
+    Boolean((err as Record<string, unknown>)[REPORTED])
+  );
+}
+
+export function markReported(err: unknown): void {
+  if (err !== null && typeof err === "object" && !isReported(err)) {
+    Object.defineProperty(err, REPORTED, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+}

packages/core-shared/src/instrumentation/sentry/sentry-logger.ts

@@ -1,27 +1,7 @@
 // packages/core-shared/src/instrumentation/sentry/sentry-logger.ts
 import * as Sentry from "@sentry/nextjs";
 import type { ILogger, Breadcrumb, CaptureContext } from "../logger.interface";
-
+import { isReported, markReported } from "../reported-flag";
-const REPORTED = "__sentryReported" as const;
-
-function isReported(err: unknown): boolean {
-  return (
-    err !== null &&
-    typeof err === "object" &&
-    Boolean((err as Record<string, unknown>)[REPORTED])
-  );
-}
-
-function markReported(err: unknown): void {
-  if (err !== null && typeof err === "object") {
-    Object.defineProperty(err, REPORTED, {
-      value: true,
-      enumerable: false,
-      configurable: false,
-      writable: false,
-    });
-  }
-}
 
 export class SentryLogger implements ILogger {
   captureException(err: unknown, ctx?: CaptureContext): void {

packages/core-shared/src/instrumentation/with-capture.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from "vitest";
+import { withCapture } from "@/instrumentation/with-capture";
+import type { ILogger } from "@/instrumentation/logger.interface";
+import { isReported } from "@/instrumentation/reported-flag";
+
+function makeLogger(): ILogger & { captureException: ReturnType<typeof vi.fn> } {
+  return {
+    captureException: vi.fn(),
+    captureMessage: vi.fn(),
+    addBreadcrumb: vi.fn(),
+    setUser: vi.fn(),
+  };
+}
+
+describe("withCapture", () => {
+  it("does not capture on success", async () => {
+    const logger = makeLogger();
+    const wrapped = withCapture(logger, { layer: "use-case" }, async (x: number) => x + 1);
+    await expect(wrapped(1)).resolves.toBe(2);
+    expect(logger.captureException).not.toHaveBeenCalled();
+  });
+
+  it("captures with tags and re-throws on failure", async () => {
+    const logger = makeLogger();
+    const err = new Error("boom");
+    const wrapped = withCapture(logger, { layer: "use-case", name: "blog.x" }, async () => {
+      throw err;
+    });
+    await expect(wrapped()).rejects.toBe(err);
+    expect(logger.captureException).toHaveBeenCalledTimes(1);
+    expect(logger.captureException).toHaveBeenCalledWith(err, {
+      tags: { layer: "use-case", name: "blog.x" },
+    });
+  });
+
+  it("marks the error as reported after first capture", async () => {
+    const logger = makeLogger();
+    const err = new Error("boom");
+    const wrapped = withCapture(logger, { layer: "use-case" }, async () => {
+      throw err;
+    });
+    await expect(wrapped()).rejects.toBe(err);
+    expect(isReported(err)).toBe(true);
+  });
+
+  it("does NOT capture again when the same error already carries the flag", async () => {
+    const logger = makeLogger();
+    const err = new Error("boom");
+    // Simulate an inner layer (repo) having already captured + marked.
+    const inner = withCapture(logger, { layer: "repo" }, async () => {
+      throw err;
+    });
+    const outer = withCapture(logger, { layer: "use-case" }, () => inner());
+
+    await expect(outer()).rejects.toBe(err);
+    // Only the inner layer captured it; outer saw the flag and bailed.
+    expect(logger.captureException).toHaveBeenCalledTimes(1);
+    expect(logger.captureException).toHaveBeenCalledWith(err, {
+      tags: { layer: "repo" },
+    });
+  });
+});

packages/core-shared/src/instrumentation/with-capture.ts

@@ -0,0 +1,40 @@
+import type { ILogger } from "./logger.interface";
+import { isReported, markReported } from "./reported-flag";
+
+/**
+ * Higher-order wrapper applied at DI bind time. Mirrors `withSpan`: takes a
+ * factory result `(args) => Promise<R>` and returns the same shape, but any
+ * thrown error is captured via `logger.captureException(err, { tags })` before
+ * being re-thrown.
+ *
+ * Skips capture if the error already carries the `__sentryReported` flag —
+ * this is what prevents double-capture when the same error bubbles through
+ * a wrapped repo → use case → controller chain (the repo's catch site
+ * captures first; outer wrappers see the flag and bail).
+ *
+ * Usage at bind time:
+ *
+ *   const captured = withCapture(logger, { feature: "blog", layer: "use-case", name: "blog.getArticles" }, factory(deps));
+ *   const wrapped  = withSpan(tracer, opts, captured);
+ *
+ * Span wraps capture: the span timing reflects the captured-and-rethrown
+ * failure (errored span gets a duration), and the capture has accurate
+ * tags by the time it fires.
+ */
+export function withCapture<Args extends unknown[], R>(
+  logger: ILogger,
+  tags: Record<string, string>,
+  fn: (...args: Args) => Promise<R>,
+): (...args: Args) => Promise<R> {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (err) {
+      if (!isReported(err)) {
+        logger.captureException(err, { tags });
+        markReported(err);
+      }
+      throw err;
+    }
+  };
+}

packages/core-testing/src/instrumentation/recording-logger.ts

@@ -24,13 +24,38 @@ export type RecordedCapture =
   | { kind: "exception"; err: unknown; ctx?: CaptureContext }
   | { kind: "message"; message: string; level?: "info" | "warning" | "error"; ctx?: CaptureContext };
 
+// Inlined to avoid a tooling → core import (boundary rule). Mirrors the
+// implementation in @repo/core-shared/instrumentation/reported-flag.ts.
+const REPORTED = "__sentryReported" as const;
+
+function isReported(err: unknown): boolean {
+  return (
+    err !== null &&
+    typeof err === "object" &&
+    Boolean((err as Record<string, unknown>)[REPORTED])
+  );
+}
+
+function markReported(err: unknown): void {
+  if (err !== null && typeof err === "object" && !isReported(err)) {
+    Object.defineProperty(err, REPORTED, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+}
+
 export class RecordingLogger implements ILogger {
   captures: RecordedCapture[] = [];
   breadcrumbs: Breadcrumb[] = [];
   users: Array<{ id: string } | null> = [];
 
   captureException(err: unknown, ctx?: CaptureContext): void {
+    if (isReported(err)) return;
     this.captures.push({ kind: "exception", err, ctx });
+    markReported(err);
   }
 
   captureMessage(

packages/marketing-pages/src/di/bind-dev-seed.ts

@@ -1,5 +1,6 @@
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -62,12 +63,20 @@ export async function bindDevSeedMarketingPages(tracer: ITracer, logger: ILogger
   const wrappedGetSiteSettings = withSpan(
     tracer,
     { name: "marketing-pages.getSiteSettings", op: "use-case" },
-    getSiteSettingsUseCase(siteSettingsRepo),
+    withCapture(
+      logger,
+      { feature: "marketing-pages", layer: "use-case", name: "marketing-pages.getSiteSettings" },
+      getSiteSettingsUseCase(siteSettingsRepo),
+    ),
   );
   const wrappedGetPageBySlug = withSpan(
     tracer,
     { name: "marketing-pages.getPageBySlug", op: "use-case" },
-    getPageBySlugUseCase(pagesRepo),
+    withCapture(
+      logger,
+      { feature: "marketing-pages", layer: "use-case", name: "marketing-pages.getPageBySlug" },
+      getPageBySlugUseCase(pagesRepo),
+    ),
   );
 
   for (const sym of [
@@ -91,7 +100,11 @@ export async function bindDevSeedMarketingPages(tracer: ITracer, logger: ILogger
       withSpan(
         tracer,
         { name: "marketing-pages.getSiteSettings", op: "controller" },
-        getSiteSettingsController(wrappedGetSiteSettings),
+        withCapture(
+          logger,
+          { feature: "marketing-pages", layer: "controller", name: "marketing-pages.getSiteSettings" },
+          getSiteSettingsController(wrappedGetSiteSettings),
+        ),
       ),
     );
   marketingPagesContainer
@@ -100,7 +113,11 @@ export async function bindDevSeedMarketingPages(tracer: ITracer, logger: ILogger
       withSpan(
         tracer,
         { name: "marketing-pages.getPageBySlug", op: "controller" },
-        getPageBySlugController(wrappedGetPageBySlug),
+        withCapture(
+          logger,
+          { feature: "marketing-pages", layer: "controller", name: "marketing-pages.getPageBySlug" },
+          getPageBySlugController(wrappedGetPageBySlug),
+        ),
       ),
     );
 }

packages/marketing-pages/src/di/bind-production.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from "payload";
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -46,16 +47,24 @@ export function bindProductionMarketingPages(
     .bind(MARKETING_PAGES_SYMBOLS.ISiteSettingsRepository)
     .toConstantValue(siteSettingsRepo);
 
-  // Use cases — wrapped with span at bind time
+  // Use cases — wrapped with span + capture at bind time
   const wrappedGetSiteSettings = withSpan(
     tracer,
     { name: "marketing-pages.getSiteSettings", op: "use-case" },
-    getSiteSettingsUseCase(siteSettingsRepo),
+    withCapture(
+      logger,
+      { feature: "marketing-pages", layer: "use-case", name: "marketing-pages.getSiteSettings" },
+      getSiteSettingsUseCase(siteSettingsRepo),
+    ),
   );
   const wrappedGetPageBySlug = withSpan(
     tracer,
     { name: "marketing-pages.getPageBySlug", op: "use-case" },
-    getPageBySlugUseCase(pagesRepo),
+    withCapture(
+      logger,
+      { feature: "marketing-pages", layer: "use-case", name: "marketing-pages.getPageBySlug" },
+      getPageBySlugUseCase(pagesRepo),
+    ),
   );
 
   for (const sym of [
@@ -84,7 +93,11 @@ export function bindProductionMarketingPages(
       withSpan(
         tracer,
         { name: "marketing-pages.getSiteSettings", op: "controller" },
-        getSiteSettingsController(wrappedGetSiteSettings),
+        withCapture(
+          logger,
+          { feature: "marketing-pages", layer: "controller", name: "marketing-pages.getSiteSettings" },
+          getSiteSettingsController(wrappedGetSiteSettings),
+        ),
       ),
     );
   marketingPagesContainer
@@ -93,7 +106,11 @@ export function bindProductionMarketingPages(
       withSpan(
         tracer,
         { name: "marketing-pages.getPageBySlug", op: "controller" },
-        getPageBySlugController(wrappedGetPageBySlug),
+        withCapture(
+          logger,
+          { feature: "marketing-pages", layer: "controller", name: "marketing-pages.getPageBySlug" },
+          getPageBySlugController(wrappedGetPageBySlug),
+        ),
       ),
     );
 }

packages/media/src/di/bind-dev-seed.ts

@@ -1,5 +1,6 @@
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -54,17 +55,29 @@ export async function bindDevSeedMedia(tracer: ITracer, logger: ILogger): Promis
   const wrappedGetMedia = withSpan(
     tracer,
     { name: "media.getMedia", op: "use-case" },
-    getMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.getMedia" },
+      getMediaUseCase(repo),
+    ),
   );
   const wrappedListMedia = withSpan(
     tracer,
     { name: "media.listMedia", op: "use-case" },
-    listMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.listMedia" },
+      listMediaUseCase(repo),
+    ),
   );
   const wrappedDeleteMedia = withSpan(
     tracer,
     { name: "media.deleteMedia", op: "use-case" },
-    deleteMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.deleteMedia" },
+      deleteMediaUseCase(repo),
+    ),
   );
 
   for (const sym of [
@@ -87,7 +100,11 @@ export async function bindDevSeedMedia(tracer: ITracer, logger: ILogger): Promis
       withSpan(
         tracer,
         { name: "media.getMedia", op: "controller" },
-        getMediaController(wrappedGetMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.getMedia" },
+          getMediaController(wrappedGetMedia),
+        ),
       ),
     );
   mediaContainer
@@ -96,7 +113,11 @@ export async function bindDevSeedMedia(tracer: ITracer, logger: ILogger): Promis
       withSpan(
         tracer,
         { name: "media.listMedia", op: "controller" },
-        listMediaController(wrappedListMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.listMedia" },
+          listMediaController(wrappedListMedia),
+        ),
       ),
     );
   mediaContainer
@@ -105,7 +126,11 @@ export async function bindDevSeedMedia(tracer: ITracer, logger: ILogger): Promis
       withSpan(
         tracer,
         { name: "media.deleteMedia", op: "controller" },
-        deleteMediaController(wrappedDeleteMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.deleteMedia" },
+          deleteMediaController(wrappedDeleteMedia),
+        ),
       ),
     );
 }

packages/media/src/di/bind-production.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from "payload";
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -39,21 +40,33 @@ export function bindProductionMedia(
     .bind(MEDIA_SYMBOLS.IMediaRepository)
     .toConstantValue(repo);
 
-  // Use cases — wrapped with span at bind time
+  // Use cases — wrapped with span + capture at bind time
   const wrappedGetMedia = withSpan(
     tracer,
     { name: "media.getMedia", op: "use-case" },
-    getMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.getMedia" },
+      getMediaUseCase(repo),
+    ),
   );
   const wrappedListMedia = withSpan(
     tracer,
     { name: "media.listMedia", op: "use-case" },
-    listMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.listMedia" },
+      listMediaUseCase(repo),
+    ),
   );
   const wrappedDeleteMedia = withSpan(
     tracer,
     { name: "media.deleteMedia", op: "use-case" },
-    deleteMediaUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "media", layer: "use-case", name: "media.deleteMedia" },
+      deleteMediaUseCase(repo),
+    ),
   );
 
   for (const sym of [
@@ -81,7 +94,11 @@ export function bindProductionMedia(
       withSpan(
         tracer,
         { name: "media.getMedia", op: "controller" },
-        getMediaController(wrappedGetMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.getMedia" },
+          getMediaController(wrappedGetMedia),
+        ),
       ),
     );
   mediaContainer
@@ -90,7 +107,11 @@ export function bindProductionMedia(
       withSpan(
         tracer,
         { name: "media.listMedia", op: "controller" },
-        listMediaController(wrappedListMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.listMedia" },
+          listMediaController(wrappedListMedia),
+        ),
       ),
     );
   mediaContainer
@@ -99,7 +120,11 @@ export function bindProductionMedia(
       withSpan(
         tracer,
         { name: "media.deleteMedia", op: "controller" },
-        deleteMediaController(wrappedDeleteMedia),
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.deleteMedia" },
+          deleteMediaController(wrappedDeleteMedia),
+        ),
       ),
     );
 }

packages/navigation/src/di/bind-dev-seed.ts

@@ -1,5 +1,6 @@
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -46,7 +47,11 @@ export async function bindDevSeedNavigation(tracer: ITracer, logger: ILogger): P
   const wrappedGetHeader = withSpan(
     tracer,
     { name: "navigation.getHeader", op: "use-case" },
-    getHeaderUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "navigation", layer: "use-case", name: "navigation.getHeader" },
+      getHeaderUseCase(repo),
+    ),
   );
 
   for (const sym of [
@@ -65,7 +70,11 @@ export async function bindDevSeedNavigation(tracer: ITracer, logger: ILogger): P
       withSpan(
         tracer,
         { name: "navigation.getHeader", op: "controller" },
-        getHeaderController(wrappedGetHeader),
+        withCapture(
+          logger,
+          { feature: "navigation", layer: "controller", name: "navigation.getHeader" },
+          getHeaderController(wrappedGetHeader),
+        ),
       ),
     );
 }

packages/navigation/src/di/bind-production.ts

@@ -1,6 +1,7 @@
 import type { SanitizedConfig } from "payload";
 import {
   withSpan,
+  withCapture,
   INSTRUMENTATION_SYMBOLS,
   type ITracer,
   type ILogger,
@@ -35,11 +36,15 @@ export function bindProductionNavigation(
     .bind(NAVIGATION_SYMBOLS.IHeaderRepository)
     .toConstantValue(repo);
 
-  // Use case — wrapped with span at bind time
+  // Use case — wrapped with span + capture at bind time
   const wrappedGetHeader = withSpan(
     tracer,
     { name: "navigation.getHeader", op: "use-case" },
-    getHeaderUseCase(repo),
+    withCapture(
+      logger,
+      { feature: "navigation", layer: "use-case", name: "navigation.getHeader" },
+      getHeaderUseCase(repo),
+    ),
   );
 
   if (navigationContainer.isBound(NAVIGATION_SYMBOLS.IGetHeaderUseCase)) {
@@ -59,7 +64,11 @@ export function bindProductionNavigation(
       withSpan(
         tracer,
         { name: "navigation.getHeader", op: "controller" },
-        getHeaderController(wrappedGetHeader),
+        withCapture(
+          logger,
+          { feature: "navigation", layer: "controller", name: "navigation.getHeader" },
+          getHeaderController(wrappedGetHeader),
+        ),
       ),
     );
 }