Reviewing files that changed from the base of the PR and between 32ac485 and d6a6c11.

• packages/client/tests/e2e/sqlcommenter-query-tags/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
• packages/client/tests/e2e/sqlcommenter-trace-context/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
• packages/client/tests/e2e/sqlcommenter/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

• .github/workflows/test-template.yml (3 hunks)
• packages/client/package.json (1 hunks)
• packages/client/src/runtime/core/engines/accelerate/HeaderBuilder.ts (1 hunks)
• packages/client/src/runtime/core/engines/client/ClientEngine.ts (1 hunks)
• packages/client/src/runtime/core/engines/client/RemoteExecutor.ts (1 hunks)
• packages/client/src/runtime/core/engines/common/Engine.ts (1 hunks)
• packages/client/src/runtime/core/engines/common/types/QueryEngine.ts (1 hunks)
• packages/client/src/runtime/core/tracing/TracingHelper.test.ts (3 hunks)
• packages/client/src/runtime/core/tracing/TracingHelper.ts (2 hunks)
• packages/client/src/runtime/getPrismaClient.ts (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/_steps.cts (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/package.json (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/prisma.config.ts (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/prisma/schema.prisma (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/readme.md (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/src/index.ts (1 hunks)
• packages/client/tests/e2e/sqlcommenter-trace-context/tsconfig.json (1 hunks)
• packages/client/tests/functional/0-legacy-ports/batch-find-unique/tests.ts (1 hunks)
• packages/client/tests/functional/tracing-no-sampling/tests.ts (2 hunks)
• packages/instrumentation-contract/README.md (1 hunks)
• packages/instrumentation-contract/helpers/build.ts (1 hunks)
• packages/instrumentation-contract/package.json (1 hunks)
• packages/instrumentation-contract/src/global.test.ts (1 hunks)
• packages/instrumentation-contract/src/global.ts (1 hunks)
• packages/instrumentation-contract/src/index.ts (1 hunks)
• packages/instrumentation-contract/src/types.ts (4 hunks)
• packages/instrumentation-contract/tsconfig.build.json (1 hunks)
• packages/instrumentation-contract/tsconfig.json (1 hunks)
• packages/instrumentation/package.json (1 hunks)
• packages/instrumentation/src/ActiveTracingHelper.ts (1 hunks)
• packages/instrumentation/src/PrismaInstrumentation.test.ts (1 hunks)
• packages/instrumentation/src/PrismaInstrumentation.ts (2 hunks)
• packages/instrumentation/src/__tests__/PrismaInstrumentation.test.ts (0 hunks)
• packages/instrumentation/src/constants.ts (0 hunks)
• packages/instrumentation/tsconfig.build.json (1 hunks)
• packages/internals/src/index.ts (0 hunks)
• packages/sqlcommenter-trace-context/README.md (1 hunks)
• packages/sqlcommenter-trace-context/helpers/build.ts (1 hunks)
• packages/sqlcommenter-trace-context/package.json (1 hunks)
• packages/sqlcommenter-trace-context/src/index.test.ts (1 hunks)
• packages/sqlcommenter-trace-context/src/index.ts (1 hunks)
• packages/sqlcommenter-trace-context/tsconfig.build.json (1 hunks)
• packages/sqlcommenter-trace-context/tsconfig.json (1 hunks)
• packages/sqlcommenter/README.md (1 hunks)
• tsconfig.build.bundle.json (2 hunks)

• packages/internals/src/index.ts
• packages/instrumentation/src/tests/PrismaInstrumentation.test.ts
• packages/instrumentation/src/constants.ts

packages/client/tests/functional/0-legacy-ports/batch-find-unique/tests.ts (1)

73-73: LGTM! Simplified query processing aligns with opt-in traceparent approach.

The removal of traceparent comment stripping is correct since queries no longer include these comments by default. This simplifies the test and aligns with the PR's objective of making trace context opt-in via the new SQL commenter plugin.

packages/sqlcommenter-trace-context/tsconfig.json (1)

1-4: No action required—all TypeScript configuration files are properly in place and configured.

This package includes both tsconfig.json and the required companion tsconfig.build.json, following the standard pattern used across the monorepo. The root tsconfig.build.bundle.json has already been updated with the correct resolution path for @prisma/sqlcommenter-trace-context pointing to ./packages/sqlcommenter-trace-context/src. The configuration is complete and correct.

Likely an incorrect or invalid review comment.

packages/client/tests/e2e/sqlcommenter-trace-context/prisma/schema.prisma (1)

1-14: LGTM!

The schema is well-structured for e2e testing purposes. The SQLite datasource without an inline url is appropriate since it's configured via prisma.config.ts in the same directory.

packages/instrumentation-contract/tsconfig.json (1)

1-4: LGTM!

Standard tsconfig for a new package, correctly extending the root configuration. Based on learnings, this satisfies the requirement for new packages to include tsconfig.json.

packages/sqlcommenter-trace-context/tsconfig.build.json (1)

1-8: LGTM!

Build configuration follows the monorepo conventions: extends the regular build config, outputs to dist, and properly excludes test files. Based on learnings, this satisfies the requirement for new packages to include tsconfig.build.json.

packages/instrumentation/tsconfig.build.json (1)

6-7: LGTM!

Adding the test exclusion pattern aligns this package with the monorepo convention and ensures .test.ts files are not included in the build output.

packages/instrumentation-contract/tsconfig.build.json (1)

1-8: LGTM!

Build configuration follows monorepo conventions correctly. Based on learnings, this satisfies the requirement for new packages to include tsconfig.build.json.

packages/sqlcommenter-trace-context/helpers/build.ts (1)

1-4: LGTM!

Build script correctly uses adapterConfig from helpers/compile/configs.ts for bundling to both CJS and ESM with type declarations. As per coding guidelines, this is the recommended approach for packages like this.

packages/instrumentation-contract/helpers/build.ts (1)

1-14: LGTM!

The custom build configuration is appropriate here since the package needs @opentelemetry/api as an external dependency, which isn't easily supported by adapterConfig. The dual-output approach (CJS with types, ESM) provides broad compatibility. The use of satisfies BuildOptions ensures type safety.

packages/instrumentation-contract/package.json (2)

3-3: Verify version before publishing.

The package version is set to 0.0.0. Ensure this is updated to an appropriate version number before publishing to npm.

---

39-44: Peer dependency range is appropriate.

The package only imports basic types (Context, Span, SpanOptions) from @opentelemetry/api, all of which have been stable since 1.8. The 1.9.0 version used in devDependencies introduces features like the synchronous Gauge instrument and post-creation span links, neither of which are used here. The ^1.8 peer dependency range is correct and does not need to be updated.

packages/sqlcommenter-trace-context/package.json (1)

3-3: Verify version before publishing.

The package version is set to 0.0.0. Ensure this is updated to an appropriate version number before publishing to npm.

packages/sqlcommenter-trace-context/README.md (1)

1-68: LGTM! Clear and comprehensive documentation.

The README provides excellent documentation for the plugin, including:

• Clear installation and usage instructions
• Helpful examples showing SQL output
• Detailed explanation of when the traceparent is added
• W3C Trace Context specification reference
• Requirements and licensing information

packages/client/src/runtime/core/engines/accelerate/HeaderBuilder.ts (1)

3-3: LGTM! Type import updated to instrumentation-contract.

The import source for TracingHelper has been correctly updated from @prisma/internals to @prisma/instrumentation-contract. This is a type-only import with no runtime behavior changes, aligning with the PR's refactoring to centralize tracing types.

packages/client/tests/e2e/sqlcommenter-trace-context/tsconfig.json (1)

1-9: LGTM! Appropriate TypeScript configuration for e2e tests.

The tsconfig correctly:

• Extends the base configuration
• Excludes the test steps file (_steps.cts) from compilation
• Uses modern module resolution (NodeNext) suitable for Node.js environments

packages/client/src/runtime/core/engines/client/RemoteExecutor.ts (1)

5-5: LGTM! Type imports updated to instrumentation-contract.

The import source for EngineTraceEvent and TracingHelper has been correctly updated from @prisma/internals to @prisma/instrumentation-contract. This is a type-only import with no runtime behavior changes, consistent with the broader refactoring in this PR.

packages/client/src/runtime/core/engines/client/ClientEngine.ts (1)

20-21: LGTM! Type and runtime imports correctly separated.

The changes correctly:

• Import TracingHelper as a type-only symbol from @prisma/instrumentation-contract
• Keep assertNever as a runtime import from @prisma/internals (used at line 435)

This separation aligns with the PR's refactoring to centralize tracing types while maintaining runtime dependencies where needed.

packages/client/tests/e2e/sqlcommenter-trace-context/prisma.config.ts (1)

1-7: LGTM! Appropriate test configuration.

The Prisma config correctly sets up a SQLite database for e2e tests, which is suitable for testing without requiring external database infrastructure. The configuration structure follows the expected pattern for Prisma config files.

packages/instrumentation/package.json (1)

30-30: LGTM! Dependency update aligns with new contract package.

The devDependency change from @prisma/internals to @prisma/instrumentation-contract correctly reflects the refactoring to use the new contract package for tracing types.

packages/client/src/runtime/core/engines/common/types/QueryEngine.ts (1)

2-2: LGTM! Type-only import correctly sources types from contract package.

The migration to type-only imports from @prisma/instrumentation-contract is appropriate since EngineSpan and EngineTraceEvent are only used in type positions within this file.

packages/instrumentation-contract/src/global.test.ts (1)

1-89: LGTM! Comprehensive test coverage for global tracing helper API.

The test suite thoroughly validates all aspects of the global tracing helper management:

• Initial undefined state
• Set and retrieve operations
• Helper replacement
• Cleanup operations
• Safe handling of no-op scenarios

The use of beforeEach and afterEach for cleanup ensures test isolation.

tsconfig.build.bundle.json (1)

28-28: LGTM! Path aliases correctly configured for new packages.

The path mappings for @prisma/instrumentation-contract and @prisma/sqlcommenter-trace-context are properly configured, enabling editor go-to-definition support for the new workspace packages.

Based on coding guidelines, this update to tsconfig.build.bundle.json is required for new workspace packages.

Also applies to: 38-38

packages/client/src/runtime/getPrismaClient.ts (1)

6-7: LGTM! Type-only imports correctly separated from runtime imports.

The refactoring appropriately:

• Imports ExtendedSpanOptions and TracingHelper as type-only from @prisma/instrumentation-contract
• Preserves runtime import of logger from @prisma/internals (used at Line 402)

This separation ensures no unnecessary runtime dependencies while maintaining type information.

packages/client/tests/functional/tracing-no-sampling/tests.ts (1)

13-13: LGTM! Test correctly validates opt-in trace context behavior.

The addition of traceContext() in the comments option validates that:

• The new plugin is properly integrated
• With 0% sampling, no traceparent is added to queries (as verified by the test assertions)
• The opt-in nature of the feature is preserved

The test setup correctly exercises the new SQL commenter trace context functionality.

Also applies to: 64-67

packages/instrumentation/src/ActiveTracingHelper.ts (1)

12-18: LGTM! Type-only imports correctly source from contract package.

The migration to type-only imports from @prisma/instrumentation-contract is appropriate, as all imported types (EngineSpan, EngineSpanKind, ExtendedSpanOptions, SpanCallback, TracingHelper) are used only in type positions and interface implementations.

packages/instrumentation/src/PrismaInstrumentation.test.ts (1)

1-41: LGTM! Comprehensive test coverage for instrumentation lifecycle.

The test suite effectively validates:

• Initial state (no global helper)
• Automatic enabling behavior (with helpful comment about upstream dependency)
• Explicit enable/disable operations
• Correct isEnabled() state tracking
• Integration with global tracing helper API from the contract package

The beforeEach hook ensures proper test isolation by clearing the global state.

packages/instrumentation-contract/README.md (1)

1-113: README matches the tracing contract; keep it in sync with types.

The documented TracingHelper interface and global helper functions align with the described contract and expected usage; just ensure this stays updated if types.ts evolves.

.github/workflows/test-template.yml (1)

935-938: CI wiring for new packages looks consistent.

Adding pnpm run test for instrumentation-contract and sqlcommenter-trace-context in both others and no-docker jobs, with the same if guards and patterns as neighboring steps, is consistent and should give good coverage across platforms.

Also applies to: 963-966, 1331-1335, 1341-1345

packages/client/tests/e2e/sqlcommenter-trace-context/_steps.cts (1)

1-20: E2E step orchestration is sound and idiomatic.

The setup/test/finish flow matches existing client e2e patterns (install → generate → db push → run scenario → typecheck) and uses zx correctly with executeSteps.

packages/instrumentation-contract/src/index.ts (1)

1-2: Public entrypoint re-exports are appropriate.

Re-exporting ./global and ./types from the package root gives consumers a single import path without leaking internals; looks good.

packages/client/src/runtime/core/engines/common/Engine.ts (1)

4-4: TracingHelper import migration to instrumentation-contract looks correct.

Switching to import type { TracingHelper } from '@prisma/instrumentation-contract' keeps the EngineConfig.tracingHelper API surface unchanged while aligning with the new shared tracing contract and avoiding extra runtime deps from this file.

packages/client/tests/e2e/sqlcommenter-trace-context/package.json (1)

1-29: E2E test package manifest is consistent with existing patterns.

The manifest (private package, /tmp Prisma tarballs, OTel deps, and onlyBuiltDependencies: ["better-sqlite3"]) matches the standard setup for client e2e scenarios and should work fine with the new _steps.cts flow.

packages/client/tests/e2e/sqlcommenter-trace-context/src/index.ts (3)

81-131: Test 2 executes query outside of an active span, unlike Test 1.

In Test 1 (lines 55-60), the query runs inside tracer.startActiveSpan(), but Test 2 (line 117) runs prisma.user.findMany() directly without an active span. This means Test 2 tests a different scenario than expected - it's testing "no active span context" rather than "active span with 0% sampling".

If the intent is to verify that unsampled spans don't produce traceparent comments, the query should also run within an active span:

-  await prisma.user.findMany()
+  const tracer = tracerProvider.getTracer('test')
+  await tracer.startActiveSpan('test-operation', async (span) => {
+    await prisma.user.findMany()
+    span.end()
+  })

However, if the current behavior is intentional (testing that without an active sampled span no traceparent is added), consider updating the test description to clarify this.

---

19-79: LGTM! Test 1 correctly validates traceparent presence with sampling.

The test properly:

• Sets up OpenTelemetry with 100% sampling
• Registers Prisma instrumentation
• Captures queries via event listener
• Validates the traceparent format matches W3C spec with sampled flag 01
• Performs cleanup of instrumentation and tracing globals

---

133-161: LGTM! Test 3 validates behavior without tracing configuration.

The test correctly verifies that when no tracing infrastructure is configured, the traceContext() plugin does not inject traceparent comments.

packages/sqlcommenter-trace-context/src/index.ts (2)

12-30: LGTM! Robust traceparent parsing with proper validation.

The isSampled() function correctly:

• Validates the 4-part W3C traceparent structure
• Checks trace-flags length (2 hex chars)
• Handles invalid hex parsing with isNaN check
• Uses bitwise AND to check the sampled flag (0x01)

---

56-74: LGTM! Plugin implementation follows expected patterns.

The plugin correctly:

• Retrieves the global tracing helper lazily on each invocation
• Returns empty object when tracing is disabled
• Only includes traceparent when the span is sampled
• Integrates cleanly with the SqlCommenterPlugin interface

The defensive checks at lines 61-63 and 68-70 ensure graceful degradation when tracing isn't configured or active.

packages/client/src/runtime/core/tracing/TracingHelper.test.ts (2)

16-22: LGTM! Good test isolation with lifecycle hooks.

Adding beforeEach and afterEach hooks to clear the global tracing helper ensures proper test isolation and prevents state leakage between tests.

---

34-61: LGTM! Tests properly validate global helper lifecycle.

The updated tests correctly verify:

1. The helper picks up a globally set tracing helper
2. After clearing, the system falls back to the disabled helper (traceparent ending in 00)

The tests align well with the new @prisma/instrumentation-contract API.

packages/instrumentation/src/PrismaInstrumentation.ts (1)

39-56: LGTM! Clean refactor to centralized global helper API.

The implementation correctly:

• Uses setGlobalTracingHelper() to register the ActiveTracingHelper when enabling
• Uses clearGlobalTracingHelper() to remove the helper when disabling
• Uses getGlobalTracingHelper() !== undefined to check enabled state

This centralizes the global state management in @prisma/instrumentation-contract, improving maintainability and consistency across packages.

packages/instrumentation-contract/src/global.ts (4)

21-34: LGTM! Proper version isolation with backwards compatibility.

The getGlobalTracingHelper() function correctly:

• Prioritizes the versioned global key for major version isolation
• Falls back to the unversioned global for backwards compatibility with older versions
• Uses optional chaining for safe property access

The TODO comment appropriately flags this for potential simplification in v8.

---

40-47: LGTM! Dual-write strategy ensures compatibility.

Setting both versioned and unversioned globals ensures that:

• New clients using versioned keys can find the helper
• Older clients using the unversioned key remain functional

This is the correct approach for a compatibility transition period.

---

53-56: LGTM! Complete cleanup of global state.

Deleting both global keys ensures no stale references remain after disabling instrumentation.

---

1-7: JSON module import is correctly configured.

The resolveJsonModule: true setting is present in tsconfig.build.regular.json (the base configuration) and properly inherited by packages/instrumentation-contract/tsconfig.json through the configuration chain. The import of package.json on line 1 will work as expected.

packages/sqlcommenter-trace-context/src/index.test.ts (6)

1-16: LGTM! Well-structured mock helper factory.

The createMockTracingHelper factory provides good defaults while allowing targeted overrides for individual tests. The interface implementation is complete and matches the TracingHelper contract from @prisma/instrumentation-contract.

---

18-27: LGTM! Mock context is minimal and appropriate.

The mock context correctly matches the SqlCommenterContext shape required by the plugin.

---

29-36: LGTM! Proper test isolation with global state cleanup.

Using both beforeEach and afterEach to clear the global tracing helper ensures tests don't leak state to each other.

---

63-123: Good coverage of W3C trace-context sampled flag variations.

The tests correctly verify:

• 01 (sampled) returns traceparent
• 00 (not sampled) returns empty
• 03 (sampled bit set in flags with other bits) returns traceparent
• 02 (other bits set, sampled bit not set) returns empty

This aligns with the W3C Trace Context specification where the sampled flag is the lowest bit (0x01).

---

125-182: Comprehensive edge case coverage for malformed traceparents.

Good defensive testing for:

• Wrong number of parts
• Invalid hex characters in flags
• Wrong flag length
• Placeholder traceparent

This ensures the isSampled function gracefully handles invalid input.

---

192-213: Good test for dynamic tracing state evaluation.

This test verifies that the plugin correctly re-evaluates tracing state on each invocation rather than capturing it at plugin creation time. This is important for the use case where tracing can be toggled via PrismaInstrumentation::disable/enable at runtime.

packages/client/src/runtime/core/tracing/TracingHelper.ts (2)

2-8: LGTM! Clean import consolidation.

All tracing types and the global helper accessor are now imported from the centralized @prisma/instrumentation-contract package, which aligns with the PR objective of introducing a contract-based interface.

---

37-59: Good refactor to centralize global helper access.

The DynamicTracingHelper now delegates all calls through a single getTracingHelper() accessor that uses getGlobalTracingHelper() ?? disabledTracingHelper. This pattern ensures consistent fallback behavior and makes the code easier to reason about.

One minor observation: each method call now goes through an extra function call to getTracingHelper(), but this is negligible overhead and provides cleaner separation of concerns.

packages/instrumentation-contract/src/types.ts (5)

5-14: LGTM! Good conversion to interface with extends.

Converting ExtendedSpanOptions from a type alias to an interface that extends SpanOptions is cleaner and provides better IDE support for interface merging if needed in the future.

---

35-46: LGTM! Clean interface definition.

The EngineTraceEvent interface properly defines the shape for engine trace events with appropriate type annotations for the attributes record.

---

48-51: LGTM! Concise interface definition.

EngineTrace cleanly composes EngineSpan[] and EngineTraceEvent[].

---

53-61: LGTM! Well-defined TracingHelper contract.

The TracingHelper interface provides a clear contract for tracing implementations with methods for checking enabled state, getting trace context, dispatching spans, and running code in child spans.

---

63-65: LGTM! Clean interface for global value.

The PrismaInstrumentationGlobalValue interface correctly uses an optional helper property, allowing for the case where instrumentation is not configured.