feat(observability): route eval scores through ScoreEvent bus (#16185)

## Description

Wires Mastra eval scores through the unified observability bus so every
exporter implementing `onScoreEvent` automatically receives them.
Replaces the deprecated per-exporter `addScoreToTrace` side-channel that
bypassed the pipeline. Also unblocks Mastra spans appearing under
Braintrust experiment eval spans (#11097) as a side effect of the
unified path.

- Producer alignment: `packages/core/src/mastra/hooks.ts` no longer
iterates exporters with `addScoreToTrace`. `MastraScorer.run()` (already
on main from PR #14920) remains the single producer of `ScoreEvent`s
through `mastra.observability.addScore()`.
- Consumer side: implemented `onScoreEvent` on Langfuse
(`LangfuseClient.score.create`), Laminar (`/v1/evaluators/score`),
Braintrust (`logger.logFeedback`), Datadog
(`tracer.llmobs.submitEvaluation`), and LangSmith
(`Client.createFeedback`).
- Backwards compatibility: Langfuse `addScoreToTrace` and Laminar
`_addScoreToTrace` are preserved as `@deprecated` wrappers that forward
to a shared private `submitScore` helper.
- Bug fix in `observability/mastra/src/recorded.ts`: `buildScoreEvent`
now forwards `scorerName` and `targetEntityType` from `ScoreInput` to
`ExportedScore` (without this, exporters silently fell back to
`scorerId`).
- Tests: rewrote core hook test to assert the hook no longer publishes a
`ScoreEvent`; added per-exporter `onScoreEvent` tests; added a
regression test for `buildScoreEvent` field forwarding.
- Seven single-package changesets created (`@mastra/core`,
`@mastra/observability`, `@mastra/langfuse`, `@mastra/laminar`,
`@mastra/braintrust`, `@mastra/datadog`, `@mastra/langsmith`) per the
project's changeset style guide.

## Related Issue(s)

Fixes #10896 (also unblocks #11097)

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

When Mastra assigns an evaluation score, this PR sends that score
exactly once into a single observability "bus" so all
monitoring/exporter integrations (Langfuse, Laminar, Braintrust,
Datadog, LangSmith, etc.) automatically receive it — avoiding
exporter-specific wiring and duplicate deliveries.

## Overview

Routes Mastra evaluation scores through the unified observability
ScoreEvent bus (mastra.observability.addScore) so any exporter
implementing onScoreEvent receives them. MastraScorer.run() remains the
single producer of ScoreEvent; the core scorer hook no longer iterates
exporters to call addScoreToTrace. Per-exporter
addScoreToTrace/_addScoreToTrace behaviors are preserved as @deprecated
wrappers that forward to shared submit helpers where applicable. Fixes a
bug in buildScoreEvent so scorerName and targetEntityType from
ScoreInput are forwarded into emitted ExportedScore.

## Changes by Component

### Core (@mastra/core)
- Removed exporter-iteration and addScoreToTrace republishing from
createOnScorerHook; the hook now only persists scores to the legacy
scores store.
- Ensures MastraScorer.run() is the single producer of ScoreEvent.
- Registers static workflow-step scorers synchronously during
addWorkflow and resolves dynamic scorers asynchronously so scorers are
registered before use.
- Updated core test to assert the hook does not emit ScoreEvent.

### Observability (@mastra/observability)
- Fix: buildScoreEvent (observability/mastra/src/recorded.ts) now
includes scorerName and targetEntityType in emitted ScoreEvent.
- Bus routing: route-event now prefers onScoreEvent; if an exporter
lacks onScoreEvent but implements deprecated addScoreToTrace, the bus
maps the ScoreEvent into the legacy addScoreToTrace payload and calls it
(avoids duplicate delivery when both exist).
- Added unit tests for score routing behavior and the buildScoreEvent
regression.

### Exporter Integrations (new onScoreEvent handlers + tests)
- Langfuse (@mastra/langfuse)
- Added onScoreEvent → LangfuseClient.score.create with a shared
submitScore helper and centralized error logging.
- Preserved addScoreToTrace as a deprecated wrapper forwarding to
submitScore.
- Tests updated to cover onScoreEvent and mark addScoreToTrace
deprecated.

- Laminar (@mastra/laminar)
- Added onScoreEvent delegating to a private submitScore that POSTS to
/v1/evaluators/score.
- submitScore converts trace/span IDs to Laminar/OTel UUIDs, merges
metadata/reason, enforces timeouts via AbortController, and logs
non-OK/timed-out responses.
- Preserved _addScoreToTrace as a @deprecated wrapper forwarding to
submitScore.
  - Tests verify POST payload mapping and wrapper behavior.

- Braintrust (@mastra/braintrust)
- Added onScoreEvent that calls logger.logFeedback using spanId (falling
back to traceId) and skips when neither is present.
- Maps scorer name/ID, reason, and metadata into the feedback payload
and logs failures.
  - Tests cover span/trace fallback and skip behavior.

- Datadog (@mastra/datadog)
- Added onScoreEvent: validates traceId/spanId, looks up exported
dd-trace span context (traceState), and calls
tracer.llmobs.submitEvaluation with mapped fields
(label/value/metricType/mlApp/timestamp/reason/metadata).
- Drops scores when identifiers or exported span context are missing and
warns when scores arrive before the span is exported.
- Tests cover successful submission, unknown IDs (no-op), and dropping
out-of-order scores.

- LangSmith (@mastra/langsmith)
- Added onScoreEvent that submits Client.createFeedback when a
spanId→LangSmith runId mapping exists.
- Introduced a configurable bounded LRU spanId→runId cache
(runIdCacheMaxEntries) populated from RunTree building; evicts oldest
entries when full and is cleared on shutdown.
- Ensures authoritative scorerId/scoreSource are preserved in sourceInfo
and ignores events when span/run mapping is absent.
- Tests cover mapping semantics, eviction, metadata protection, and
skipping unseen spans.

## Tests

- Core hook test rewritten to assert the hook does not publish
ScoreEvent.
- Per-exporter onScoreEvent test suites added for Langfuse, Laminar,
Braintrust, Datadog, and LangSmith covering field mapping, identifier
fallbacks, ordering/dropping, timeout handling, and cache eviction.
- Bus tests added to assert onScoreEvent preferred and legacy
addScoreToTrace fallback behavior.
- Regression test added to ensure buildScoreEvent forwards scorerName
and targetEntityType.

## Backwards Compatibility

- Deprecated addScoreToTrace/_addScoreToTrace preserved (where present)
as wrappers that forward to the new onScoreEvent/submit helpers to avoid
breaking existing callers.
- Observability interface docs updated to deprecate addScoreToTrace in
favor of onScoreEvent/ScoreEvent bus.
- No breaking public API surface changes beyond documented additions and
deprecations.

## Commits & Release Notes

- Seven package-scoped changesets created for @mastra/core,
@mastra/observability, @mastra/langfuse, @mastra/laminar,
@mastra/langsmith, @mastra/datadog, and @mastra/braintrust documenting
onScoreEvent support and the buildScoreEvent fix.
- Exporter-specific notes documented (Datadog ordering caveat; Laminar
timeout/error logging; LangSmith runId cache behavior).

## Related Issues

Fixes #10896 and unblocks #11097.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: intojhanurag

.changeset/dark-rooms-build.md

@@ -0,0 +1,5 @@
+---
+'@mastra/langfuse': minor
+---
+
+Mastra Eval results are now forwarded to Langfuse.

.changeset/five-stars-smile.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': minor
+---
+
+Mastra Eval results are now emitted once through the unified observability score pipeline.

.changeset/giant-apes-accept.md

@@ -0,0 +1,5 @@
+---
+'@mastra/langsmith': minor
+---
+
+Mastra Eval results are now forwarded to LangSmith.

.changeset/large-yaks-battle.md

@@ -0,0 +1,5 @@
+---
+'@mastra/laminar': minor
+---
+
+Mastra Eval results are now forwarded to Laminar.

.changeset/ready-socks-leave.md

@@ -0,0 +1,5 @@
+---
+'@mastra/observability': patch
+---
+
+Score events now include scorer names and target entity types.

.changeset/tiny-doodles-hang.md

@@ -0,0 +1,5 @@
+---
+'@mastra/braintrust': minor
+---
+
+Mastra Eval results are now forwarded to Braintrust.

.changeset/violet-rules-design.md

@@ -0,0 +1,5 @@
+---
+'@mastra/datadog': minor
+---
+
+Mastra Eval results are now forwarded to Datadog.

docs/src/content/en/reference/observability/tracing/interfaces.mdx

@@ -156,7 +156,12 @@ interface ObservabilityExporter {
   /** Export tracing events */
   exportTracingEvent(event: TracingEvent): Promise<void>
 
-  /** Add score to a trace (optional) */
+  /**
+   * @deprecated Implement `onScoreEvent` instead. Eval scores now flow through the
+   * unified observability bus as `ScoreEvent`s. This method is preserved on the
+   * interface for backwards compatibility with existing exporters; new exporters
+   * should not implement it.
+   */
   addScoreToTrace?({
     traceId,
     spanId,

observability/braintrust/src/tracing.test.ts

@@ -2182,6 +2182,61 @@ describe('BraintrustExporter', () => {
       expect(mockSpan.end).toHaveBeenCalledTimes(3);
     });
   });
+
+  describe('onScoreEvent', () => {
+    const baseScore = {
+      scoreId: 'score-1',
+      timestamp: new Date(),
+      traceId: 'trace-1',
+      spanId: 'span-1',
+      scorerId: 'accuracy',
+      scorerName: 'Accuracy',
+      scoreSource: 'live',
+      score: 0.9,
+      reason: 'good',
+      metadata: { sessionId: 's-1' },
+    };
+
+    it('forwards score events to logger.logFeedback keyed by spanId', async () => {
+      mockLogger.logFeedback = vi.fn();
+      mockInitLogger.mockResolvedValue(mockLogger);
+
+      await exporter.onScoreEvent({ type: 'score', score: { ...baseScore } } as any);
+
+      expect(mockLogger.logFeedback).toHaveBeenCalledTimes(1);
+      const arg = mockLogger.logFeedback.mock.calls[0][0];
+      expect(arg).toMatchObject({
+        id: 'span-1',
+        scores: { Accuracy: 0.9 },
+        comment: 'good',
+        source: 'external',
+      });
+      expect(arg.metadata).toMatchObject({ scorerId: 'accuracy', scoreSource: 'live', sessionId: 's-1' });
+    });
+
+    it('falls back to traceId when spanId is missing', async () => {
+      mockLogger.logFeedback = vi.fn();
+      mockInitLogger.mockResolvedValue(mockLogger);
+
+      await exporter.onScoreEvent({
+        type: 'score',
+        score: { ...baseScore, spanId: undefined },
+      } as any);
+
+      expect(mockLogger.logFeedback).toHaveBeenCalledWith(expect.objectContaining({ id: 'trace-1' }));
+    });
+
+    it('skips when both spanId and traceId are missing', async () => {
+      mockLogger.logFeedback = vi.fn();
+
+      await exporter.onScoreEvent({
+        type: 'score',
+        score: { ...baseScore, spanId: undefined, traceId: undefined },
+      } as any);
+
+      expect(mockLogger.logFeedback).not.toHaveBeenCalled();
+    });
+  });
 });
 
 // ==============================================================================

observability/braintrust/src/tracing.ts

@@ -6,7 +6,7 @@
  * Events are handled as zero-duration spans with matching start/end times.
  */
 
-import type { AnyExportedSpan, ModelGenerationAttributes, SpanErrorInfo } from '@mastra/core/observability';
+import type { AnyExportedSpan, ModelGenerationAttributes, ScoreEvent, SpanErrorInfo } from '@mastra/core/observability';
 import { SpanType } from '@mastra/core/observability';
 import { omitKeys } from '@mastra/core/utils';
 import { TrackingExporter } from '@mastra/observability';
@@ -134,6 +134,45 @@ export class BraintrustExporter extends TrackingExporter<
     }
   }
 
