ShadowRealm: a value the host registers, and the members its wrapper builds eagerly, belong to that realm

[lahma]

Backport of #3367 and #3427, the two ShadowRealm realm-affinity fixes, adapted to 4.x.

They land as one PR because the second only bites once the first exists. An ObjectWrapper takes its realm from whichever one is running when it is built, so until SetValue enters the shadow realm there is no shadow realm for the eagerly built members to belong to — porting #3427 alone would have been a no-op on 4.x.

A value the host registers belongs to that realm (#3325)

ShadowRealm.SetValue converted its argument against whichever realm the host called from — the principal one — and then installed the result on the shadow realm's global object. The prototype came from the wrong realm, so script inside the realm did not recognize the object the host had just handed it:

var shadowRealm = engine.Intrinsics.ShadowRealm.Construct();
shadowRealm.SetValue("company", new Company("acme"));

shadowRealm.Evaluate("company instanceof Object");   // false

That is the opposite of what a realm is for.

Realm-scoped construction is entering that realm's execution context, and nothing else. Engine.Realm is ExecutionContext.Realm, and every interop construction reads it to pick a prototype: JsValue.FromObject through ObjectInstance's base constructor, TypeReference.CreateTypeReference through TypeReferencePrototype, DelegateWrapper outright. ShadowRealmImportValue in this very class already does exactly that, so SetValue now brackets its registration the same way, through a RealmScope that names it.

The wrapper's eagerly built members agree with it (#3365)

ObjectWrapper's constructor builds three members eagerly — Symbol.dispose, Symbol.asyncDispose and toJSON — through the public ClrFunction(Engine, string, …) constructor, which pins engine._originalIntrinsics. That pin is deliberate and is what #2893 fixed: a function a host wires up against an engine must belong to the realm the surrounding script can reach whatever realm happened to be current when it was built. It is the wrong constructor for a function the engine builds for an object it is creating, and the consequence was two answers on one object:

handle.Dispose instanceof Function            // true   — resolved lazily, reads engine.Realm
handle[Symbol.dispose] instanceof Function    // false  — a Function of a realm this script cannot reach

using and JSON.stringify kept working throughout, because a call never consults the prototype. What did not work is anything asking what the member is: a feature detection, Object.getPrototypeOf, or a reach for call/apply/bind.

The issue asked which realm an ObjectWrapper answers with, and noted it has no _realm field. It needs none: the question is answered two constructors up, where ObjectInstance's constructor takes _prototype from engine.Realm.Intrinsics and ArrayLikeWrapper takes Array.prototype from engine.Intrinsics — both the running realm. The three members simply have to agree with it, so each now uses the internal ClrFunction(Engine, Realm, …) constructor whose own doc comment names this exact case, with engine.Realm.

ClrFunction(Engine, …), HostFunction and Constructor(Engine, string) keep pinning engine._originalIntrinsics and are untouched; HostClrFunctionRealmTests still passes. The distinction the two constructors draw is the whole rule: the host's function belongs to the host's realm; the engine's function belongs to the object's.

How this differs from main, and what is deliberately not here

Three overloads take the realm scope on 4.x rather than main's six — the same rule, not a narrower one. main's SetValue had been widened to mirror Engine.SetValue (#3321) before #3367 landed on it, so it has Type, generic and array overloads that 4.x does not. On 4.x a Type and an array both arrive through SetValue(string, object), and the four primitive overloads reach the JsValue one — which takes the scope as well, so installation happening in the realm being written stays one rule rather than two. Every path that converts or installs is covered, and the tests are written against the behaviour, not the overload list, so they pin the same seven facts.

Consequently main's GlobalValueRegistration hunk has no counterpart here — that class does not exist on 4.x, where the overloads convert inline.

The ImportValue half of #3367 is deliberately omitted: its premise is absent on 4.x. That half added using var ownership = _engine.EnterHostCall(); so a second thread reaching Evaluate during a module load is refused. 4.x has no EnterHostCall and no engine-ownership reservation at all — grep -rn "EnterHostCall" Jint/ returns nothing — so there is nothing to claim, no behaviour to fix, and no HostEngineConcurrencyTests to join. Porting the reservation would mean backporting the whole ownership mechanism, which is well past a one-sentence backport.

docs/v5-migration.md and Jint/Runtime/Interop/AGENTS.md do not exist on 4.x, and UndocumentedPublicApi.txt does not either, so those hunks are dropped. No public API signature moves — the constructor being called instead is internal and already existed on 4.x.

Evidence

Jint.Tests.PublicInterface/ShadowRealmValueRealmTests.cs, translated to xUnit v3 ([Test] → [Fact]): one fact per converting overload, one per eagerly built member, both negative halves stated against the principal intrinsic handed into the realm through the JsValue overload, the two guards that an engine registration keeps the principal realm, and the control that disposal itself still works. The Symbol.asyncDispose pair is #if !NETFRAMEWORK, matching Jint's own SUPPORTS_ASYNC_DISPOSE.

Failing first, on unmodified 4.x with only the tests added:

TFM	before	after
net10.0	Failed: 10, Passed: 3, Total: 13	Failed: 0, Passed: 13
net472	Failed: 9, Passed: 3, Total: 12	Failed: 0, Passed: 12

Per fix, on unfixed 4.x:

• ShadowRealm: a value the host registers belongs to that realm, and ImportValue claims the engine #3367 (SetValue) — 6 failing on both TFMs: the typed and untyped host object, the delegate, the type reference, the projected array, and the negative half. Expected value to be "true (Boolean)", but found "false (Boolean)".
• ShadowRealm: a wrapper's eagerly built members are functions of the realm the wrapper belongs to #3427 (eager members) — 4 failing on net10.0, 3 on net472 (Symbol.asyncDispose is net10.0-only): Symbol.dispose, Symbol.asyncDispose, toJSON, and the negative half AnEagerlyBuiltMemberIsNotAFunctionOfThePrincipalRealm, which fails the other way — Expected value to be "false (Boolean)", but found "true (Boolean)".

The 3 that pass on unfixed 4.x are exactly the two guards (TheEnginesOwnRegistrationsStillBelongToThePrincipalRealm, TheEagerlyBuiltMembersOfAnEngineRegistrationStayInThePrincipalRealm) and the control (ADisposableHostObjectIsStillDisposableInsideTheRealm) — which is the point: they state what must not change, and it did not.

Verification

• dotnet build -c Release — 0 errors, 0 code warnings.
• Jint.Tests — 6,958 passed on net10.0, 6,873 on net472, 0 failed.
• Jint.Tests.PublicInterface — 1,515 passed on net10.0, 1,507 on net472, 0 failed.
• Jint.Tests.CommonScripts — 28 passed on each, 0 failed.
• Jint.Tests.SourceGenerators — 52 passed, 0 failed.
• Jint.Tests.Test262 — 102,499 passed, 0 failed, 185 skipped of 102,684, matching the 4.x control exactly.

No benchmark: the change is which of two already-resolved prototype references three constructor-time allocations read, plus one execution-context push and pop per host SetValue call.

🤖 Generated with Claude Code

https://claude.ai/code/session_014W5mbjGhyvgAS4pivXoc4S