Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(apple): derive dispatch coverage from located decode facts
morluto488f448ae27f
diff --git a/src/native/AppleDispatchCoverage.ts b/src/native/AppleDispatchCoverage.tsindex 6114a8e87..746e099be 100644--- a/src/native/AppleDispatchCoverage.ts+++ b/src/native/AppleDispatchCoverage.ts@@ -1,5 +1,7 @@import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";import type { PointerFixups } from "./AppleMachoFixups.js";+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";+import type { FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";const describeFixups = (fixups: PointerFixups): string => {if (fixups.kind === "chained")@@ -13,13 +15,25 @@ const describeFixups = (fixups: PointerFixups): string => {export const pushDispatchCoverage = (input: {readonly result: ObjcSwiftMetadata;readonly failures: readonly string[];+ readonly categoryIssues: readonly DecodeIssue[];readonly examined: number;readonly categoriesExamined: number;readonly truncated: boolean;readonly fixups: PointerFixups;+ readonly vtables: FacetDecodeFacts;+ readonly swift: FacetDecodeFacts;}): void => {- const { result, failures, examined, categoriesExamined, truncated, fixups } =- input;+ const {+ result,+ failures,+ categoryIssues,+ examined,+ categoriesExamined,+ truncated,+ fixups,+ vtables,+ swift,+ } = input;result.coverage.push({facet: "objc_class_method_ivar_metadata",status: failures.length > 0 || truncated ? "partial" : "complete",@@ -48,17 +62,22 @@ export const pushDispatchCoverage = (input: {(item) => item.decode.status === "decoded",).length,});- const categoryFailures = failures.filter((failure) =>- /^(?:Properties of|Category at)/u.test(failure),+ const categoryFailures = categoryIssues.map(+ ({ code, location, message }) =>+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`,);result.coverage.push({facet: "objc_properties_categories",status:+ truncated ||categoryFailures.length > 0 ||result.objc_categories.some(({ decode }) => decode.status !== "decoded")? "partial": "complete",- reason: categoryFailures.join("; ") || null,+ reason:+ [...categoryFailures, ...(truncated ? ["max_records_reached"] : [])].join(+ "; ",+ ) || null,examined: categoriesExamined,decoded: result.objc_categories.filter(({ decode }) => decode.status === "decoded",@@ -66,8 +85,14 @@ export const pushDispatchCoverage = (input: {});result.coverage.push({facet: "pointer_fixups",- status: fixups.failures.length > 0 ? "partial" : "complete",- reason: [describeFixups(fixups), ...fixups.failures].join("; "),+ status: fixups.issues.length > 0 ? "partial" : "complete",+ reason: [+ describeFixups(fixups),+ ...fixups.issues.map(+ ({ code, location, message }) =>+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`,+ ),+ ].join("; "),examined: 0,decoded: 0,});@@ -79,4 +104,63 @@ export const pushDispatchCoverage = (input: {examined: 0,decoded: 0,});+ result.coverage.push({+ facet: "swift_conformances_static_witness_slots",+ status:+ swift.exhaustive &&+ !truncated &&+ !result.swift_conformances.some(+ ({ decode }) => decode.status !== "decoded",+ ) &&+ !result.swift_dispatch_slots.some(+ ({ table_kind, decode }) =>+ table_kind === "witness_table" && decode.status !== "decoded",+ )+ ? "complete"+ : "partial",+ reason:+ [+ ...swift.issues.map(formatIssue),+ ...(truncated ? ["max_records_reached"] : []),+ ...(result.swift_conformances.some(+ ({ decode }) => decode.status !== "decoded",+ ) ||+ result.swift_dispatch_slots.some(+ ({ table_kind, decode }) =>+ table_kind === "witness_table" && decode.status !== "decoded",+ )+ ? ["swift_records_unresolved"]+ : []),+ ].join("; ") || null,+ examined: swift.examined,+ decoded: swift.decoded,+ });+ result.coverage.push({+ facet: "swift_class_vtable_descriptors",+ status:+ vtables.exhaustive &&+ !truncated &&+ !result.swift_dispatch_slots.some(+ ({ table_kind, decode }) =>+ table_kind === "class_vtable" && decode.status !== "decoded",+ )+ ? "complete"+ : "partial",+ reason:+ [+ ...vtables.issues.map(formatIssue),+ ...(truncated ? ["max_records_reached"] : []),+ ...(result.swift_dispatch_slots.some(+ ({ table_kind, decode }) =>+ table_kind === "class_vtable" && decode.status !== "decoded",+ )+ ? ["vtable_implementations_unresolved"]+ : []),+ ].join("; ") || null,+ examined: vtables.examined,+ decoded: vtables.decoded,+ });};++const formatIssue = ({ code, location, message }: DecodeIssue): string =>+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`;diff --git a/src/native/AppleDispatchDecodeFacts.ts b/src/native/AppleDispatchDecodeFacts.tsnew file mode 100644index 000000000..699235d16--- /dev/null+++ b/src/native/AppleDispatchDecodeFacts.ts@@ -0,0 +1,35 @@+/** Stable internal decode issues used to derive public facet coverage. */+export type DispatchFacet =+ | "objc_class_method_ivar_metadata"+ | "binary_relative_pointers"+ | "objc_properties_categories"+ | "pointer_fixups"+ | "swift_conformances_static_witness_slots"+ | "swift_class_vtable_descriptors";++export interface DecodeIssue {+ readonly facet: DispatchFacet;+ readonly code: string;+ readonly location?: string;+ readonly message: string;+}++export interface FacetDecodeFacts {+ readonly facet: DispatchFacet;+ readonly examined: number;+ readonly decoded: number;+ readonly exhaustive: boolean;+ readonly issues: readonly DecodeIssue[];+}++export const issue = (+ facet: DispatchFacet,+ code: string,+ message: string,+ location?: string,+): DecodeIssue => ({+ facet,+ code,+ message,+ ...(location === undefined ? {} : { location }),+});diff --git a/src/native/AppleDispatchMetadata.test.ts b/src/native/AppleDispatchMetadata.test.tsindex 1c78241a5..a69f20183 100644--- a/src/native/AppleDispatchMetadata.test.ts+++ b/src/native/AppleDispatchMetadata.test.ts@@ -102,9 +102,13 @@ describe("Apple dispatch binary metadata", () => {implementation_address: null,decode: { status: "partial" },});+ const truncated = decodeAppleDispatchMetadata(fixture(), 1, provenance);+ expect(truncated.coverage[0]?.reason).toContain("max_records_reached");expect(- decodeAppleDispatchMetadata(fixture(), 1, provenance).coverage[0]?.reason,- ).toContain("max_records_reached");+ truncated.coverage.find(+ ({ facet }) => facet === "objc_properties_categories",+ ),+ ).toMatchObject({ status: "partial", reason: "max_records_reached" });});it("rejects malformed command and section boundaries", () => {const bytes = fixture();@@ -171,7 +175,7 @@ describe("FAT64 dispatch slice validation", () => {const bytes = wrapped();bytes.writeBigUInt64BE(0x100000000n, field);expect(() => decodeAppleDispatchMetadata(bytes, 100, provenance)).toThrow(- "FAT slice exceeds file",+ "FAT architecture 0 slice range extends beyond the file",);},);@@ -265,7 +269,7 @@ describe("byte-swapped universal Apple dispatch metadata", () => {const bytes = wrapped(true);bytes.writeBigUInt64LE(0x100000000n, 16);expect(() => decodeAppleDispatchMetadata(bytes, 100, provenance)).toThrow(- "FAT slice exceeds file (FAT header byte order: little-endian)",+ "FAT architecture 0 slice range extends beyond the file (FAT header byte order: little-endian)",);});});diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.tsindex 94daaf9f8..530dd9eb8 100644--- a/src/native/AppleDispatchMetadata.ts+++ b/src/native/AppleDispatchMetadata.ts@@ -99,21 +99,22 @@ export const decodeAppleDispatchMetadata = (evidence,offset,};- const { failures, examined, categoriesExamined } = decodeObjcDispatchFacets({- bytes,- sections,- segments,- readers,- budget,- result,- });+ const { failures, categoryIssues, examined, categoriesExamined } =+ decodeObjcDispatchFacets({+ bytes,+ sections,+ segments,+ readers,+ budget,+ result,+ });const swiftRelative = createSwiftRelativeReader({bytes,readers,budget,result,});- decodeSwiftDispatchFacets({+ const swift = decodeSwiftDispatchFacets({sections,segments,readers,@@ -131,7 +132,7 @@ export const decodeAppleDispatchMetadata = (typeEntries.push(section.address + BigInt(index * 4));if (section.size / 4 > maxRecords) budget.truncated = true;}- decodeSwiftClassVtables({+ const vtables = decodeSwiftClassVtables({entries: typeEntries,result,readers: {@@ -153,10 +154,13 @@ export const decodeAppleDispatchMetadata = (pushDispatchCoverage({result,failures,+ categoryIssues,examined,categoriesExamined,truncated: budget.truncated,fixups,+ vtables,+ swift,});return objcSwiftMetadataSchema.parse(result);};diff --git a/src/native/AppleMachoFixups.test.ts b/src/native/AppleMachoFixups.test.tsindex b4a2ebdbb..f9218fc7b 100644--- a/src/native/AppleMachoFixups.test.ts+++ b/src/native/AppleMachoFixups.test.ts@@ -144,6 +144,33 @@ const SEGMENTS: Segment[] = [];describe("pointer fixup tables", () => {+ it("reports unsupported pointer formats even when no pointer is visited", () => {+ const data = chainedData(1);+ data.writeUInt16LE(99, 46);+ const fixups = parsePointerFixups(+ data,+ { chained: { offset: 0, size: data.length }, binds: [], dylibs: [] },+ SEGMENTS,+ BASE,+ );+ expect(fixups.failures).toContain("Unsupported chained pointer format 99");+ });++ it("does not decode unreferenced imports while constructing fixup facts", () => {+ const data = chainedData(1);+ // The second import is outside the table bytes; only the first is needed+ // to construct the fixup reader, so its malformed symbol remains lazy.+ data.writeUInt32LE(0xffff_ff00, 72);+ expect(() =>+ parsePointerFixups(+ data,+ { chained: { offset: 0, size: data.length }, binds: [], dylibs: [] },+ SEGMENTS,+ BASE,+ ),+ ).not.toThrow();+ });+for (const format of [1, 2, 3] as const)it(`reads chained import format ${format}`, () => {const data = chainedData(format);diff --git a/src/native/AppleMachoFixups.ts b/src/native/AppleMachoFixups.tsindex 4f3649082..4c7686790 100644--- a/src/native/AppleMachoFixups.ts+++ b/src/native/AppleMachoFixups.ts@@ -1,4 +1,6 @@import type { Segment } from "./AppleMachoSelection.js";+import { issue } from "./AppleDispatchDecodeFacts.js";+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";/** Where a Mach-O stores pointer fixups, from its load commands. */export interface FixupCommands {@@ -23,7 +25,8 @@ export type DecodedPointer =readonly library: string | null;readonly weak: boolean;readonly addend: bigint;- };+ }+ | { readonly kind: "unsupported"; readonly reason: string };/** Pointer decoding for one Mach-O slice. */export interface PointerFixups {@@ -31,6 +34,7 @@ export interface PointerFixups {/** Chained pointer formats in use, such as `DYLD_CHAINED_PTR_64_OFFSET`. */readonly formats: readonly string[];readonly failures: readonly string[];+ readonly issues: readonly DecodeIssue[];/** Decode the pointer stored at `address` whose raw 64-bit value is `raw`. */decode(address: bigint, raw: bigint): DecodedPointer;}@@ -72,7 +76,7 @@ const cString = (bytes: Buffer, offset: number, end: number): string => {return bytes.toString("utf8", offset, stop);};-const readImports = (+const readImport = (data: {readonly bytes: Buffer;readonly base: number;@@ -85,38 +89,42 @@ const readImports = (readonly format: number;readonly symbols: number;},-): Import[] => {+ index: number,+): Import => {const { bytes, base, end, dylibs } = data;const size = header.format === 3 ? 16 : header.format === 2 ? 8 : 4;if (header.format < 1 || header.format > 3)throw new RangeError(`Unsupported chained import format ${header.format}`);- if (base + header.offset + header.count * size > end)+ if (+ !Number.isSafeInteger(header.count) ||+ base + header.offset + header.count * size > end+ )throw new RangeError("Chained import table exceeds the fixup data");- return Array.from({ length: header.count }, (_, index) => {- const at = base + header.offset + index * size;- if (header.format === 3) {- const word = bytes.readBigUInt64LE(at);- const ordinal = Number(signed(bits(word, 0, 16), 16));- return {- symbol: cString(- bytes,- base + header.symbols + Number(bits(word, 32, 32)),- end,- ),- library: libraryName(ordinal, dylibs),- weak: bits(word, 16, 1) === 1n,- addend: bytes.readBigInt64LE(at + 8),- };- }- const word = bytes.readUInt32LE(at);- const ordinal = Number(signed(BigInt(word & 0xff), 8));+ if (index < 0 || index >= header.count)+ throw new RangeError("Chained import index is outside the table");+ const at = base + header.offset + index * size;+ if (header.format === 3) {+ const word = bytes.readBigUInt64LE(at);+ const ordinal = Number(signed(bits(word, 0, 16), 16));return {- symbol: cString(bytes, base + header.symbols + (word >>> 9), end),+ symbol: cString(+ bytes,+ base + header.symbols + Number(bits(word, 32, 32)),+ end,+ ),library: libraryName(ordinal, dylibs),- weak: ((word >>> 8) & 1) === 1,- addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,+ weak: bits(word, 16, 1) === 1n,+ addend: bytes.readBigInt64LE(at + 8),};- });+ }+ const word = bytes.readUInt32LE(at);+ const ordinal = Number(signed(BigInt(word & 0xff), 8));+ return {+ symbol: cString(bytes, base + header.symbols + (word >>> 9), end),+ library: libraryName(ordinal, dylibs),+ weak: ((word >>> 8) & 1) === 1,+ addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,+ };};/** Decode one raw chained pointer for its segment's pointer format. */@@ -124,10 +132,13 @@ export const decodeChainedPointer = (raw: bigint,format: number,baseAddress: bigint,- imports: readonly Import[],+ imports: readonly Import[] | ((index: number) => Import),): DecodedPointer => {const bind = (ordinal: bigint, addend: bigint): DecodedPointer => {- const target = imports[Number(ordinal)];+ const target =+ typeof imports === "function"+ ? imports(Number(ordinal))+ : imports[Number(ordinal)];if (target === undefined)throw new RangeError(`Chained bind ordinal ${ordinal} has no import`);return { kind: "bind", ...target, addend: target.addend + addend };@@ -176,15 +187,24 @@ const chainedFixups = (if (range.size < 28 || end > bytes.length)throw new RangeError("Chained fixup header exceeds the target");const startsOffset = bytes.readUInt32LE(base + 4);- const imports = readImports(- { bytes, base, end, dylibs },- {- offset: bytes.readUInt32LE(base + 8),- symbols: bytes.readUInt32LE(base + 12),- count: bytes.readUInt32LE(base + 16),- format: bytes.readUInt32LE(base + 20),- },- );+ const importHeader = {+ offset: bytes.readUInt32LE(base + 8),+ symbols: bytes.readUInt32LE(base + 12),+ count: bytes.readUInt32LE(base + 16),+ format: bytes.readUInt32LE(base + 20),+ };+ const importSize =+ importHeader.format === 3 ? 16 : importHeader.format === 2 ? 8 : 4;+ const importTableEnd =+ base + importHeader.offset + importHeader.count * importSize;+ if (importHeader.format < 1 || importHeader.format > 3)+ throw new RangeError(+ `Unsupported chained import format ${importHeader.format}`,+ );+ if (!Number.isSafeInteger(importHeader.count) || importTableEnd > end)+ throw new RangeError("Chained import table exceeds the fixup data");+ const imports = (index: number) =>+ readImport({ bytes, base, end, dylibs }, importHeader, index);if (bytes.readUInt32LE(base + 24) !== 0)throw new RangeError("Compressed chained-fixup symbol names are not supported",@@ -213,10 +233,23 @@ const chainedFixups = (ranges.map(({ format }) => POINTER_FORMATS[format] ?? `format-${format}`),),];+ const issues = ranges.flatMap(({ format, from }) =>+ POINTER_FORMATS[format] === undefined+ ? [+ issue(+ "pointer_fixups",+ "unsupported_pointer_format",+ `Unsupported chained pointer format ${format}`,+ `0x${from.toString(16)}`,+ ),+ ]+ : [],+ );return {kind: "chained",formats,- failures: [],+ failures: issues.map(({ message }) => message),+ issues,decode(address, raw) {const segment = ranges.find(({ from, to }) => address >= from && address < to,@@ -224,6 +257,11 @@ const chainedFixups = (// Pointers outside fixup segments, such as in __TEXT, are stored plainly.if (segment === undefined) return { kind: "rebase", target: raw };if (raw === 0n) return { kind: "rebase", target: 0n };+ if (POINTER_FORMATS[segment.format] === undefined)+ return {+ kind: "unsupported",+ reason: `Unsupported chained pointer format ${segment.format}`,+ };return decodeChainedPointer(raw, segment.format, baseAddress, imports);},};@@ -388,6 +426,7 @@ export const parsePointerFixups = (kind: "none",formats: [],failures: [],+ issues: [],decode: (_address, raw) => ({ kind: "rebase", target: raw }),};const binds = new Map<bigint, Import>();@@ -404,6 +443,9 @@ export const parsePointerFixups = (kind: "dyld-info",formats: [],failures,+ issues: failures.map((message) =>+ issue("pointer_fixups", "bind_stream_decode_failed", message),+ ),decode(address, raw) {const bound = binds.get(address);return bound === undefineddiff --git a/src/native/AppleObjcCategories.ts b/src/native/AppleObjcCategories.tsindex 10d5a13df..bd936e0ce 100644--- a/src/native/AppleObjcCategories.ts+++ b/src/native/AppleObjcCategories.ts@@ -2,6 +2,7 @@ import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";import type { Section } from "./AppleMachoSelection.js";import type { ObjcDispatchReaders } from "./AppleObjcDispatchFacets.js";import { readObjcPropertiesOf } from "./AppleObjcProperties.js";+import { issue, type DecodeIssue } from "./AppleDispatchDecodeFacts.js";const CLASS_SYMBOL = /^_OBJC_(?:META)?CLASS_\$_(.+)$/u;@@ -23,6 +24,7 @@ export const decodeObjcCategories = (input: {readonly read: ObjcDispatchReaders;readonly result: ObjcSwiftMetadata;readonly failures: string[];+ readonly issues: DecodeIssue[];readonly admit: () => boolean;/** Decode a method list into implementations attributed to the category. */readonly methods: (@@ -79,7 +81,8 @@ export const decodeObjcCategories = (input: {properties: readObjcPropertiesOf(read, read.pointer(category + 40n), {owner: `category ${name}`,admit: input.admit,- failures,+ issues: input.issues,+ location: `0x${read.pointer(category + 40n).toString(16)}`,}),location: read.location(category),decode:@@ -89,8 +92,15 @@ export const decodeObjcCategories = (input: {evidence: read.evidence(category, "Objective-C category_t record"),});} catch (cause: unknown) {- failures.push(- `Category at ${`0x${field.toString(16)}`}: ${cause instanceof Error ? cause.message : String(cause)}`,+ const message = cause instanceof Error ? cause.message : String(cause);+ failures.push(`Category at 0x${field.toString(16)}: ${message}`);+ input.issues.push(+ issue(+ "objc_properties_categories",+ "category_decode_failed",+ message,+ `0x${field.toString(16)}`,+ ),);}}diff --git a/src/native/AppleObjcDispatchFacets.ts b/src/native/AppleObjcDispatchFacets.tsindex e3485e9c1..e23d4905d 100644--- a/src/native/AppleObjcDispatchFacets.ts+++ b/src/native/AppleObjcDispatchFacets.ts@@ -2,6 +2,7 @@ import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";import type { Segment, Section } from "./AppleMachoSelection.js";import { boundClassName, decodeObjcCategories } from "./AppleObjcCategories.js";import { readObjcPropertiesOf } from "./AppleObjcProperties.js";+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";import { createObjcProtocolReader } from "./AppleObjcProtocols.js";import type {BinaryMetadataEvidence,@@ -67,9 +68,15 @@ export const decodeObjcDispatchFacets = (input: {readers: ObjcDispatchReaders;budget: DispatchRecordBudget;result: ObjcSwiftMetadata;-}): { failures: string[]; examined: number; categoriesExamined: number } => {+}): {+ failures: string[];+ categoryIssues: DecodeIssue[];+ examined: number;+ categoriesExamined: number;+} => {const { bytes, sections, segments, readers: read, budget, result } = input;const failures: string[] = [];+ const categoryIssues: DecodeIssue[] = [];let examined = 0;const methods = (list: bigint,@@ -275,7 +282,8 @@ export const decodeObjcDispatchFacets = (input: {properties: readObjcPropertiesOf(read, read.pointer(ro + 64n), {owner: name,admit: () => budget.admit(),- failures,+ issues: categoryIssues,+ location: hex(read.pointer(ro + 64n)),}),protocols: protocolReader.list(read.pointer(ro + 40n)),ivar_count: ivarCount,@@ -328,10 +336,11 @@ export const decodeObjcDispatchFacets = (input: {read,result,failures,+ issues: categoryIssues,admit: () => budget.admit(),methods,protocols: (list) => protocolReader.list(list),localClassName: (address) => localClassName(read, address),});- return { failures, examined, categoriesExamined };+ return { failures, categoryIssues, examined, categoriesExamined };};diff --git a/src/native/AppleObjcProperties.ts b/src/native/AppleObjcProperties.tsindex 4aac58a18..07dacbc1f 100644--- a/src/native/AppleObjcProperties.ts+++ b/src/native/AppleObjcProperties.ts@@ -1,6 +1,7 @@import type { z } from "zod";import type { objcPropertySchema } from "../domain/native/objcSwiftMetadata.js";+import { issue, type DecodeIssue } from "./AppleDispatchDecodeFacts.js";type ObjcProperty = z.infer<typeof objcPropertySchema>;@@ -89,14 +90,20 @@ export const readObjcPropertiesOf = (context: {readonly owner: string;readonly admit: () => boolean;- readonly failures: string[];+ readonly issues: DecodeIssue[];+ readonly location?: string;},): ObjcProperty[] => {try {return readObjcPropertyList(read, list, context.admit);} catch (cause: unknown) {- context.failures.push(- `Properties of ${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`,+ context.issues.push(+ issue(+ "objc_properties_categories",+ "property_decode_failed",+ `${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`,+ context.location,+ ),);return [];}diff --git a/src/native/AppleSwiftDispatchFacets.ts b/src/native/AppleSwiftDispatchFacets.tsindex ac6507d1d..c22683a9f 100644--- a/src/native/AppleSwiftDispatchFacets.ts+++ b/src/native/AppleSwiftDispatchFacets.ts@@ -1,5 +1,6 @@import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";import type { Segment, Section } from "./AppleMachoSelection.js";+import { issue, type FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";/** Resolved file-backed metadata location from the Mach-O layout. */export interface ResolvedMetadataLocation {@@ -89,10 +90,12 @@ export const decodeSwiftDispatchFacets = (input: {relative: (field: bigint, indirectable?: boolean) => bigint;budget: DispatchRecordBudget;result: ObjcSwiftMetadata;-}): void => {+}): FacetDecodeFacts => {const { sections, segments, readers: read, relative, budget, result } = input;const swiftFailures: string[] = [];+ const issues = [] as ReturnType<typeof issue>[];let swiftExamined = 0;+ let decodedRecords = 0;for (const section of sections.filter(({ name }) => name === "__swift5_proto",)) {@@ -130,6 +133,10 @@ export const decodeSwiftDispatchFacets = (input: {if (staticWitness && read.pointer(witness) !== descriptor)witnessReason ="Witness-table conformance header is unresolved or encoded";+ const conformanceDecode =+ witnessReason === null+ ? { status: "decoded" as const, reason: null }+ : { status: "partial" as const, reason: witnessReason };result.swift_conformances.push({type_name: typeName,protocol_name: protocolName,@@ -139,20 +146,23 @@ export const decodeSwiftDispatchFacets = (input: {? { address: null, file_offset: null }: read.location(witness),location: read.location(descriptor),- decode:- witnessReason === null- ? decoded- : {- status: "partial",- reason: witnessReason,- },+ decode: conformanceDecode,evidence: read.evidence(descriptor,"Swift protocol conformance descriptor and directly encoded type/protocol names",),});+ if (conformanceDecode.status === "decoded") decodedRecords++;if (witnessReason !== null) {swiftFailures.push(`${typeName}: ${witnessReason}`);+ issues.push(+ issue(+ "swift_conformances_static_witness_slots",+ "conformance_decode_partial",+ witnessReason,+ hex(descriptor),+ ),+ );continue;}const count = read.u32(protocol + 16n);@@ -177,6 +187,13 @@ export const decodeSwiftDispatchFacets = (input: {implementation >= segment.address &&implementation < segment.address + segment.size,);+ const slotDecode = executable+ ? { status: "decoded" as const, reason: null }+ : {+ status: "partial" as const,+ reason:+ "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",+ };result.swift_dispatch_slots.push({owner: `${typeName}: ${protocolName}`,table_kind: "witness_table",@@ -186,36 +203,41 @@ export const decodeSwiftDispatchFacets = (input: {implementation_address: executable ? hex(implementation) : null,thunk_address: null,location: read.location(entry),- decode: executable- ? decoded- : {- status: "partial",- reason:- "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",- },+ decode: slotDecode,evidence: read.evidence(entry,"Static Swift witness slot, indexed after the conformance-descriptor header",),});+ if (slotDecode.status !== "decoded")+ issues.push(+ issue(+ "swift_conformances_static_witness_slots",+ "witness_slot_unresolved",+ slotDecode.reason,+ hex(entry),+ ),+ );}} catch (cause) {- swiftFailures.push(- `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,+ const message = cause instanceof Error ? cause.message : String(cause);+ swiftFailures.push(`${hex(field)}: ${message}`);+ issues.push(+ issue(+ "swift_conformances_static_witness_slots",+ "conformance_decode_failed",+ message,+ hex(field),+ ),);}}}- result.coverage.push({+ return {facet: "swift_conformances_static_witness_slots",- status:- swiftFailures.length > 0 || budget.truncated ? "partial" : "complete",- reason:- [- ...swiftFailures,- ...(budget.truncated ? ["max_records_reached"] : []),- ].join("; ") || null,examined: swiftExamined,- decoded: result.swift_conformances.length,- });+ decoded: decodedRecords,+ exhaustive: !budget.truncated && issues.length === 0,+ issues,+ };};diff --git a/src/native/AppleSwiftVtables.test.ts b/src/native/AppleSwiftVtables.test.tsnew file mode 100644index 000000000..782e09349--- /dev/null+++ b/src/native/AppleSwiftVtables.test.ts@@ -0,0 +1,207 @@+import { describe, expect, it } from "vitest";++import { objcSwiftMetadataSchema } from "../domain/native/objcSwiftMetadata.js";+import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";+import { decodeSwiftClassVtables } from "./AppleSwiftVtables.js";+import { decodeSwiftDispatchFacets } from "./AppleSwiftDispatchFacets.js";+import type { DispatchRecordBudget } from "./AppleSwiftDispatchFacets.js";+import { issue } from "./AppleDispatchDecodeFacts.js";++describe("Swift vtable coverage facts: unresolved Swift dispatch slots", () => {+ it("returns a located issue for an emitted unresolved async slot", () => {+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });+ const values = new Map<bigint, number>([+ [0x200n, 0x80000010], // class descriptor with a vtable+ [0x22cn, 0], // table offset+ [0x230n, 1], // slot count+ [0x21cn, 1], // descriptor positive words+ [0x234n, 0x40], // async method flag+ ]);+ const facts = decodeSwiftClassVtables({+ entries: [0x100n],+ result,+ readers: {+ u32: (address) => values.get(address) ?? 0,+ relative: (address) =>+ address === 0x100n ? 0x200n : address === 0x208n ? 0x300n : 0x400n,+ string: () => "Widget",+ location: (address) => ({+ address: `0x${address.toString(16)}`,+ file_offset: Number(address),+ }),+ evidence: (address, description) => [+ {+ kind: "binary_metadata",+ description,+ location: {+ address: `0x${address.toString(16)}`,+ file_offset: Number(address),+ },+ artifact_path: "/fixture",+ artifact_sha256: "a".repeat(64),+ },+ ],+ executable: () => false,+ admit: () => true,+ },+ });++ expect(result.swift_dispatch_slots[0]?.decode.status).toBe("partial");+ expect(facts).toMatchObject({+ facet: "swift_class_vtable_descriptors",+ exhaustive: false,+ issues: [{ code: "vtable_implementation_unresolved", location: "0x234" }],+ });++ pushDispatchCoverage({+ result,+ failures: [],+ categoryIssues: [],+ examined: 0,+ categoriesExamined: 0,+ truncated: false,+ fixups: {+ kind: "none",+ formats: [],+ failures: [],+ issues: [],+ decode: (_address, raw) => ({ kind: "rebase", target: raw }),+ },+ swift: {+ facet: "swift_conformances_static_witness_slots",+ examined: 0,+ decoded: 0,+ exhaustive: true,+ issues: [],+ },+ vtables: facts,+ });++ expect(+ result.coverage.find(+ ({ facet }) => facet === "swift_class_vtable_descriptors",+ ),+ ).toMatchObject({+ status: "partial",+ reason: expect.stringContaining("0x234"),+ });+ });++ it("returns a located issue for an emitted unresolved witness slot", () => {+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });+ const values = new Map<bigint, number>([+ [0x20cn, 0], // simple, unconditional conformance+ [0x500n, 3], // protocol descriptor kind+ [0x50cn, 0], // signature count+ [0x510n, 1], // witness requirement count+ [0x2b0n, 16], // nominal type descriptor kind+ [0x518n, 1], // function witness requirement+ ]);+ const budget: DispatchRecordBudget = {+ truncated: false,+ isFull: () => false,+ markTruncated: () => {+ budget.truncated = true;+ },+ admit: () => true,+ };+ const facts = decodeSwiftDispatchFacets({+ sections: [{ name: "__swift5_proto", address: 0x100n, size: 4 }],+ segments: [],+ readers: {+ u32: (address) => values.get(address) ?? 0,+ pointer: (address) => (address === 0x380n ? 0x200n : 0x900n),+ string: (address) => (address === 0x600n ? "Proto" : "Widget"),+ location: (address) => ({+ address: `0x${address.toString(16)}`,+ file_offset: Number(address),+ }),+ evidence: (address, description) => [+ {+ kind: "binary_metadata",+ description,+ location: {+ address: `0x${address.toString(16)}`,+ file_offset: Number(address),+ },+ artifact_path: "/fixture",+ artifact_sha256: "a".repeat(64),+ },+ ],+ offset: (address) => Number(address),+ },+ relative: (field) =>+ new Map<bigint, bigint>([+ [0x100n, 0x200n],+ [0x200n, 0x500n],+ [0x508n, 0x600n],+ [0x204n, 0x2b0n],+ [0x2b8n, 0x700n],+ [0x208n, 0x380n],+ ]).get(field) ?? 0n,+ budget,+ result,+ });++ expect(result.swift_dispatch_slots[0]?.decode.status).toBe("partial");+ expect(facts).toMatchObject({+ facet: "swift_conformances_static_witness_slots",+ exhaustive: false,+ issues: [{ code: "witness_slot_unresolved", location: "0x388" }],+ });+ });+});++describe("Swift vtable coverage facts: unsupported pointer fixup coverage", () => {+ it("marks pointer fixup coverage partial for an unsupported format with no decoded pointers", () => {+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });+ pushDispatchCoverage({+ result,+ failures: [],+ categoryIssues: [],+ examined: 0,+ categoriesExamined: 0,+ truncated: false,+ fixups: {+ kind: "chained",+ formats: ["format-99"],+ failures: ["Unsupported chained pointer format 99"],+ issues: [+ issue(+ "pointer_fixups",+ "unsupported_pointer_format",+ "Unsupported chained pointer format 99",+ "0x1000",+ ),+ ],+ decode: () => ({+ kind: "unsupported",+ reason: "Unsupported chained pointer format 99",+ }),+ },+ swift: {+ facet: "swift_conformances_static_witness_slots",+ examined: 0,+ decoded: 0,+ exhaustive: true,+ issues: [],+ },+ vtables: {+ facet: "swift_class_vtable_descriptors",+ examined: 0,+ decoded: 0,+ exhaustive: true,+ issues: [],+ },+ });++ expect(+ result.coverage.find(({ facet }) => facet === "pointer_fixups"),+ ).toMatchObject({+ status: "partial",+ examined: 0,+ decoded: 0,+ reason: expect.stringContaining("0x1000"),+ });+ });+});diff --git a/src/native/AppleSwiftVtables.ts b/src/native/AppleSwiftVtables.tsindex 1cb843238..64d91b593 100644--- a/src/native/AppleSwiftVtables.ts+++ b/src/native/AppleSwiftVtables.ts@@ -3,6 +3,7 @@ import type {NativeMetadataEvidence,NativeMetadataLocation,} from "../domain/native/objcSwiftMetadata.js";+import { issue, type FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";/** Byte readers shared with the validated Mach-O metadata boundary. */export interface SwiftMetadataReaders {@@ -20,13 +21,23 @@ export const decodeSwiftClassVtables = (input: {readers: SwiftMetadataReaders;entries: readonly bigint[];result: ObjcSwiftMetadata;-}) => {+}): FacetDecodeFacts => {const { readers: read, result } = input;const failures: string[] = [];+ const issues = [] as ReturnType<typeof issue>[];let examined = 0;+ let decoded = 0;for (const field of input.entries) {if (!read.admit()) {failures.push("max_records_reached");+ issues.push(+ issue(+ "swift_class_vtable_descriptors",+ "record_budget_exhausted",+ "max_records_reached",+ `0x${field.toString(16)}`,+ ),+ );break;}examined++;@@ -56,11 +67,19 @@ export const decodeSwiftClassVtables = (input: {);const owner = read.string(read.relative(descriptor + 8n));for (let index = 0; index < count; index++) {+ const entry = header + 8n + BigInt(index * 8);if (!read.admit()) {failures.push("max_records_reached");+ issues.push(+ issue(+ "swift_class_vtable_descriptors",+ "record_budget_exhausted",+ "max_records_reached",+ `0x${entry.toString(16)}`,+ ),+ );break;}- const entry = header + 8n + BigInt(index * 8);const methodFlags = read.u32(entry);// Async slots reference async descriptors; coroutine and future kinds need separate decoders.const synchronous =@@ -90,33 +109,48 @@ export const decodeSwiftClassVtables = (input: {"Swift class vtable method descriptor; slot index is a metadata word offset, not a source method ordinal",),});+ if (resolved) decoded++;+ else+ issues.push(+ issue(+ "swift_class_vtable_descriptors",+ "vtable_implementation_unresolved",+ "Async, coroutine, external or unmapped vtable implementation is unresolved",+ `0x${entry.toString(16)}`,+ ),+ );}- if ((specific & 0x4000) !== 0)+ if ((specific & 0x4000) !== 0) {failures.push(`${owner}: inherited override descriptors are unsupported`,);+ issues.push(+ issue(+ "swift_class_vtable_descriptors",+ "inherited_override_descriptors_unsupported",+ "Inherited override descriptors are unsupported",+ `0x${descriptor.toString(16)}`,+ ),+ );+ }} catch (cause) {- failures.push(- `0x${field.toString(16)}: ${cause instanceof Error ? cause.message : String(cause)}`,+ const message = cause instanceof Error ? cause.message : String(cause);+ failures.push(`0x${field.toString(16)}: ${message}`);+ issues.push(+ issue(+ "swift_class_vtable_descriptors",+ "vtable_decode_failed",+ message,+ `0x${field.toString(16)}`,+ ),);}}- const slots = result.swift_dispatch_slots.filter(- (slot) => slot.table_kind === "class_vtable",- );- result.coverage.push({+ return {facet: "swift_class_vtable_descriptors",examined,- decoded: slots.filter((slot) => slot.decode.status === "decoded").length,- status:- failures.length > 0 ||- slots.some((slot) => slot.decode.status !== "decoded")- ? "partial"- : "complete",- reason:- failures.join("; ") ||- (slots.some((slot) => slot.decode.status !== "decoded")- ? "vtable_implementations_unresolved"- : null),- });+ decoded,+ exhaustive: issues.length === 0,+ issues,+ };};