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 <rizzellostefano@gmail.com>

* fix(flutter): retain valid pools beside malformed snapshot exports

---------

Co-authored-by: Stefano Rizzello <rizzellostefano@gmail.com>
This commit is contained in:
morlutoandStefano Rizzello authored and GitHub committed 2026-11-19 19:22:54 +00:00
1 parent 18abd3221a
commit 673bd049b7
11 files changed
+526 -245

No files matched your search

+15 -17
View File
@@ -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
@@ -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(
@@ -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({
+9 -2
View File
@@ -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",
},
],
});
});
+16 -7
View File
@@ -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 };
};
+216
View File
@@ -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<typeof readSnapshotHeader>;
const ALL_SYMBOLS = [
...LEGACY.data,
...LEGACY.text,
...UNIFIED.data,
...UNIFIED.text,
];
const DATA_SYMBOLS: ReadonlySet<string> = 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<string, ElfSymbol>,
headers: ReadonlyMap<string, Header>,
) => {
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<string, Header>();
const physicalHeaders = new Map<string, Header>();
const hashes = new Map<number, string>();
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,
};
};
+64 -8
View File
@@ -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<typeof buildElf64Image>[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: {
+22 -149
View File
@@ -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<typeof readSnapshotHeader>;
}[] = [];
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<number>();
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<DartPoolBudget>(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`,
+115 -1
View File
@@ -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 }) => {
@@ -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) => {
+7 -1
View File
@@ -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({