+  async onScoreEvent(event: ScoreEvent): Promise<void> {
+    if (this.isDisabled) return;
+
+    const { score } = event;
+    const rowId = score.spanId ?? score.traceId;
+    if (!rowId) {
+      this.logger.debug('Braintrust exporter: skipping score with no spanId or traceId', {
+        scorerId: score.scorerId,
+      });
+      return;
+    }
+
+    const logger = this.#useProvidedLogger ? this.#providedLogger : await this.getLocalLogger();
+    if (!logger) return;
+
+    const name = score.scorerName ?? score.scorerId;
+
+    try {
+      logger.logFeedback({
+        id: rowId,
+        scores: { [name]: score.score },
+        ...(score.reason ? { comment: score.reason } : {}),
+        metadata: {
+          scorerId: score.scorerId,
+          ...(score.scoreSource ? { scoreSource: score.scoreSource } : {}),
+          ...(score.metadata ?? {}),
+        },
+        source: 'external',
+      });
+    } catch (err) {
+      this.logger.error('Braintrust exporter: Failed to submit score', {
+        error: err,
+        traceId: score.traceId,
+        spanId: score.spanId,
+        scorerId: score.scorerId,
+      });
+    }
+  }
+
   private startSpan(args: { parent: Span | Logger<true>; span: AnyExportedSpan }): BraintrustSpanData {
     const { parent, span } = args;
     const payload = this.buildSpanPayload(span);