Transition trees, deprecation, and migration

Transitions are edges in a shared tree

Recall the one-line version from browser/03-v8-internals/03-hidden-classes: adding x then y reaches a different leaf than adding y then x, so order matters. Now the mechanism. Every Map stores a forward TransitionArray keyed by {property name, attributes}. Adding a property:

1. Looks up the {name, attributes} edge in the current Map’s TransitionArray.
2. If an edge exists, follows it — no allocation, you reuse the existing child Map and its (shared) DescriptorArray.
3. If no edge exists, creates a new child Map (extending the parent’s DescriptorArray by one descriptor), records the edge, and points the object at the new Map.

Because the tree is shared across the entire isolate, the second object to walk a path is free — it follows edges the first object created. This is why building objects the same way is cheap and building them in scrambled orders is not: scrambled orders never re-find an edge, so every object forces a fresh Map.

const a = {}; a.x = 1; a.y = 2;   // empty -> +x -> +x,y   (creates 2 edges)
const b = {}; b.x = 3; b.y = 4;   // empty -> +x -> +x,y   (follows them; 0 new Maps)
const c = {}; c.y = 5; c.x = 6;   // empty -> +y -> +y,x   (new branch; 2 new Maps)

Three more ways to transition (not just adding properties)

The overview implied transitions come only from adding properties. They do not. There are three other triggers, and they bite in production:

• Elements-kind change. Writing a float into a PACKED_SMI_ELEMENTS array, or creating a hole, transitions the array’s Map to a wider elements kind (PACKED_SMI → PACKED_DOUBLE → PACKED_ELEMENTS, and the HOLEY variants). One-way, like the property tree.
• Field representation generalization. This is the big one. A field starts narrow — say Smi. If any instance later stores a value that does not fit (2.5, or a string), the field’s representation must widen to Double or Tagged. But the representation is a property of the Map, shared by all instances. So V8 cannot just change one object; it must generalize the Map.
• Constness loss. A field is const while every instance assigned it the same value. The first instance that assigns a different value flips the descriptor to mutable, which is itself a transition (the compiled code that inlined the constant must be invalidated).

Together these three non-adding triggers share one pattern: a change in what a field can hold forces a change in the shared Map, not in individual objects. Without understanding this, you will spend hours suspecting GC or network when the real cause is a single float assignment two call frames away.

Deprecation and migration: how V8 widens a shared field

Here is the subtle part. Suppose 10000 objects share Map M1 where field temp has representation Smi. Now one object assigns obj.temp = 98.6. The field must become Double — but for the whole shape, because the Map is shared. V8 cannot rewrite 10000 objects at that instant (it does not even have a list of them). Instead:

1. It creates a new Map M2 identical to M1 except temp is Double (a more general representation). The split happens at the right place in the tree, and descendants are re-pointed.
2. It marks M1 as deprecated — a dead Map that should no longer be used. Existing objects still point at M1 for now.
3. Migration is lazy. The next time V8 touches one of those objects through a slow path (a property access whose inline cache misses, a %DebugPrint, etc.), it notices the object’s Map is deprecated, walks to the corresponding non-deprecated Map (M2) using the back-pointers from lesson 01, rewrites the object’s layout in place (boxing the integer into a double slot), and updates the object’s map pointer. This is the “MigrationMarker” / migration path.

So a single obj.temp = 98.6 can begin deprecating a shape used by thousands of objects, each paying a small migration cost the next time it is accessed. If that field oscillates between integer and float, you can churn deprecation repeatedly — a real, hard-to-spot deopt source.

Why scrambled key orders are pathological

Put the pieces together. A function that builds objects by iterating input keys in arbitrary order (a JSON re-serializer, a generic mapper, generated code) creates a new branch of the transition tree for almost every distinct order it sees. The shapes never repeat, so:

• Every object allocates fresh Maps and DescriptorArrays (the lesson-01 memory blow-up).
• The downstream inline cache that reads those objects sees a fresh Map nearly every time → it goes polymorphic, then megamorphic, then gives up (lesson 05).
• TurboFan cannot specialize on a stable shape, so the hot function never reaches top tier or deopts repeatedly.

The fix is always the same: build from a fixed schema in a constant order (defaulting absent fields to null), or store genuinely dynamic key sets in a Map collection that is built for arbitrary keys.