From 673bd049b7d453a6e532cd70508df8a1c684942d Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:22:54 -0500 Subject: [PATCH] fix(flutter): inspect unified Dart AOT snapshot profiles (#12480) * fix(flutter): inspect unified Dart AOT snapshot profiles Port the unified Dart SDK layout from #3662 and resolve profiles from one dynamic-symbol inventory and the physical snapshot headers. Refs #3629. Co-authored-by: Stefano Rizzello * fix(flutter): retain valid pools beside malformed snapshot exports --------- Co-authored-by: Stefano Rizzello --- docs/guides/android/flutter-analysis.md | 32 ++- src/contracts/flutter/flutterToolContracts.ts | 2 +- src/domain/flutter/flutterBuildAnalysis.ts | 7 + src/flutter/DartElf.test.ts | 11 +- src/flutter/DartElf.ts | 23 +- src/flutter/DartSnapshotProfile.ts | 216 ++++++++++++++++++ src/flutter/FlutterBuild.fixture.ts | 72 +++++- src/flutter/FlutterBuildProvider.ts | 171 ++------------ tests/acceptance/flutterAnalysis.test.ts | 116 +++++++++- .../filesystem/flutterBuildProvider.test.ts | 113 +++++---- tests/boundary/mcp/dartAotSummaryMcp.test.ts | 8 +- 11 files changed, 526 insertions(+), 245 deletions(-) create mode 100644 src/flutter/DartSnapshotProfile.ts diff --git a/docs/guides/android/flutter-analysis.md b/docs/guides/android/flutter-analysis.md index 0e7da6fe9f..be83a16453 100644 --- a/docs/guides/android/flutter-analysis.md +++ b/docs/guides/android/flutter-analysis.md @@ -57,17 +57,14 @@ server; older servers keep the complete request after schema discovery. sections, which carry the `f5f5dcdc` magic — the parsed header kind and length (the stored length excludes the four magic bytes). Data headers whose declared snapshot length does not fit their symbol retain their - observed fields and report partial coverage. Complete structural coverage - currently requires kind 3, the FullAOT value in the supported - [Dart 2.14 layout](https://github.com/dart-lang/sdk/blob/2.14.0/runtime/vm/snapshot.h). - Kind numbers vary across Dart releases; other values are preserved with - partial coverage, without guessing their interpretation. - Unified `_kDartSnapshotData` / `_kDartSnapshotText` exports are a different - unsupported profile. The [upstream VM-isolate removal](https://github.com/dart-lang/sdk/commit/d36adbacafee01d9852cf8e960cf2d8654d91e7e) - changes both the source layout and the FullAOT kind value. REA reports the - observed export names and library identity with a typed unsupported-profile - refusal when only unified exports are available; it does not alias one header - into two independent sources. + observed fields and report partial coverage. `libapp.snapshot_profile` + identifies `legacy-split` for the kind 3 FullAOT layout in Dart 2.14 or + `unified` for the kind 2 FullAOT layout from the VM-isolate removal. It is + `null` when the data headers leave the profile unresolved. Older Evidence + can omit the field. Independent, conflicting profiles retain their source + exports and hashes with partial coverage and an unselected string pool. + [Dart 2.14 header](https://github.com/dart-lang/sdk/blob/2.14.0/runtime/vm/snapshot.h) + · [Dart SDK unified layout change](https://github.com/dart-lang/sdk/commit/d36adbacafee01d9852cf8e960cf2d8654d91e7e) Address resolution examines every overlapping `PT_LOAD` interpretation, including partial overlaps. Equivalent mappings are coalesced; conflicting mappings leave affected symbols unresolved and qualify coverage. Dynamic @@ -75,10 +72,11 @@ server; older servers keep the complete request after schema discovery. A payload without exported snapshot symbols is refused rather than guessed at. - **The snapshot hash** from the header at the start of each exported data - symbol. Complete hash coverage requires a valid header from both the VM - and isolate; duplicate records inside one symbol cannot stand in for the - other's header. Aliased or overlapping data symbols report partial coverage. -- **A string-pool projection from the isolate data section**: distinct + symbol. The split profile needs independent VM and isolate headers. The + unified profile needs one header, and aliases published at the same + role's file range count as one source. +- **A string-pool projection from the selected data section** uses the split + isolate data or unified snapshot data. It includes distinct `package:` source URIs (the app's own and its dependencies' Dart files — a dependency inventory), `dart:` SDK URIs (which SDK libraries the app uses), and identifier-shaped tokens, each bounded with counts and @@ -95,13 +93,13 @@ server; older servers keep the complete request after schema discovery. negative answer reports complete coverage: absence is an answer. - **`snapshot_hash`** is the Dart build hash observed 20 bytes after the snapshot magic (`f5 f5 dc dc`) inside `libapp.so`. Identification scans - byte patterns; AOT inspection reads the exported VM and isolate headers. + byte patterns, while AOT inspection reads headers at the exported data boundaries. `snapshot_hash_sources` counts the valid records observed by the chosen operation, and when they **disagree** the distinct values are kept in `snapshot_hash_candidates` with `snapshot_hash: null` and `coverage: "partial"` rather than silently picking one. Identification can retain a single byte-scanned hash from a unified payload; - its partial status does not establish truncation or support for that profile. + its partial status describes the byte scan's coverage. - **`elf_header_valid`** checks the supported little-endian ELF32/ELF64 header, table entry widths, and full table extents against the library's actual byte length. Truncated, malformed, or unsupported headers report diff --git a/src/contracts/flutter/flutterToolContracts.ts b/src/contracts/flutter/flutterToolContracts.ts index d2e0516d5a..cec3eabe2f 100644 --- a/src/contracts/flutter/flutterToolContracts.ts +++ b/src/contracts/flutter/flutterToolContracts.ts @@ -44,7 +44,7 @@ export const FLUTTER_TOOL_CONTRACTS = [ }), ), description: - "Inspect one APK ABI's legacy split VM/isolate Dart AOT snapshot without executing it. Structural coverage supports Dart 2.14 FullAOT kind 3; unified snapshot layouts are unsupported. Returns snapshot exports/headers/hash and bounded package:/dart:/identifier-like byte-pattern strings, not deserialized classes/functions. pool_policy.contains selects strings before collection; other pool budgets do not raise APK/ELF/response limits. Default complete returns all facts; detail summary retains them for inspect_analysis_view kind dart-aot, collections package_uris/dart_uris/class_like_tokens, using parent_evidence_id and row paging. Counts are lower bounds and page exhaustion never proves complete pool coverage.", + "Inspect one APK ABI's Dart AOT snapshot without executing it. Supports legacy split VM/isolate FullAOT kind 3 and unified FullAOT kind 2. Returns the observed profile, snapshot exports, headers, hashes and bounded package:/dart:/identifier-like byte-pattern strings. pool_policy.contains selects strings before collection; other pool budgets do not raise APK/ELF/response limits. Default complete returns all facts; detail summary retains them for inspect_analysis_view kind dart-aot, collections package_uris/dart_uris/class_like_tokens, using parent_evidence_id and row paging. Counts are lower bounds and page exhaustion never proves complete pool coverage.", kind: "flutter-provider", inputSchema: dartAotInspectionInputSchema, outputSchema: evidenceResultOf( diff --git a/src/domain/flutter/flutterBuildAnalysis.ts b/src/domain/flutter/flutterBuildAnalysis.ts index 9c44cdb0c4..42e0587c55 100644 --- a/src/domain/flutter/flutterBuildAnalysis.ts +++ b/src/domain/flutter/flutterBuildAnalysis.ts @@ -239,6 +239,13 @@ export const flutterResultSchemas = { snapshot_hash_candidates: z.array(z.string().regex(/^[0-9a-f]{32}$/u)), /** Distinct exported data headers with a valid hash at the header's fixed offset. */ snapshot_hash_sources: z.int().nonnegative(), + snapshot_profile: z + .enum(["legacy-split", "unified"]) + .nullable() + .exactOptional() + .describe( + "Export profile supported by the observed headers. Null means unresolved. Older Evidence may omit it.", + ), /** Snapshot symbols read from the dynamic symbol table. */ sections: z.array( z.strictObject({ diff --git a/src/flutter/DartElf.test.ts b/src/flutter/DartElf.test.ts index d07b124f0c..a5cba91f38 100644 --- a/src/flutter/DartElf.test.ts +++ b/src/flutter/DartElf.test.ts @@ -379,6 +379,7 @@ describe("stripped ELF symbol-table ownership", () => { reason: expect.stringMatching( /_kDartIsolateSnapshotData.*not in the dynamic symbol table/i, ), + missingSymbol: "_kDartIsolateSnapshotData", }); image.writeBigUInt64LE(0x60000001n, dynamic + 4 * 16); // No recognized count table. expect( @@ -568,7 +569,10 @@ it.each([256, 257])( : { symbols: [], failures: [ - { reason: `symbol ${name} is not in the dynamic symbol table` }, + { + reason: `symbol ${name} is not in the dynamic symbol table`, + missingSymbol: name, + }, ], }, ); @@ -596,7 +600,10 @@ it("checks raw symbol precision only after definition and requested-name selecti expect(await readElfSymbols(bytes, ["unselected"])).toEqual({ symbols: [], failures: [ - { reason: "symbol unselected is not in the dynamic symbol table" }, + { + reason: "symbol unselected is not in the dynamic symbol table", + missingSymbol: "unselected", + }, ], }); }); diff --git a/src/flutter/DartElf.ts b/src/flutter/DartElf.ts index a8d17c6911..6f5d81332b 100644 --- a/src/flutter/DartElf.ts +++ b/src/flutter/DartElf.ts @@ -76,6 +76,8 @@ export interface ElfSymbol { export interface ElfParseFailure { readonly reason: string; + /** Requested name for an ordinary missing definition; other failures are structural. */ + readonly missingSymbol?: string; } const SHT_DYNSYM = 11; @@ -526,12 +528,20 @@ export const readElfSymbols = async ( failures.add(`Symbol ${name} has conflicting definitions`); } for (const name of unresolved) symbols.delete(name); - for (const name of wanted) - if (!symbols.has(name) && !ambiguous.has(name) && !unresolved.has(name)) - failures.add(`symbol ${name} is not in the dynamic symbol table`); return { symbols: [...symbols.values()], - failures: [...failures].map((reason) => ({ reason })), + failures: [ + ...[...failures].map((reason) => ({ reason })), + ...[...wanted] + .filter( + (name) => + !symbols.has(name) && !ambiguous.has(name) && !unresolved.has(name), + ) + .map((name) => ({ + reason: `symbol ${name} is not in the dynamic symbol table`, + missingSymbol: name, + })), + ], }; }; @@ -571,13 +581,12 @@ export const readSnapshotHeader = ( // Dart's stored length excludes the four magic bytes and includes the // 20-byte fixed header and the version hash. Aligned data may follow it // inside the exported symbol, but the serialized snapshot must fit. - // Kind 3 is FullAOT in the supported Dart 2.14 layout; enum values change - // across SDK versions, so other kinds remain uninterpreted observations. + // The export profile interprets the kind. Its enum values vary by producer. const complete = headerLength !== null && headerLength >= SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH - 4 && headerLength <= bytes.length - offset - 4 && - kind === 3 && + kind !== null && hash !== null; return { magicValid: true, kind, headerLength, hash, complete }; }; diff --git a/src/flutter/DartSnapshotProfile.ts b/src/flutter/DartSnapshotProfile.ts new file mode 100644 index 0000000000..d46a06c5e9 --- /dev/null +++ b/src/flutter/DartSnapshotProfile.ts @@ -0,0 +1,216 @@ +import { + readElfSymbols, + readSnapshotHeader, + type ElfSymbol, +} from "./DartElf.js"; + +const LEGACY = { + name: "legacy-split", + data: ["_kDartVmSnapshotData", "_kDartIsolateSnapshotData"], + text: ["_kDartVmSnapshotInstructions", "_kDartIsolateSnapshotInstructions"], + pool: "_kDartIsolateSnapshotData", + kind: 3, +} as const; +const UNIFIED = { + name: "unified", + data: ["_kDartSnapshotData"], + text: ["_kDartSnapshotText"], + pool: "_kDartSnapshotData", + kind: 2, +} as const; + +type Profile = typeof LEGACY | typeof UNIFIED; +type Header = ReturnType; +const ALL_SYMBOLS = [ + ...LEGACY.data, + ...LEGACY.text, + ...UNIFIED.data, + ...UNIFIED.text, +]; +const DATA_SYMBOLS: ReadonlySet = new Set([ + ...LEGACY.data, + ...UNIFIED.data, +]); + +const overlap = (a: ElfSymbol, b: ElfSymbol): boolean => + a.offset < b.offset + b.size && b.offset < a.offset + a.size; + +const sameRange = ( + alias: ElfSymbol, + canonical: ElfSymbol | undefined, +): boolean => + canonical !== undefined && + alias.offset === canonical.offset && + alias.size === canonical.size; + +const profileFacts = ( + profile: Profile, + symbols: ReadonlyMap, + headers: ReadonlyMap, +) => { + const names: readonly string[] = [...profile.data, ...profile.text]; + const present = names.flatMap((name) => symbols.get(name) ?? []); + const data = profile.data.flatMap((name) => { + const symbol = symbols.get(name); + const header = headers.get(name); + return symbol !== undefined && header !== undefined + ? [{ symbol, header }] + : []; + }); + const validData = data.filter( + ({ header }) => header.complete && header.kind === profile.kind, + ); + const text = profile.text.map((name) => symbols.get(name)); + const aliased = data.some(({ symbol }, index) => + data + .slice(0, index) + .some((previous) => previous.symbol.offset === symbol.offset), + ); + const overlapping = data.some(({ symbol }, index) => + data.slice(0, index).some((previous) => overlap(previous.symbol, symbol)), + ); + const textOverlapsData = + profile === UNIFIED && + text.some( + (symbol) => + symbol !== undefined && + data.some((entry) => overlap(entry.symbol, symbol)), + ); + return { + profile, + names, + present, + data, + qualified: validData.length > 0, + poolUsable: validData.some(({ symbol }) => symbol.name === profile.pool), + complete: + validData.length === profile.data.length && + text.every((symbol) => symbol !== undefined && symbol.size > 0) && + !overlapping && + !textOverlapsData, + aliased, + overlapping, + textOverlapsData, + }; +}; + +/** One inventory owns the layout, extent and physical hash provenance for the report. */ +export const observeDartSnapshot = async ( + bytes: Buffer, + signal?: AbortSignal, +) => { + const inventory = await readElfSymbols(bytes, ALL_SYMBOLS, signal); + if (inventory.symbols.length === 0) + return { + observed: false as const, + reasons: inventory.failures.map(({ reason }) => reason), + }; + + const symbols = new Map( + inventory.symbols.map((symbol) => [symbol.name, symbol]), + ); + const headers = new Map(); + const physicalHeaders = new Map(); + const hashes = new Map(); + const sections = inventory.symbols.map(({ name, offset, size }) => { + let header: Header | undefined; + if (DATA_SYMBOLS.has(name)) { + const range = `${offset}:${size}`; + header = + physicalHeaders.get(range) ?? + readSnapshotHeader(bytes.subarray(offset, offset + size), 0); + physicalHeaders.set(range, header); + headers.set(name, header); + if (header.hash !== null) hashes.set(offset, header.hash); + } + return { + name, + offset, + size, + magic_valid: header?.magicValid ?? false, + kind: header?.kind ?? null, + header_length: header?.headerLength ?? null, + }; + }); + const candidates = [...new Set(hashes.values())]; + const legacy = profileFacts(LEGACY, symbols, headers); + const unified = profileFacts(UNIFIED, symbols, headers); + const mixed = legacy.present.length > 0 && unified.present.length > 0; + // The transition assembler publishes both older names for each canonical role. + const aliases = + mixed && + unified.qualified && + legacy.present.every((symbol) => + sameRange( + symbol, + symbols.get( + DATA_SYMBOLS.has(symbol.name) ? UNIFIED.data[0] : UNIFIED.text[0], + ), + ), + ); + let selected: typeof legacy | null = null; + if (!mixed) selected = legacy.present.length > 0 ? legacy : unified; + else if (aliases) selected = unified; + // A bounded, matching-kind pool header can establish a sole usable source + // even if the other layout's names resolve to invalid data or to text alone. + else if (legacy.poolUsable && !unified.qualified) selected = legacy; + else if (unified.poolUsable && !legacy.qualified) selected = unified; + const failures = inventory.failures.filter( + ({ missingSymbol }) => + missingSymbol === undefined || + selected?.names.includes(missingSymbol) === true, + ); + const limitations = failures.map(({ reason }) => reason); + if (mixed && !aliases) + limitations.push( + selected === null + ? "The legacy and unified exports do not establish one snapshot profile or string-pool source." + : "Additional snapshot exports have no verified alias to the selected profile.", + ); + if (aliases) + limitations.push( + "Legacy exports alias the unified text or data ranges. Each physical header counts once.", + ); + if (selected !== null) { + const { present, names, aliased, overlapping, textOverlapsData } = selected; + if (present.length < names.length) + limitations.push( + `Only ${present.length} of ${names.length} snapshot symbols were present`, + ); + if (aliased) + limitations.push( + "Two or more snapshot data symbols share one header offset; its hash counts as one source instead of two agreeing ones", + ); + else if (overlapping) + limitations.push( + "Snapshot data symbol ranges overlap; independent VM/isolate coverage is not established", + ); + if (textOverlapsData) + limitations.push("Unified snapshot text and data symbol ranges overlap."); + } + for (const { profile, data } of aliases ? [unified] : [legacy, unified]) + for (const { symbol, header } of data) + if (!header.complete || header.kind !== profile.kind) + limitations.push( + `${symbol.name} has an incomplete or invalid snapshot header: kind ${String(header.kind)} (AOT app requires ${profile.kind}), declared length ${String(header.headerLength)} excludes the four magic bytes, symbol size ${symbol.size}, valid hash ${String(header.hash !== null)}`, + ); + const pool = + selected === null ? undefined : symbols.get(selected.profile.pool); + return { + observed: true as const, + profile: selected?.qualified === true ? selected.profile.name : null, + pool: + pool === undefined + ? null + : bytes.subarray(pool.offset, pool.offset + pool.size), + complete: + selected?.complete === true && + (!mixed || aliases) && + failures.length === 0 && + candidates.length === 1 && + hashes.size === selected.profile.data.length, + sections, + hashes: { candidates, sources: hashes.size }, + limitations, + }; +}; diff --git a/src/flutter/FlutterBuild.fixture.ts b/src/flutter/FlutterBuild.fixture.ts index 8567b488c6..3c5f6a60a7 100644 --- a/src/flutter/FlutterBuild.fixture.ts +++ b/src/flutter/FlutterBuild.fixture.ts @@ -4,12 +4,16 @@ import { Buffer } from "node:buffer"; export const REFERENCE_HASH = "65817c30a78bb44c3dc3771876b6010a"; /** A synthetic AOT image with four symbols, two data sections, and a pool. */ -export const aotFixtureImage = (hash: string = REFERENCE_HASH): Buffer => { +export const aotFixtureImage = ( + hash: string = REFERENCE_HASH, + additionalSymbols: Parameters[0] = [], +): Buffer => { const elf = buildElf64Image([ { name: "_kDartVmSnapshotData", value: 0x1000, size: 52 }, { name: "_kDartVmSnapshotInstructions", value: 0x1800, size: 16 }, { name: "_kDartIsolateSnapshotData", value: 0x2000, size: 0x600 }, { name: "_kDartIsolateSnapshotInstructions", value: 0x2600, size: 16 }, + ...additionalSymbols, ]); const pool = Buffer.concat([ Buffer.from( @@ -294,13 +298,65 @@ export const strippedAotFixtureImage = ( }; /** A minimal Dart snapshot data section carrying a 32-hex hash. */ -export const snapshotSection = (hash: string): Buffer => - Buffer.concat([ - Buffer.from([ - 0xf5, 0xf5, 0xdc, 0xdc, 48, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, - ]), - Buffer.from(hash, "latin1"), - ]); +export const snapshotSection = (hash: string, kind = 3): Buffer => { + const header = Buffer.alloc(20); + header.writeUInt32LE(0xdcdcf5f5, 0); + header.writeBigUInt64LE(48n, 4); + header.writeBigUInt64LE(BigInt(kind), 12); + return Buffer.concat([header, Buffer.from(hash, "latin1")]); +}; + +/** Pinned unified ELF layout with optional legacy assembler aliases. */ +export const unifiedAotFixtureImage = ({ + includeText = true, + aliases = false, + kind = 2, +}: { + includeText?: boolean; + aliases?: boolean; + kind?: number; +} = {}): Buffer => { + const data = { value: 0x1000, size: 0x100 }; + const text = { value: 0x1100, size: 16 }; + const image = Buffer.alloc(text.value + text.size); + buildElf64Image([ + { name: "_kDartSnapshotData", ...data }, + ...(includeText ? [{ name: "_kDartSnapshotText", ...text }] : []), + ...(aliases + ? [ + { name: "_kDartVmSnapshotData", ...data }, + { name: "_kDartIsolateSnapshotData", ...data }, + { name: "_kDartVmSnapshotInstructions", ...text }, + { name: "_kDartIsolateSnapshotInstructions", ...text }, + ] + : []), + ]).copy(image); + snapshotSection(REFERENCE_HASH, kind).copy(image, data.value); + image.write("\0package:app/unified.dart\0dart:core\0", data.value + 52); + return image; +}; + +/** Distinct split and unified exports, with conflicting or malformed headers. */ +export const mixedAotFixtureImage = ( + malformed?: "legacy-split" | "unified", +): Buffer => { + const image = Buffer.alloc(0x2810); + aotFixtureImage(REFERENCE_HASH, [ + { + name: "_kDartSnapshotData", + value: 0x2700, + size: malformed === "unified" ? 4 : 0x100, + }, + { name: "_kDartSnapshotText", value: 0x2800, size: 16 }, + ]).copy(image); + snapshotSection("a".repeat(32), 2).copy(image, 0x2700); + image.write("\0package:app/mixed.dart\0", 0x2700 + 52); + if (malformed === "legacy-split") { + image.writeUInt32LE(0, 0x1000); + image.writeUInt32LE(0, 0x2000); + } + return image; +}; /** A real ELF container declaring GNU note ownership, with an unrelated payload prefix. */ export const engineFixtureImage = (options: { diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.ts index 966ed56445..7339d274ca 100644 --- a/src/flutter/FlutterBuildProvider.ts +++ b/src/flutter/FlutterBuildProvider.ts @@ -66,12 +66,8 @@ import { LabeledStringScanner, SnapshotHashScanner, } from "./FlutterPayloadScan.js"; -import { - ELF_HEADER_MAX_BYTES, - readElfHeader, - readElfSymbols, - readSnapshotHeader, -} from "./DartElf.js"; +import { ELF_HEADER_MAX_BYTES, readElfHeader } from "./DartElf.js"; +import { observeDartSnapshot } from "./DartSnapshotProfile.js"; import { readElfBuildIds } from "./ElfBuildId.js"; import { privateWorkspaceFailure } from "../process/privateWorkspaceFailure.js"; import { errorMessage } from "../kernel/errorMessage.js"; @@ -86,8 +82,6 @@ const APK_MAX_BYTES = 2 * 1024 * 1024 * 1024; // engine labels this keeps expanded result metadata below 512 KiB for ordinary // ABI names, independently of the archive's compressed-byte budget. const MAX_FLUTTER_ABIS = 32; -/** A complete AOT image carries exactly one VM and one isolate section. */ -const SYMBOL_PAIR_COUNT = 2; const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/u; /** Each release-fixed Flutter ceiling with the value that refused the input. */ @@ -1258,124 +1252,21 @@ export class FlutterBuildProvider { } assertArtifactReadActive(signal); const bounded = image.subarray(0, imageLength); - const symbolNames = [ - "_kDartVmSnapshotData", - "_kDartVmSnapshotInstructions", - "_kDartIsolateSnapshotData", - "_kDartIsolateSnapshotInstructions", - ]; - const sections: { - name: string; - offset: number; - size: number; - magic_valid: boolean; - kind: number | null; - header_length: number | null; - }[] = []; - const dataHeaders: { - name: string; - offset: number; - size: number; - header: ReturnType; - }[] = []; - let isolateData: Buffer | null = null; - const inventory = await readElfSymbols(bounded, symbolNames, signal); - for (const symbol of inventory.symbols) { - const name = symbol.name; - const header = name.endsWith("Data") - ? readSnapshotHeader( - bounded.subarray(symbol.offset, symbol.offset + symbol.size), - 0, - ) - : null; - sections.push({ - name, - offset: symbol.offset, - size: symbol.size, - magic_valid: header?.magicValid ?? false, - kind: header?.kind ?? null, - header_length: header?.headerLength ?? null, - }); - if (header !== null) dataHeaders.push({ ...symbol, header }); - if (name === "_kDartIsolateSnapshotData") - isolateData = image.subarray( - symbol.offset, - symbol.offset + symbol.size, - ); - } - // Each exported data symbol owns one header at its start. Matching - // records elsewhere in a symbol are not evidence for the other - // symbol's hash. Count a physical header only once for aliased exports. - const observedOffsets = new Set(); - let aliasedDataSymbols = false; - const hashes: string[] = []; - for (const section of dataHeaders) { - if (observedOffsets.has(section.offset)) { - aliasedDataSymbols = true; - continue; - } - observedOffsets.add(section.offset); - if (section.header.hash !== null) hashes.push(section.header.hash); - } - const hashScan = { - sources: hashes.length, - candidates: [...new Set(hashes)], - }; - const overlappingDataSymbols = dataHeaders.some((section, index) => - dataHeaders - .slice(0, index) - .some( - (previous) => - previous.offset < section.offset + section.size && - section.offset < previous.offset + previous.size, - ), - ); - if (sections.length === 0) { - // This is a profile diagnostic, not aliases for the split data sources. - // Probe only after the legacy selection fails, leaving its normal path - // and two-source completeness rule unchanged. - const unified = await readElfSymbols( - bounded, - ["_kDartSnapshotData", "_kDartSnapshotText"], - signal, - ); - if (unified.symbols.length > 0) - return err( - new AnalysisUnsupportedTargetError( - "inspect_dart_aot", - path, - "Observed unified Dart snapshot exports; this reader supports the legacy split VM/isolate profile (Dart 2.14 FullAOT kind 3). The unified profile is unsupported, not missing legacy data", - { - diagnostics: { - supported_profile: "dart-2.14-split-full-aot", - observed_exports: unified.symbols.map( - ({ name, offset, size }) => ({ name, offset, size }), - ), - abi: selected.abi, - libapp_sha256: imageSha256, - libapp_bytes: imageLength, - }, - }, - ), - ); + const snapshotFacts = await observeDartSnapshot(bounded, signal); + if (!snapshotFacts.observed) return err( new AnalysisUnsupportedTargetError( "inspect_dart_aot", path, - `No recognizable legacy split Dart snapshot symbols were found: ${inventory.failures.map((failure) => failure.reason).join("; ")}`, + `No recognizable Dart snapshot symbols were found: ${snapshotFacts.reasons.join("; ")}`, ), ); - } - const pool = await projectStringPool(isolateData, signal, poolPolicy); - const snapshotPartial = - inventory.failures.length > 0 || - aliasedDataSymbols || - overlappingDataSymbols || - sections.length < symbolNames.length || - dataHeaders.length !== SYMBOL_PAIR_COUNT || - dataHeaders.some((section) => !section.header.complete) || - hashScan.candidates.length !== 1 || - hashScan.sources !== SYMBOL_PAIR_COUNT; + const pool = await projectStringPool( + snapshotFacts.pool, + signal, + poolPolicy, + ); + const snapshotPartial = !snapshotFacts.complete; const poolBudgetsReached = new Set(pool.limitsReached); if ( pool.packageUriCount > poolPolicy.uri_limit || @@ -1385,7 +1276,7 @@ export class FlutterBuildProvider { if (pool.classLikeTokenCount > poolPolicy.token_limit) poolBudgetsReached.add("token_limit"); const poolPartial = - isolateData === null || + snapshotFacts.pool === null || pool.collectionCapped || pool.packageUriCount > poolPolicy.uri_limit || pool.dartUriCount > poolPolicy.uri_limit || @@ -1400,10 +1291,13 @@ export class FlutterBuildProvider { bytes: imageLength, sha256: imageSha256, snapshot_hash: - hashScan.candidates.length === 1 ? hashScan.candidates[0]! : null, - snapshot_hash_candidates: [...hashScan.candidates], - snapshot_hash_sources: hashScan.sources, - sections, + snapshotFacts.hashes.candidates.length === 1 + ? snapshotFacts.hashes.candidates[0]! + : null, + snapshot_hash_candidates: snapshotFacts.hashes.candidates, + snapshot_hash_sources: snapshotFacts.hashes.sources, + snapshot_profile: snapshotFacts.profile, + sections: snapshotFacts.sections, }, string_pool: { policy: { ...poolPolicy }, @@ -1435,32 +1329,11 @@ export class FlutterBuildProvider { limitations: [ "The APK is read through an owned read-only snapshot; concurrent changes to the original cannot mix into this observation", "Snapshot sections are located through the ELF dynamic symbol table; a payload without exported snapshot symbols is refused rather than guessed", - "Snapshot hash sources are the headers at the start of the VM and isolate data symbols; complete decoding supports kind 3 (the Dart 2.14 FullAOT layout), a valid hash and a declared length that fits its symbol, including the four magic bytes; other kind values remain observed with partial coverage", - "String-pool entries are byte-pattern observations from the isolate data section, not deserialized cluster semantics; typed class and function recovery needs an SDK-specific parser", + "Snapshot hash sources count distinct physical headers. FullAOT kind 3 supports the legacy split profile and kind 2 supports the unified profile when the corresponding exports and header extents agree", + "String-pool entries are byte-pattern observations from the selected snapshot data symbol", "class_like_tokens are identifier-shaped runs and include incidental matches", "URI/token counts are lower bounds for runs matching pool_policy.contains: distinct collection stops at twice each selected projection bound. printable_run_count counts complete printable runs before filtering; overflowed runs are omitted, never fabricated as prefixes", - ...inventory.failures.map((failure) => failure.reason), - ...(sections.length < symbolNames.length - ? [ - `Only ${String(sections.length)} of 4 snapshot symbols were present`, - ] - : []), - ...(aliasedDataSymbols - ? [ - "Two or more snapshot data symbols share one header offset; its hash counts as one source instead of two agreeing ones", - ] - : []), - ...(overlappingDataSymbols && !aliasedDataSymbols - ? [ - "Snapshot data symbol ranges overlap; independent VM/isolate coverage is not established", - ] - : []), - ...dataHeaders - .filter((section) => !section.header.complete) - .map( - (section) => - `${section.name} has an incomplete or invalid snapshot header: kind ${String(section.header.kind)} (AOT app requires 3), declared length ${String(section.header.headerLength)} excludes the four magic bytes, symbol size ${String(section.size)}, valid hash ${String(section.header.hash !== null)}`, - ), + ...snapshotFacts.limitations, ...pool.limitsReached.map( (limit) => `String-pool admission reached pool_policy.${limit}=${String(poolPolicy[limit])}. Retry with a narrower pool_policy.contains or increase ${limit}; string_pool.limits records the control and no REA restart is required. Counts remain lower bounds and overflowed runs are omitted. APK, library and response limits are unchanged`, diff --git a/tests/acceptance/flutterAnalysis.test.ts b/tests/acceptance/flutterAnalysis.test.ts index 08240150dc..5602bb2bf5 100644 --- a/tests/acceptance/flutterAnalysis.test.ts +++ b/tests/acceptance/flutterAnalysis.test.ts @@ -3,7 +3,7 @@ import { compressedElfNoteSectionFixture, } from "../../src/native/elf/ElfNotes.fixture.js"; import { createHash } from "node:crypto"; -import { expect } from "vitest"; +import { expect, onTestFinished } from "vitest"; import { toolContract } from "../../src/contracts/toolContracts.js"; import { parseEvidence } from "../../src/domain/evidence.js"; import { flutterResultSchemas } from "../../src/domain/flutter/flutterBuildAnalysis.js"; @@ -13,17 +13,23 @@ import { engineFixtureImage, REFERENCE_HASH, appendElfRanges, + mixedAotFixtureImage, + unifiedAotFixtureImage, } from "../../src/flutter/FlutterBuild.fixture.js"; import { createFlutterApk, createDuplicateFlutterApk, } from "../fixtures/flutterApk.js"; import { lazyLocalToolsMcp } from "../fixtures/localToolsMcp.js"; +import { createMcpSchemaValidation } from "../fixtures/mcpSchemaValidation.js"; import { expectCliMcpEvidenceParity } from "../fixtures/cliMcpEvidenceParity.js"; import { parseMcpToolError } from "../fixtures/mcpToolError.js"; import { cliTest } from "../support/cli/cliFixture.js"; const connectLocalToolsMcp = lazyLocalToolsMcp(); +const connectProfileMcp = lazyLocalToolsMcp({ + REA_MCP_OUTPUT_SCHEMA_PROFILE: "compact", +}); cliTest( "CLI and stdio MCP preserve AOT facts and exact artifact identity across ignored DT_BIND_NOW values", @@ -58,6 +64,7 @@ cliTest( coverage: "complete", snapshot_hash: REFERENCE_HASH, snapshot_hash_sources: 2, + snapshot_profile: "legacy-split", }, string_pool: { coverage: "complete", @@ -80,6 +87,113 @@ cliTest( }, ); +cliTest( + "CLI and MCP preserve unified aliases and conflicting Dart profiles", + async ({ cli }) => { + const { client, call } = await connectProfileMcp(); + const tool = (await client.listTools()).tools.find( + ({ name }) => name === "inspect_dart_aot", + ); + if (tool?.outputSchema === undefined) + throw new Error("Missing advertised AOT schema"); + const { assertions, clear } = createMcpSchemaValidation(); + onTestFinished(clear); + for (const test of [ + { + label: "unified", + image: unifiedAotFixtureImage(), + profile: "unified", + sources: 1, + hash: REFERENCE_HASH, + sections: 2, + coverage: "complete", + pool: ["package:app/unified.dart"], + }, + { + label: "aliases", + image: unifiedAotFixtureImage({ aliases: true }), + profile: "unified", + sources: 1, + hash: REFERENCE_HASH, + sections: 6, + coverage: "complete", + pool: ["package:app/unified.dart"], + }, + { + label: "mixed", + image: mixedAotFixtureImage(), + profile: null, + sources: 3, + hash: null, + sections: 6, + coverage: "partial", + pool: [], + }, + { + label: "malformed-unified", + image: mixedAotFixtureImage("unified"), + profile: "legacy-split", + sources: 2, + hash: REFERENCE_HASH, + sections: 6, + coverage: "partial", + pool: [ + "package:adaptive_breakpoints/src/adaptive_breakpoints.dart", + "package:animations/src/fade_scale_transition.dart", + ], + malformed: { name: "_kDartSnapshotData", size: 4, kind: null }, + }, + { + label: "malformed-legacy", + image: mixedAotFixtureImage("legacy-split"), + profile: "unified", + sources: 1, + hash: "a".repeat(32), + sections: 6, + coverage: "partial", + pool: ["package:app/mixed.dart"], + malformed: { name: "_kDartIsolateSnapshotData", magic_valid: false }, + }, + ]) { + const path = await createFlutterApk(`${test.label}.apk`, [ + { path: "lib/x86_64/libapp.so", bytes: test.image }, + ]); + const cliReply = await cli.run({ + arguments: ["inspect-dart-aot", path, "--json"], + }); + expect(cliReply.exitCode, cliReply.stderr).toBe(0); + const evidence = toolContract("inspect_dart_aot").outputSchema.parse( + cliReply.json, + ); + const reply = await call("inspect_dart_aot", { path }); + expect(reply.isError, JSON.stringify(reply)).not.toBe(true); + expect( + assertions.validate(tool.outputSchema, reply.structuredContent), + JSON.stringify(assertions.errors), + ).toBe(true); + expectCliMcpEvidenceParity(evidence, reply.structuredContent, path); + const report = flutterResultSchemas.inspect_dart_aot.parse( + evidence.normalized_result, + ); + expect(report.libapp).toMatchObject({ + coverage: test.coverage, + snapshot_profile: test.profile, + snapshot_hash_sources: test.sources, + snapshot_hash: test.hash, + sha256: createHash("sha256").update(test.image).digest("hex"), + }); + expect(report.libapp.sections).toHaveLength(test.sections); + expect(report.string_pool.package_uris).toEqual(test.pool); + if (test.malformed !== undefined) { + expect(report.libapp.sections).toContainEqual( + expect.objectContaining(test.malformed), + ); + expect(report.string_pool.coverage).toBe("complete"); + } + } + }, +); + cliTest( "CLI and stdio MCP retain Flutter identity, selected ABI and duplicate-member refusals", async ({ cli }) => { diff --git a/tests/boundary/filesystem/flutterBuildProvider.test.ts b/tests/boundary/filesystem/flutterBuildProvider.test.ts index e09c1ab927..17e8b35ab3 100644 --- a/tests/boundary/filesystem/flutterBuildProvider.test.ts +++ b/tests/boundary/filesystem/flutterBuildProvider.test.ts @@ -20,6 +20,7 @@ import { buildElf64Image, REFERENCE_HASH, snapshotSection, + unifiedAotFixtureImage, } from "../../../src/flutter/FlutterBuild.fixture.js"; import { FlutterBuildProvider } from "../../../src/flutter/FlutterBuildProvider.js"; import { FlutterBuildAnalysisService } from "../../../src/application/flutter/FlutterBuildAnalysisService.js"; @@ -130,71 +131,65 @@ const analyzeImage = async (bytes: Buffer, operation: FlutterOperation) => { return result.value; }; -it.each([false, true])( - "qualifies unified snapshot exports without aliasing legacy sources (text=%s)", - async (includeText) => { - const symbols = [ - { name: "_kDartSnapshotData", value: 0x1000, size: 52 }, - ...(includeText - ? [{ name: "_kDartSnapshotText", value: 0x1100, size: 16 }] - : []), - ]; - const image = Buffer.alloc(0x1110); - buildElf64Image(symbols).copy(image); - const data = snapshotSection(REFERENCE_HASH); - data.writeBigUInt64LE(2n, 12); // Pinned unified producer enum; support is not inferred. - data.copy(image, 0x1000); - const path = await buildApk("unified.apk", [ - { path: "lib/arm64-v8a/libapp.so", bytes: image }, - ]); - const provider = new FlutterBuildProvider(); - onTestFinished(() => provider.close()); - const inspected = await provider.execute({ - operation: "inspect_dart_aot", - input: { path }, - }); - expect(inspected.ok).toBe(false); - if (inspected.ok) - throw new Error("Unified profile was admitted as split VM/isolate"); - expect(projectAnalysisError(inspected.error)).toMatchObject({ - code: "unsupported_target", - category: "unsupported_target", - details: { - diagnostics: { - supported_profile: "dart-2.14-split-full-aot", - observed_exports: symbols.map(({ name, value, size }) => ({ - name, - offset: value, - size, - })), - abi: "arm64-v8a", - libapp_bytes: image.length, - libapp_sha256: expect.stringMatching(/^[a-f0-9]{64}$/u), - }, - }, - }); - const identified = await provider.execute({ - operation: "identify_flutter_build", - input: { path }, - }); - if (!identified.ok) throw identified.error; - const value = flutterResultSchemas.identify_flutter_build.parse( - identified.value.result, +it("keeps byte-scanned build identification partial for a unified payload", async () => { + const identified = await analyzeImage( + unifiedAotFixtureImage(), + "identify_flutter_build", + ); + const value = flutterResultSchemas.identify_flutter_build.parse( + identified.result, + ); + expect(value.coverage).toBe("partial"); + expect(value.abis[0]?.libapp).toMatchObject({ + snapshot_hash: REFERENCE_HASH, + snapshot_hash_sources: 1, + }); + expect(identified.limitations.join(" ")).toContain( + "supported legacy split VM/isolate profile", + ); + expect(identified.limitations.join(" ")).not.toContain("truncated"); +}); + +it.each([ + { includeText: false, kind: 2, expectedProfile: "unified" }, + { includeText: true, kind: 3, expectedProfile: null }, +] as const)( + "retains partial unified observations (text=$includeText, kind=$kind)", + async ({ includeText, kind, expectedProfile }) => { + const result = await analyzeImage( + unifiedAotFixtureImage({ includeText, kind }), + "inspect_dart_aot", ); - expect(value.coverage).toBe("partial"); - expect(value.abis[0]?.libapp).toMatchObject({ - snapshot_hash: REFERENCE_HASH, + const report = flutterResultSchemas.inspect_dart_aot.parse(result.result); + expect(report.libapp).toMatchObject({ + coverage: "partial", + snapshot_profile: expectedProfile, snapshot_hash_sources: 1, + sections: expect.arrayContaining([ + expect.objectContaining({ name: "_kDartSnapshotData", kind }), + ]), }); - expect(identified.value.limitations.join(" ")).toContain( - "supported legacy split VM/isolate profile", - ); - expect(identified.value.limitations.join(" ")).not.toContain( - "library is truncated", - ); + expect(report.string_pool.package_uris).toEqual([ + "package:app/unified.dart", + ]); }, ); +it("keeps a lone unified text marker from overriding a complete split observation", async () => { + const image = aotFixtureImage(REFERENCE_HASH, [ + { name: "_kDartSnapshotText", value: 0x2600, size: 16 }, + ]); + const result = await analyzeImage(image, "inspect_dart_aot"); + const report = flutterResultSchemas.inspect_dart_aot.parse(result.result); + expect(report.libapp).toMatchObject({ + snapshot_profile: "legacy-split", + coverage: "partial", + snapshot_hash_sources: 2, + }); + expect(report.libapp.sections).toHaveLength(5); + expect(report.string_pool.package_uri_count_at_least).toBe(2); +}); + it.each([32, 64] as const)( "reads only ELF-owned notes in an ELF%s engine", async (bits) => { diff --git a/tests/boundary/mcp/dartAotSummaryMcp.test.ts b/tests/boundary/mcp/dartAotSummaryMcp.test.ts index 2e9e635d4b..78fb0deae2 100644 --- a/tests/boundary/mcp/dartAotSummaryMcp.test.ts +++ b/tests/boundary/mcp/dartAotSummaryMcp.test.ts @@ -246,7 +246,9 @@ it("preserves null snapshot facts and pool lower bounds after exhaustion, reject limitations: ["Original uncertainty"], }, ); - for (const parent of [evidence(), evidence(report, null)]) { + for (const stored of [evidence(), evidence(report, null)]) { + const parent = parseEvidence(JSON.parse(JSON.stringify(stored))); + expect(parent.evidence_id).toBe(stored.evidence_id); const summary = await inspectAnalysisView({ source: { kind: "inline", evidence: parent }, view: { kind: "summary" }, @@ -256,6 +258,7 @@ it("preserves null snapshot facts and pool lower bounds after exhaustion, reject summary.value.normalized_result, ); expect(result.summary.libapp.snapshot_hash).toBeNull(); + expect(result.summary.libapp).not.toHaveProperty("snapshot_profile"); expect(result.summary.string_pool.package_uri_count_at_least).toBe(1000); expect(result.summary.string_pool.returned_counts.package_uris).toBe(1); expect(result.limitations).toEqual(parent.limitations); @@ -276,6 +279,9 @@ it("preserves null snapshot facts and pool lower bounds after exhaustion, reject string_pool: { coverage: "partial", package_uri_count_at_least: 1000 }, coverage: { total: 1, exhausted: true }, }); + expect(page.value.normalized_result).not.toHaveProperty( + "libapp.snapshot_profile", + ); } expect( await inspectAnalysisView({