From ea4baaf6de4716033f423137d45fa5121e7fc33d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=B4=E4=BD=B3=E6=B5=A9Alben?= <35291372+XiaoBinGan@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:41:01 +0800 Subject: [PATCH] fix(v8): read the code cache header size from the container (#10279) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(v8): read the code cache header size from the container V8 sizes the header with `kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` and `kUnalignedHeaderSize` is 28, so the header is padded *after* its words: a 64-bit producer writes 32 header bytes and a 32-bit one writes 28. The reader pinned 32 and required the declared payload to equal `bytes.length - 32`, so every container from a 32-bit producer failed as "truncated or corrupt". Measured here on Node 24.22.1 (V8 in x64): take a real cache and drop the four alignment bytes at offset 28. V8 loads it unchanged — `cachedDataRejected === false` — while the reader refused it: before: Header declares a 392-byte payload but 388 bytes follow the 32-byte header after: ACCEPT header_bytes=28 words=7 payload.offset=28 The payload-length word sits at byte 20 in both layouts, so the declared length already states how much trailing padding the container carries. The header size is derived from it now: `28` and `32` are admitted, the reported word table covers exactly the header the container holds (7 or 8 words), and the schema requires that table to agree with `header_bytes`. Nothing is loosened. A header that is neither 28 nor 32 bytes is still `malformed`, and the 16 existing cases pass unchanged — dropping only the derivation back to the constant fails exactly the new narrow-header case. `src/v8` — 26 passing. `npm run lint` and `tsc --noEmit` clean. * fix(v8): refuse a wide cache that is only four bytes short A review finding on the previous commit, and a real one: deriving the header size from the declared payload length makes a 32-byte-header container truncated by four bytes resolve to 28, because `bytes.length - declaredPayload` loses exactly those four bytes. The reader then accepted a truncated cache and read its payload one word long. The wide header's last word is `POINTER_SIZE_ALIGN` padding that V8 leaves zero, and a narrow container has payload where that word sits. Measured on Node 24.22.1 across six different sources: the padding word is always `0x00000000` and the first payload word is always non-zero. So the zero word is the only evidence that separates the two, and it is now required to be non-zero for the 28-byte layout: | container | before this commit | after | | --- | --- | --- | | real 32-byte header | accept | accept, `header_bytes=32` | | real 28-byte header | accept | accept, `header_bytes=28` | | 32-byte header truncated by 4 | **accept** | refused as `malformed` | The guide also described one pinned 32-byte header; it now describes both layouts, how the size is resolved, and why an ambiguous container is refused. `src/v8` — 27 passing. Removing the guard accepts the truncated container again. * fix(v8): read the padding word through the header accessor A Static checks finding: `verify/architecture-guards.mjs` counts raw Buffer reads in parser folders and allows only a shrinking baseline, and the previous commit added one: ``` raw Buffer or DataView numeric read (use BinaryReader ...); new copies are not allowed: src/v8/V8CodeCacheParser.ts: 2 (baseline 1) ``` The read is the narrow-header discriminator — the alignment word a 64-bit producer leaves zero at offset 28. It now goes through the file's existing `field(index)` accessor instead of calling `bytes.readUInt32LE` directly, so the count returns to the baseline while the check itself is unchanged: `field(7)` is byte 28, and `V8_CODE_CACHE_NARROW_HEADER_BYTES / 4` spells that index. `node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files. `src/v8` + `tests/boundary/rust` — 68 passing. `tsc --noEmit` 0 errors. Setting the condition to `false` fails "refuses a wide container that is only four bytes short", so the check is still load-bearing. * fix(v8): ground the narrow-header rule in the producer, and test the word table Two review findings. **The rule was stated as measurement, not as format.** The previous comment justified the zero-word discriminator with "measured on Node 24.22.1 every real payload begins with a non-zero word", which makes support for other producers depend on one host. The producer zeroes that padding rather than copying payload over it: `SerializedData::AllocateWithPayload` in `src/snapshot/snapshot-data.cc` runs `std::fill_n(data_, header_size, 0)` before writing any header word, and `kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` in `src/snapshot/code-serializer.h` puts the four padding bytes inside `header_size`. So a zero word at byte 28 is a fact about the producer, not about one Node build. The refusal is now worded as the reservation it is: a narrow container whose payload happened to begin with four zero bytes would match the same test, and no reading of the header alone separates the two cases. The message says both readings instead of asserting corruption. **The word-table rule had no test that could fail.** `header.fields.length * 4 === header.header_bytes` cannot disagree on a parsed container — the parser derives both from `payloadOffset` — so it is only reachable through the schema, which is what a stored or projected report also goes through. The new case builds four reports directly: seven words with 32 bytes and eight words with 28 are refused on `header.fields`, while the two consistent pairs are accepted. Setting the rule to `false` fails it with `7 words / 32 bytes: expected true to be false`. `node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files. `src/v8` + `tests/boundary/rust` — 69 passing. `tsc --noEmit` 0 errors, `npm run lint` 0 errors. * refactor(v8): share decoded code cache header words * fix(v8): validate narrow header evidence without assuming runtime compatibility --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- docs/guides/javascript/v8-code-cache.md | 29 ++-- scripts/verify/baselines/raw-buffer-read.json | 3 +- src/domain/v8/v8CodeCache.ts | 39 ++++- src/v8/V8CodeCache.fixture.ts | 11 ++ src/v8/V8CodeCacheParser.test.ts | 142 +++++++++++++++++- src/v8/V8CodeCacheParser.ts | 57 ++++--- tests/acceptance/v8CodeCacheCli.test.ts | 50 +++--- 7 files changed, 272 insertions(+), 59 deletions(-) diff --git a/docs/guides/javascript/v8-code-cache.md b/docs/guides/javascript/v8-code-cache.md index 40c2c69ce7..7c17450ca9 100644 --- a/docs/guides/javascript/v8-code-cache.md +++ b/docs/guides/javascript/v8-code-cache.md @@ -16,13 +16,16 @@ Evidence. ## What is read -A V8 code cache is a producer-written container, not a documented file format. This reader -admits one container shape and reports everything else as an observation, so a build it -has never seen still yields facts instead of a false parse. +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 +payload bytes. -The 32-byte header is eight little-endian 32-bit words. Every word is reported in -`header.fields` with its byte offset, its observed value, the role this reader believes it -has, and how confident that role is: +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) +defines seven little-endian 32-bit words followed by pointer-alignment padding. +Four-byte alignment produces a 28-byte header. Eight-byte alignment produces a +32-byte header with a zero padding word. The reader derives the candidate header +extent from the container length and declared payload length. Each observed word +appears in `header.fields` with its byte offset, value, role, and confidence. | Offset | Role | Status | | -------------- | -------------- | ----------- | @@ -39,13 +42,15 @@ has, and how confident that role is: could plausibly differ. `unconfirmed` means the word is reported and nothing more is claimed. -Only three facts gate admission: +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. +`ExternalReferenceTable::kSize` accounts for the varying low half of the magic word. +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. -1. the header size this reader pins (32 bytes); -2. the V8 code cache magic high half, `0xc0de`. The low half is - `ExternalReferenceTable::kSize` and varies per V8 build, so it is reported as a build - fingerprint and never required to match a fixed value; -3. the declared payload length must equal the bytes that follow the header exactly. +Header extent describes the retained bytes. The synthetic narrow fixture tests +reader admission. Runtime compatibility remains unverified for a 32-bit 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 diff --git a/scripts/verify/baselines/raw-buffer-read.json b/scripts/verify/baselines/raw-buffer-read.json index 77622a1a9f..e02c78266d 100644 --- a/scripts/verify/baselines/raw-buffer-read.json +++ b/scripts/verify/baselines/raw-buffer-read.json @@ -8,6 +8,5 @@ "src/native/AppleObjcDispatchFacets.ts": 1, "src/native/AppleSwiftDispatchFacets.ts": 1, "src/native/elf/ElfNoteParser.ts": 6, - "src/native/pe/PeCertificateAsn1.ts": 2, - "src/v8/V8CodeCacheParser.ts": 1 + "src/native/pe/PeCertificateAsn1.ts": 2 } diff --git a/src/domain/v8/v8CodeCache.ts b/src/domain/v8/v8CodeCache.ts index cf52f26231..057713ab5d 100644 --- a/src/domain/v8/v8CodeCache.ts +++ b/src/domain/v8/v8CodeCache.ts @@ -12,8 +12,19 @@ const offset = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER); * process; it matches the pinned CPython pyc reader's 64 MiB ceiling. */ export const MAX_INSPECT_V8_CODE_CACHE_FILE_BYTES = 67108864; -/** Hard ceiling on the V8 code cache container header this reader accepts. */ +/** The 28-byte word area after alignment to an eight-byte pointer. */ export const V8_CODE_CACHE_HEADER_BYTES = 32; +/** The same word area with four-byte pointer alignment. */ +export const V8_CODE_CACHE_NARROW_HEADER_BYTES = 28; +/** Every container header size admitted by the pinned layout. */ +export const V8_CODE_CACHE_HEADER_SIZES: readonly number[] = [ + V8_CODE_CACHE_NARROW_HEADER_BYTES, + V8_CODE_CACHE_HEADER_BYTES, +]; +/** Shortest admitted header, so no selected file is smaller than this. */ +export const V8_CODE_CACHE_MIN_HEADER_BYTES = Math.min( + ...V8_CODE_CACHE_HEADER_SIZES, +); /** * V8 stamps every serialized code cache with `0xC0DE0000 ^ ExternalReferenceTable::kSize`. * Only the high half is stable across builds, so the low half is a build fingerprint and @@ -114,8 +125,8 @@ const headerSchema = z.strictObject({ magic: uint, /** High half of the magic, the only part stable across V8 builds. */ magic_build_stable: uint, - /** Every header word, in container order. */ - fields: z.array(headerFieldSchema).length(8), + /** Every header word this container carries, in container order. */ + fields: z.array(headerFieldSchema).min(7).max(8), /** Bytes this reader treats as header before the payload begins. */ header_bytes: uint, /** Source length in UTF-16 code units, as recorded by the producer, if determinable. */ @@ -178,11 +189,23 @@ export const v8CodeCacheSchema = z limitations: z.array(z.string().min(1)).min(1), }) .superRefine((report, context) => { - if (report.header.header_bytes !== V8_CODE_CACHE_HEADER_BYTES) + if (!V8_CODE_CACHE_HEADER_SIZES.includes(report.header.header_bytes)) context.addIssue({ code: "custom", path: ["header", "header_bytes"], - message: "This reader only accepts its pinned container header size.", + message: + "This reader only accepts the container header sizes it admits.", + }); + // The word table describes the container's own header, so it cannot disagree with it. + if ( + report.header.fields.length * 4 !== report.header.header_bytes || + report.header.fields.some(({ offset }, index) => offset !== index * 4) + ) + context.addIssue({ + code: "custom", + path: ["header", "fields"], + message: + "The reported words must cover the declared header in byte order.", }); if (report.header.magic_build_stable !== V8_CODE_CACHE_MAGIC_HIGH) context.addIssue({ @@ -191,6 +214,12 @@ export const v8CodeCacheSchema = z message: "The admitted magic must carry the stable V8 code cache high half.", }); + if (report.payload.offset !== report.header.header_bytes) + context.addIssue({ + code: "custom", + path: ["payload", "offset"], + message: "The payload must start at the end of the declared header.", + }); if (report.payload.offset + report.payload.bytes !== report.artifact.bytes) context.addIssue({ code: "custom", diff --git a/src/v8/V8CodeCache.fixture.ts b/src/v8/V8CodeCache.fixture.ts index be81df68ca..c7da6b6910 100644 --- a/src/v8/V8CodeCache.fixture.ts +++ b/src/v8/V8CodeCache.fixture.ts @@ -1,4 +1,8 @@ import vm from "node:vm"; +import { + V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_NARROW_HEADER_BYTES, +} from "../domain/v8/v8CodeCache.js"; /** * Generate a real V8 code cache instead of committing a version-pinned binary. Node @@ -9,6 +13,13 @@ export const v8CodeCacheFixture = ( ): Buffer => new vm.Script(source, { produceCachedData: true }).createCachedData(); +/** Build an offline reader fixture with the wide header's alignment word removed. */ +export const withSyntheticNarrowHeader = (wide: Buffer): Buffer => + Buffer.concat([ + wide.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES), + wide.subarray(V8_CODE_CACHE_HEADER_BYTES), + ]); + /** `vm.compileFunction` sets the producer bit in the source-length word. */ export const v8FunctionCodeCacheFixture = (source = "return 1 + 2;"): Buffer => vm.compileFunction(source, [], { produceCachedData: true }).cachedData ?? diff --git a/src/v8/V8CodeCacheParser.test.ts b/src/v8/V8CodeCacheParser.test.ts index 46df14a90c..2d62660e33 100644 --- a/src/v8/V8CodeCacheParser.test.ts +++ b/src/v8/V8CodeCacheParser.test.ts @@ -4,6 +4,8 @@ import { inspectV8CodeCacheInputSchema, v8CodeCacheSchema, V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_MAGIC_HIGH, + V8_CODE_CACHE_NARROW_HEADER_BYTES, type V8CodeCache, } from "../domain/v8/v8CodeCache.js"; import { parseV8CodeCache } from "./V8CodeCacheParser.js"; @@ -11,6 +13,7 @@ import { v8CodeCacheFixture, v8FunctionCodeCacheFixture, withHeaderWord, + withSyntheticNarrowHeader, } from "./V8CodeCache.fixture.js"; const defaults = inspectV8CodeCacheInputSchema.parse({ @@ -199,9 +202,9 @@ it("fails closed on a payload-length mismatch", () => { }); it("fails closed on a truncated header", () => { - expect(() => parse(real.subarray(0, V8_CODE_CACHE_HEADER_BYTES - 1))).toThrow( - expect.objectContaining({ kind: "malformed" }), - ); + expect(() => + parse(real.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES - 1)), + ).toThrow(expect.objectContaining({ kind: "malformed" })); }); it("fails closed when fewer payload bytes follow the header than it declares", () => { @@ -265,3 +268,136 @@ it("raises min_string_bytes and reports only runs that long", () => { const realSlice = (bytes: Buffer, offset: number, length: number): string => bytes.subarray(offset, offset + length).toString("latin1"); + +it("inspects a synthetic narrow layout derived from a 64-bit cache", () => { + // Removing the alignment word preserves the retained payload bytes. + const narrow = withSyntheticNarrowHeader(real); + const report = parse(narrow); + + expect(narrow.readUInt32LE(20)).toBe( + narrow.length - V8_CODE_CACHE_NARROW_HEADER_BYTES, + ); + expect(report.header.header_bytes).toBe(V8_CODE_CACHE_NARROW_HEADER_BYTES); + expect(report.payload.offset).toBe(V8_CODE_CACHE_NARROW_HEADER_BYTES); + // Nothing but the padding is removed, so the payload is identical. + expect(report.payload.sha256).toBe(parse(real).payload.sha256); + // The word table covers exactly the header this container carries. + expect(report.header.fields).toHaveLength(7); + expect(report.header.fields.map((entry) => entry.offset)).toEqual([ + 0, 4, 8, 12, 16, 20, 24, + ]); +}); + +it("fails closed when the declared payload leaves no admitted header size", () => { + // Padding that is neither 28 nor 32 bytes is not a container this reader admits. + expect(() => + parse( + Buffer.concat([ + real.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES + 2), + real.subarray(V8_CODE_CACHE_HEADER_BYTES), + ]), + ), + ).toThrow(expect.objectContaining({ kind: "malformed" })); +}); + +it("refuses a wide container that is only four bytes short", () => { + // Truncating a 32-byte-header cache by four bytes makes `bytes.length - declaredPayload` + // equal 28. The padding then occupies the same position as a zero first + // payload word in a narrow container, so the reader refuses the ambiguity. + const short = real.subarray(0, real.length - 4); + expect(short.readUInt32LE(28)).toBe(0); + expect(() => parse(short)).toThrow( + expect.objectContaining({ kind: "malformed" }), + ); + expect(() => parse(short)).toThrow(/ambiguous/u); + // A synthetic narrow fixture has payload at the same byte offset. + const narrow = withSyntheticNarrowHeader(real); + expect(narrow.readUInt32LE(V8_CODE_CACHE_NARROW_HEADER_BYTES)).not.toBe(0); + expect(parse(narrow).header.header_bytes).toBe( + V8_CODE_CACHE_NARROW_HEADER_BYTES, + ); +}); + +it("rejects a reported word table that does not cover the header it declares", () => { + // The parser derives both from one offset, so this pair cannot disagree on a + // parsed container; the schema is what a stored or projected report also goes + // through, and there the two are independent fields. Without these cases the + // rule could be deleted and every parser test would still pass. + const reported = (fieldCount: number, headerBytes: number) => ({ + artifact: { + path: "/artifacts/module.jsc", + sha256: "a".repeat(64), + bytes: 4096, + }, + header: { + magic: 0xf00d, + magic_build_stable: V8_CODE_CACHE_MAGIC_HIGH, + fields: Array.from({ length: fieldCount }, (_, index) => ({ + offset: index * 4, + value: index, + role: "reserved", + status: "unconfirmed" as const, + })), + header_bytes: headerBytes, + source_length: 10, + producer: "script" as const, + }, + payload: { + offset: headerBytes, + bytes: 4096 - headerBytes, + sha256: "b".repeat(64), + trailing_bytes: 0, + }, + embedded_strings: [], + coverage: { + status: "complete" as const, + scanned_bytes: 4096 - headerBytes, + strings: 0, + }, + limitations: ["measured on one producer"], + }); + + // Seven words is 28 bytes and eight is 32, so each header size has exactly one + // word count that covers it. + const cases = [ + { fields: 7, bytes: V8_CODE_CACHE_HEADER_BYTES, accepted: false }, + { fields: 8, bytes: V8_CODE_CACHE_NARROW_HEADER_BYTES, accepted: false }, + { fields: 7, bytes: V8_CODE_CACHE_NARROW_HEADER_BYTES, accepted: true }, + { fields: 8, bytes: V8_CODE_CACHE_HEADER_BYTES, accepted: true }, + ]; + for (const { fields, bytes, accepted } of cases) { + const label = `${String(fields)} words / ${String(bytes)} bytes`; + const parsed = v8CodeCacheSchema.safeParse(reported(fields, bytes)); + expect(parsed.success, label).toBe(accepted); + expect( + parsed.error?.issues.some( + (issue) => issue.path.join(".") === "header.fields", + ) ?? false, + label, + ).toBe(!accepted); + } +}); + +it("rejects retained header and payload coordinates that disagree", () => { + const report = parse(real); + const disordered = { + ...report, + header: { + ...report.header, + fields: report.header.fields.map((field, index) => + index === 0 ? { ...field, offset: 4 } : field, + ), + }, + }; + const shiftedPayload = { + ...report, + artifact: { ...report.artifact, bytes: report.artifact.bytes + 4 }, + payload: { ...report.payload, offset: report.payload.offset + 4 }, + }; + expect( + v8CodeCacheSchema.safeParse(disordered).error?.issues ?? [], + ).toContainEqual(expect.objectContaining({ path: ["header", "fields"] })); + expect( + v8CodeCacheSchema.safeParse(shiftedPayload).error?.issues ?? [], + ).toContainEqual(expect.objectContaining({ path: ["payload", "offset"] })); +}); diff --git a/src/v8/V8CodeCacheParser.ts b/src/v8/V8CodeCacheParser.ts index 3f18ffddf8..a062b75848 100644 --- a/src/v8/V8CodeCacheParser.ts +++ b/src/v8/V8CodeCacheParser.ts @@ -4,6 +4,9 @@ import { V8_CODE_CACHE_LEGACY_MODULE_BIT, V8_CODE_CACHE_MODULE_BIT, V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_HEADER_SIZES, + V8_CODE_CACHE_MIN_HEADER_BYTES, + V8_CODE_CACHE_NARROW_HEADER_BYTES, V8_CODE_CACHE_MAGIC_HIGH, V8_CODE_CACHE_SOURCE_LENGTH_MASK, type V8CodeCache, @@ -13,6 +16,7 @@ import { V8_CODE_CACHE_FORMAT, v8CodeCacheBudgetFailure, } from "../v8/V8CodeCache.errors.js"; +import { BinaryReader } from "../domain/binaryContainer.js"; import { malformedInput, unsupportedInput } from "../domain/parseFailure.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; @@ -72,28 +76,52 @@ export const parseV8CodeCache = ( ): V8CodeCache => { if (bytes.length !== artifact.bytes) malformed("Selected artifact length disagrees with the retained bytes."); - if (bytes.length < V8_CODE_CACHE_HEADER_BYTES) + if (bytes.length < V8_CODE_CACHE_MIN_HEADER_BYTES) malformed( - `Selected file is shorter than the ${String(V8_CODE_CACHE_HEADER_BYTES)}-byte V8 code cache header.`, + `Selected file is shorter than the ${String(V8_CODE_CACHE_MIN_HEADER_BYTES)}-byte V8 code cache header.`, ); - const field = (index: number): number => bytes.readUInt32LE(index * 4); - const magic = field(0); + const headerReader = new BinaryReader( + bytes.subarray(0, V8_CODE_CACHE_HEADER_BYTES), + true, + V8_CODE_CACHE_FORMAT, + ); + const readField = (entry: (typeof HEADER_ROLES)[number], index: number) => { + const offset = index * 4; + return { offset, value: headerReader.u32(offset), ...entry }; + }; + const commonFieldCount = V8_CODE_CACHE_NARROW_HEADER_BYTES / 4; + const fields = HEADER_ROLES.slice(0, commonFieldCount).map(readField); + const magic = fields[0]!.value; const magicHigh = magic >>> 16; if (magicHigh !== V8_CODE_CACHE_MAGIC_HIGH) unsupported( `Container magic 0x${magic.toString(16).padStart(8, "0")} does not carry the V8 code cache high half 0x${V8_CODE_CACHE_MAGIC_HIGH.toString(16)}; this file is not a V8 code cache.`, ); - const declaredPayload = field(5); - const payloadOffset = V8_CODE_CACHE_HEADER_BYTES; - const expectedPayload = bytes.length - payloadOffset; - if (declaredPayload !== expectedPayload) + // The declared payload length gives the candidate aligned header extent. + const declaredPayload = fields[5]!.value; + const payloadOffset = bytes.length - declaredPayload; + if (!V8_CODE_CACHE_HEADER_SIZES.includes(payloadOffset)) malformed( - `Header declares a ${String(declaredPayload)}-byte payload but ${String(expectedPayload)} bytes follow the ${String(V8_CODE_CACHE_HEADER_BYTES)}-byte header; the container is truncated or corrupt.`, + `Header declares a ${String(declaredPayload)}-byte payload, leaving ${String(payloadOffset)} header bytes, which is no admitted V8 code cache header size (${V8_CODE_CACHE_HEADER_SIZES.join(" or ")}); the container is truncated or corrupt.`, + ); + // Node v24.22.1's SerializedCodeData writer in code-serializer.cc zeroes + // the alignment bytes after its words. A missing final wide payload word + // and a narrow payload beginning with a zero word are indistinguishable here. + if ( + payloadOffset === V8_CODE_CACHE_NARROW_HEADER_BYTES && + bytes.length >= V8_CODE_CACHE_HEADER_BYTES && + headerReader.u32(V8_CODE_CACHE_NARROW_HEADER_BYTES) === 0 + ) + malformed( + "A 28-byte header extent followed by a zero word is ambiguous: the file may have a zero-leading narrow payload or a truncated 32-byte layout.", ); - const sourceWord = field(2); + if (payloadOffset === V8_CODE_CACHE_HEADER_BYTES) + fields.push(readField(HEADER_ROLES[commonFieldCount]!, commonFieldCount)); + + const sourceWord = fields[2]!.value; const sourceLength = sourceWord & V8_CODE_CACHE_SOURCE_LENGTH_MASK; // Bit 30 marks a `vm.SourceTextModule` cache and bit 29 a `vm.compileFunction` one. // Measured on Node 24.22.1, a 19-unit module source reads `0x40000013` while a script of @@ -162,13 +190,8 @@ export const parseV8CodeCache = ( header: { magic, magic_build_stable: magicHigh, - fields: HEADER_ROLES.map((entry, index) => ({ - offset: index * 4, - value: field(index), - role: entry.role, - status: entry.status, - })), - header_bytes: V8_CODE_CACHE_HEADER_BYTES, + fields, + header_bytes: payloadOffset, source_length: sourceLength, producer, }, diff --git a/tests/acceptance/v8CodeCacheCli.test.ts b/tests/acceptance/v8CodeCacheCli.test.ts index a60713fa34..89737816ba 100644 --- a/tests/acceptance/v8CodeCacheCli.test.ts +++ b/tests/acceptance/v8CodeCacheCli.test.ts @@ -3,34 +3,44 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; import { toolContract } from "../../src/contracts/toolContracts.js"; -import { v8CodeCacheFixture } from "../../src/v8/V8CodeCache.fixture.js"; +import { + v8CodeCacheFixture, + withSyntheticNarrowHeader, +} from "../../src/v8/V8CodeCache.fixture.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; const outputSchema = toolContract("inspect_v8_code_cache").outputSchema; cliTest( - "reports the observed header and payload through the public CLI", + "reports wide and synthetic narrow header extents through the public CLI", async ({ cli }) => { const root = await createTestTempDirectory("rea-v8-cli-"); - const path = join(root, "module.jsc"); - const bytes = v8CodeCacheFixture( - "function add(a, b) { return a + b; } add(1, 2);", - ); - await writeFile(path, bytes); - const result = await cli.run({ - arguments: ["inspect-v8-code-cache", path, "--json"], - }); - expect(result.exitCode, result.stderr).toBe(0); - const evidence = outputSchema.parse(result.json); - const report = evidence.normalized_result; - expect(report.header.magic).toBe(bytes.readUInt32LE(0)); - expect(report.header.magic_build_stable).toBe(0xc0de); - expect(report.header.fields).toHaveLength(8); - expect(report.payload.offset).toBe(32); - expect(report.payload.bytes).toBe(bytes.length - 32); - expect(report.payload.sha256).toMatch(/^[0-9a-f]{64}$/u); - expect(report.coverage.status).toBe("complete"); + const wide = v8CodeCacheFixture(); + const narrow = withSyntheticNarrowHeader(wide); + const payloadDigest = createHash("sha256") + .update(wide.subarray(32)) + .digest("hex"); + for (const [bytes, headerBytes] of [ + [wide, 32], + [narrow, 28], + ] as const) { + const path = join(root, `header-${String(headerBytes)}.jsc`); + await writeFile(path, bytes); + const result = await cli.run({ + arguments: ["inspect-v8-code-cache", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const report = outputSchema.parse(result.json).normalized_result; + expect(report.header.magic).toBe(bytes.readUInt32LE(0)); + expect(report.header.magic_build_stable).toBe(0xc0de); + expect(report.header.header_bytes).toBe(headerBytes); + expect(report.header.fields).toHaveLength(headerBytes / 4); + expect(report.payload.offset).toBe(headerBytes); + expect(report.payload.bytes).toBe(bytes.length - headerBytes); + expect(report.payload.sha256).toBe(payloadDigest); + expect(report.coverage.status).toBe("complete"); + } }, );