refactor(graphql): migrate shimmer to orchestrion instrumentation (#7757)

feat(graphql): migrate instrumentation to orchestrion

  Migrates GraphQL instrumentation from shimmer wrappers to orchestrion AST rewriting for graphql execute / parse / validate entry points, including CJS and ESM paths for graphql >=0.10 and @graphql-tools/executor.

  Moves resolver instrumentation into the GraphQL execute plugin. The execute plugin now owns per-execute root context, resolver wrapping, resolve-span lifecycle, source tracking, and resolver hook invocation. The old separate resolve plugin is removed.

  Preserves and tests the existing cross-feature contracts:
  - IAST still receives one apm:graphql:resolve:start publish per resolver call, using the actual GraphQL args object.
  - AppSec still receives resolver payloads through datadog:graphql:resolver:start and can abort synchronously through the shared abort controller.
  - depth only limits resolve-span creation; IAST/AppSec resolver publishes still happen for depth-gated fields.
  - depth-gated resolvers now honor abort signals before falling through the no-span fast path.
  - caller-owned execute args and contextValue are preserved without mutation.
  - default field resolver behavior matches graphql for primitive parent values.
  - graphql-yoga / @graphql-tools/executor execution is instrumented.

  Adds public TypeScript declarations for the GraphQL resolve hook and FieldContext payload.

  Keeps the implementation orchestrion-only, with no shimmer fallback, and updates the GraphQL long benchmark calibration for the migrated hot path.

  Regression coverage was added for:
  - resolver abort behavior past the configured depth
  - depth: 0 AppSec resolver-channel publishing
  - primitive-source defaultFieldResolver parity
  - caller-supplied and frozen execute args
  - primitive contextValue forwarding
  - Yoga normalized executor instrumentation
  - IAST/AppSec per-resolver channel cardinality

  Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
  Co-authored-by: Ruben Bridgewater <ruben@bridgewater.de>

Author: crysmags

.agents/skills/apm-integrations/references/orchestrion.md

@@ -208,6 +208,95 @@ For integrations wrapping multiple methods, create a separate plugin class per m
 - `ctx.error` — thrown error (on error)
 - `ctx.currentStore` — set by `startSpan` in `bindStart`
 
+## Propagating Synchronous Errors From `bindStart`
+
+Subscribers on the prefix `:start` channel and `bindStore` transforms **cannot
+propagate a synchronous throw** to the caller of an orchestrion-wrapped
+function. Both are wrapped in `try { ... } catch (err) { process.nextTick(() =>
+triggerUncaughtException(err)); ... }` by Node's `diagnostics_channel` (see
+`lib/diagnostics_channel.js`'s `wrapStoreRun` and `publish`). The error
+surfaces async as an uncaught exception, **after** the wrapped fn has already
+run and the call has returned normally.
+
+The wrapper's own catch block, however, **does** rethrow:
+
+```js
+return ch.start.runStores(__apm$ctx, () => {
+  try {
+    const result = __apm$traced();
+    __apm$ctx.result = result;
+    return result;
+  } catch (err) {
+    __apm$ctx.error = err;
+    ch.error.publish(__apm$ctx);
+    throw err;                  // <- propagates the wrapped fn's error to the caller
+  } finally {
+    ch.end.publish(__apm$ctx);
+  }
+});
+```
+
+When a contract requires `assert.throws(() => wrapped(...))`-style synchronous
+propagation from a `:start` observer (the canonical case is AppSec WAF's
+`abortController.abort()` model), use the **Proxy-on-arguments pattern**:
+
+```js
+bindStart (ctx) {
+  // ... normal setup, span creation ...
+  const abortController = new AbortController()
+  if (startCh.hasSubscribers) {
+    startCh.publish({ abortController, args })       // subscribers run sync
+    if (abortController.signal.aborted) {
+      // ctx.arguments is the SAME array reference the wrapper spreads into
+      // the wrapped fn (__apm$wrapped.apply(this, ctx.arguments)). Replace
+      // arguments[0] with a Proxy whose getters throw AbortError. The
+      // wrapped fn's first property access (typically a destructure of args)
+      // triggers the trap → the wrapper's catch+rethrow propagates AbortError
+      // to the caller. Span lifecycle still completes via end.publish.
+      ctx.arguments[0] = new Proxy({}, {
+        get () { throw new AbortError('Aborted') },
+        has () { throw new AbortError('Aborted') },
+      })
+      ctx.ddAborted = true
+      return ctx.currentStore
+    }
+  }
+  // ... rest of bindStart ...
+}
+
+error (ctx) {
+  if (ctx.ddAborted) return                          // abort != error tag
+  // ... regular error handling ...
+}
+```
+
+Reference implementation: `packages/datadog-plugin-graphql/src/execute.js`
+(`apm:graphql:execute:start` contract).
+
+Why this works:
+- `ctx.arguments` and the rewriter's `__apm$arguments` are the same array
+  reference (confirmed by capturing the rewriter output: `const __apm$traced
+  = () => __apm$wrapped.apply(this, __apm$arguments)`).
+- The wrapped fn's body almost always touches `arguments[0]` on the first
+  statement (destructure, property read, validation). Any read triggers the
+  Proxy trap.
+- The orchestrion wrapper's `catch { ...; throw err }` propagates the thrown
+  error synchronously to the caller — confirmed in the rewriter template
+  (vendor's `code-transformer/index.js`, `wrapSync` function).
+- `:end` still fires in `finally`, so the plugin's `end(ctx)` runs as usual
+  and the span lifecycle completes cleanly. Combined with an `error(ctx)`
+  that no-ops when `ctx.ddAborted`, the span finishes with `error === 0`
+  (matches the abort contract).
+
+When NOT to use this:
+- If you control the wrapped fn (e.g., it's a method you can wrap with
+  shimmer on top of orchestrion), do that — clearer and avoids the
+  Proxy indirection.
+- If the wrapped fn might catch its own errors before they escape (some
+  user-resolver patterns do this), the AbortError won't propagate. Verify
+  the wrapped fn does NOT have a top-level `try/catch` around the
+  property access that triggers the trap.
+
 ## Common Issues
 
 ### Wrong filePath

benchmark/sirun/plugin-graphql-long/meta.json

@@ -11,7 +11,7 @@
       "env": { "WITH_TRACER": "1", "WITH_DEPTH": "0", "OPERATIONS": "1150" }
     },
     "with-depth-on-max": {
-      "env": { "WITH_TRACER": "1", "WITH_DEPTH": "4", "OPERATIONS": "530" }
+      "env": { "WITH_TRACER": "1", "WITH_DEPTH": "4", "OPERATIONS": "800" }
     },
     "with-depth-and-collapse-off": {
       "env": { "WITH_TRACER": "1", "WITH_DEPTH_AND_COLLAPSE": "4,0", "OPERATIONS": "210" }

docs/test.ts

@@ -230,7 +230,8 @@ const graphqlOptions: plugins.graphql = {
   hooks: {
     execute: (span?: Span, args?, res?) => { },
     validate: (span?: Span, document?, errors?) => { },
-    parse: (span?: Span, source?, document?) => { }
+    parse: (span?: Span, source?, document?) => { },
+    resolve: (span?: Span, field?) => { }
   }
 };
 

index.d.ts

@@ -2491,6 +2491,18 @@ declare namespace tracer {
     typeResolver?: any,
     }
 
+    /** Context object passed to the `hooks.resolve` callback for each instrumented field. */
+    interface FieldContext {
+      /** The field name being resolved */
+      fieldName: string;
+      /** The dot-separated field path (e.g. `'user.address.city'`) */
+      path: string;
+      /** The error from the resolver, or `null` if it succeeded */
+      error: Error | null;
+      /** The value returned by the resolver (sync resolvers only; `undefined` for async) */
+      result: unknown;
+    }
+
     /**
      * This plugin automatically instruments the
      * [graphql](https://github.com/graphql/graphql-js) module.
@@ -2569,6 +2581,7 @@ declare namespace tracer {
         execute?: (span?: Span, args?: ExecutionArgs, res?: any) => void;
         validate?: (span?: Span, document?: any, errors?: any) => void;
         parse?: (span?: Span, source?: any, document?: any) => void;
+        resolve?: (span?: Span, field?: FieldContext) => void;
       }
     }
 

index.d.v5.ts

@@ -2625,6 +2625,18 @@ declare namespace tracer {
     typeResolver?: any,
     }
 
+    /** Context object passed to the `hooks.resolve` callback for each instrumented field. */
+    interface FieldContext {
+      /** The field name being resolved */
+      fieldName: string;
+      /** The dot-separated field path (e.g. `'user.address.city'`) */
+      path: string;
+      /** The error from the resolver, or `null` if it succeeded */
+      error: Error | null;
+      /** The value returned by the resolver (sync resolvers only; `undefined` for async) */
+      result: unknown;
+    }
+
     /**
      * This plugin automatically instruments the
      * [graphql](https://github.com/graphql/graphql-js) module.
@@ -2703,6 +2715,7 @@ declare namespace tracer {
         execute?: (span?: Span, args?: ExecutionArgs, res?: any) => void;
         validate?: (span?: Span, document?: any, errors?: any) => void;
         parse?: (span?: Span, source?: any, document?: any) => void;
+        resolve?: (span?: Span, field?: FieldContext) => void;
       }
     }