From 56838a036c2c43afee56b0336a35abbf959770f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20DS=20Andrade?= <95101505+viniciusdsandrade@users.noreply.github.com> Date: Fri, 20 Nov 2026 20:22:01 -0300 Subject: [PATCH] docs(v8): describe the six-word code cache header State the second pinned layout, its word table and how admission reads the payload length for each layout. Record that the six-word roles come from the V8 sources and that runtime compatibility with a V8 8.8 through 11.7 producer remains unverified. --- docs/guides/javascript/v8-code-cache.md | 32 +++++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/guides/javascript/v8-code-cache.md b/docs/guides/javascript/v8-code-cache.md index 7c17450ca9..702e0a9cec 100644 --- a/docs/guides/javascript/v8-code-cache.md +++ b/docs/guides/javascript/v8-code-cache.md @@ -16,8 +16,8 @@ Evidence. ## What is read -A V8 code cache is a version-dependent container. This reader recognizes a pinned -layout with both supported header extents and reports observed header values and +A V8 code cache is a version-dependent container. This reader recognizes two pinned +layouts with their supported header extents and reports observed header values and payload bytes. The [Node v24.22.1 V8 serializer](https://github.com/nodejs/node/blob/v24.22.1/deps/v8/src/snapshot/code-serializer.h#L106-L119) @@ -42,15 +42,37 @@ appears in `header.fields` with its byte offset, value, role, and confidence. could plausibly differ. `unconfirmed` means the word is reported and nothing more is claimed. +V8 8.8 through 11.7, which Node 16 through 20 embed, define six words instead. The +[Node v20.18.0 V8 serializer](https://github.com/nodejs/node/blob/v20.18.0/deps/v8/src/snapshot/code-serializer.h#L121-L135) +has no build-constant word, so the payload length is the fifth word and the 24-byte +header needs no alignment padding on either pointer width. + +| Offset | Role | Status | +| ------ | -------------- | ----------- | +| `0x00` | magic | confirmed | +| `0x04` | version hash | inferred | +| `0x08` | source length | inferred | +| `0x0c` | flag hash | inferred | +| `0x10` | payload length | confirmed | +| `0x14` | reserved | unconfirmed | + +The six-word roles come from that source definition. No producer of those releases was +measured, so only the magic and the payload-length relation, which admission checks on +the container itself, are confirmed. A result for such a container says so in +`limitations`. + Admission requires the V8 magic high half `0xc0de` and a declared payload -that reaches the end of the file from a 28- or 32-byte header. +that reaches the end of the file: from a 28- or 32-byte header when read from the word +at `0x14`, or from a 24-byte header when read from the word at `0x10`. `ExternalReferenceTable::kSize` accounts for the varying low half of the magic word. +A container that satisfies both relations is ambiguous, and the reader refuses it. A candidate 28-byte header followed by a zero word is ambiguous. A 32-byte header with a four-byte-truncated payload leaves its zero padding at the same offset as a 28-byte header whose payload begins with that word. The reader refuses that case. -Header extent describes the retained bytes. The synthetic narrow fixture tests -reader admission. Runtime compatibility remains unverified for a 32-bit producer. +Header extent describes the retained bytes. The synthetic narrow and six-word +fixtures test reader admission. Runtime compatibility remains unverified for a 32-bit +producer and for a V8 8.8 through 11.7 producer. `header.source_length` is the producer's recorded source length in UTF-16 code units. V8's serializer calls this field the source hash; on the producers measured here its value