fix(otel-thread-ctx): detect AsyncContextFrame by reading CPED natively

[szegedi]

Follow-up to #397, implementing @nsavoire's suggestion from this comment: gather the evidence natively by reading CPED, rather than inferring it from AsyncLocalStorage#run's behaviour.

Of the three shapes I floated in r3776016667, this is the third — cpedMapContains(key, value).

#397's detection overrode enterWith on a throwaway AsyncLocalStorage and checked whether run() dispatched through it:

probe.enterWith = () => { delegated = true; };
probe.run(0, () => {});

That run() reaches the instance's enterWith property is unspecified. Anything patching AsyncLocalStorage can break it — dd-trace-js patches async-context machinery itself — and the resulting false negative is precisely the failure #397 existed to fix: ThreadContext#enter() throwing from an inline diagnostic-channel subscriber, surfacing in application code.

We now replace this with:

const probe = new AsyncLocalStorage();
const sentinel = {};
let bound = false;
probe.run(sentinel, () => { bound = addon.cpedMapContains(probe, sentinel); });
probe.disable();
active = bound;

With ACF active, Node installs an AsyncContextFrame — a JS Map keyed by the storage instance, valued by its store — as the running continuation's CPED. Nothing writes the slot otherwise.

Why key+value rather than cpedIsMap

CPED is a general embedder slot. A Map that some other native addon left there must not be able to answer for us — that would readmit the silent false positive #397 killed, where the writer looks healthy from JS while every reader sees records nothing updates.

This is load-bearing, not theoretical: mutating the helper to a bare IsMap check fails three of the five new tests and none of the pre-existing ones. Without them, the weaker version would pass the whole suite.

Why not getCped

Returning the live frame to JS would hand any caller who can require the addon an object whose mutation corrupts async-context propagation process-wide. It also moves the check into JS, where instanceof Map is realm-sensitive (the frame is a SafeMap subclass), so it'd need to be acf?.get?.(probe) === value to be safe — same answer as this, larger blast radius.

Implementation notes

• In binding.cc, not wall.cc, so it works on Windows. wall.cc's #ifndef _WIN32 block is there for SIGPROF and the v8::base::TimeTicks symbol trick; a CPED read needs neither. This allows us to not have a JS fallback anywhere. This is largely theoretical as none of the features using CPED currently work on Windows, but one can hope.
• NODE_MAJOR_VERSION >= 22, returning false below — the correct answer there, rather than a missing export the JS side has to reason about.
• Total by construction. We check for no context entered, CPED slot unset, CPED value not being a Map, key absent, and even a malformed call; these all yield false, and never throw.

Second commit: the 22.7.0 cutoff

The >=22.7.0 nits from the same review. ACF landed in 22.7.0, not at the 22 boundary, and several places named the wrong version.

The && satisfies(process.versions.node, '>=22.7.0') conjunct comes off all four useCPED definitions: it is redundant against isAsyncContextFrameActive(), since ACF cannot be active below 22.7.0, so the detection already answers false there. That leaves semver unused in test-get-value-from-map-profiler.ts, so its import goes too. The skip gates in test-async-context-frame.ts move from a bare major to a semver check, and the prose cutoffs are corrected.

asyncContextFrameHint() held the only user-visible instance: on 22.0 through 22.6 it advised passing --experimental-async-context-frame, a flag those versions don't have. Compared by major/minor rather than semver.satisfies, since semver is a devDependency and this module ships. Boundary checked across 20.19.0, 22.6.0, 22.7.0, 22.23.2, 23.5.0 and 24.18.0.

[github-actions]

Overall package size

Self size: 2.53 MB
Deduped: 3.23 MB
No deduping: 3.23 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | pprof-format | 2.3.1 | 504.33 kB | 504.33 kB | | source-map | 0.8.0 | 185.66 kB | 185.66 kB | | node-gyp-build | 4.8.4 | 13.86 kB | 13.86 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}

[Copilot]

Pull request overview

This PR strengthens AsyncContextFrame (ACF) detection by switching from a JavaScript-level behavioral proxy (AsyncLocalStorage#run delegating to enterWith) to a native check that directly inspects V8’s ContinuationPreservedEmbedderData (CPED) for the expected ACF Map binding. It also corrects the version boundary for ACF support (22.7.0) and removes redundant >=22.7.0 gating where the new detection already answers correctly.

Changes:

• Add native addon helper cpedMapContains(key, value) to validate that CPED holds a Map binding the given key to the given value (used as the new ACF detection substrate).
• Update isAsyncContextFrameActive() to run a probe AsyncLocalStorage and query CPED natively, avoiding reliance on unspecified JS dispatch behavior.
• Adjust tests and test gating to reflect the correct ACF introduction point (Node 22.7.0) and remove redundant semver checks where appropriate.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
ts/src/async-context-frame.ts	Replaces JS behavioral inference with native CPED-based detection; updates hint logic for Node 22.7.0 boundary.
bindings/binding.cc	Exports cpedMapContains to check CPED Map membership/binding in native code.
ts/test/test-async-context-frame.ts	Adds targeted tests for cpedMapContains semantics and updates version gating to >=22.7.0.
ts/test/test-time-profiler.ts	Removes redundant >=22.7.0 semver gate for CPED usage, relying on detection instead.
ts/test/test-get-value-from-map-profiler.ts	Removes unused semver import and redundant >=22.7.0 CPED gate.
ts/test/worker.ts	Removes redundant >=22.7.0 semver gate for CPED usage in worker tests.
ts/test/worker2.ts	Removes redundant >=22.7.0 semver gate for CPED usage in worker tests.
ts/test/test-otel-thread-ctx.ts	Corrects documentation comment to reflect ACF support starting at Node 22.7.0.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[nsavoire]

Thanks for the changes !