feat(il2cpp): inventory Unity IL2CPP global-metadata images, types and methods (#3807)

* feat(il2cpp): inventory IL2CPP global-metadata images, types and methods

Add inspect_il2cpp_metadata (CLI inspect-il2cpp-metadata), a read-only
in-process decoder for unencrypted Unity global-metadata.dat version 39.
It reports header sections, serialized index widths, images, type
definitions (nesting from the nestedTypes section) and method names.

Unrecognized magic and other versions are unsupported; damaged headers,
overlapping sections, inconsistent record sizes, out-of-range indices and
invalid strings fail with a reason code and no partial success. MCP
detail summary retains the complete Evidence and pages rows through
inspect_analysis_view kind il2cpp-metadata.

Adds an opt-in verify:il2cpp:metadata -- --metadata PATH check.

* feat(il2cpp): deliver metadata summaries by default over MCP

A 112,232-method file produced a 10.5 MB complete response, above the
10 MiB stdio budget. Default MCP delivery is now the retained summary;
detail complete stays available, and the one-shot CLI requests it.

* fix(il2cpp): reject shifted strings, nesting cycles and method owner drift

Review fuzzing showed that moving the strings section offset by one byte
silently renamed every image, type and method. Name indices must now start
a string, which also bounds total decoding by the section size.

Nesting cycles and methods whose declaring type disagrees with the owning
type range are rejected instead of returned. Adds service, shutdown and
index-width coverage, and moves environment-specific measurements out of
the public guide and tool description.

* feat(il2cpp): decode global-metadata versions 29 and 31

Unity 2022.3 writes version 29 or 31 metadata: a 256-byte header of
(offset, size) pairs, fixed 4-byte indices, type records with
elementTypeIndex, and method records that gained returnParameterToken in
version 31. Record counts come from section sizes and must be whole.

Sections report a null count for these versions and index widths report
fixed-width-version. Image, type and method rows keep the same shape, and
the string, nesting and method-ownership checks apply to every version.

* fix(il2cpp): bound report size before serializing and tighten coverage

Rows share decoded names, so a 130 KB file could expand into gigabytes of
JSON before the 64 MiB budget check, ending in an internal RangeError. The
provider now refuses from a lower bound on the serialized rows first.

The decoder also rejects non-empty sections inside the header, methods
outside their declaring type's range and overlapping image type ranges, and
keeps a leading byte order mark in names. Layouts now carry one indexing
mode instead of two coupled flags, and the tool description explains
nested_type_start.

* fix(il2cpp): refuse oversized metadata before decoding rows

Address review findings on the IL2CPP metadata inventory:

- check a lower bound from header row counts before any row object is
  allocated, so a large rejected file no longer builds every row first;
- validate sealed parent Evidence and count its rows once per report
  instead of on every inspect_analysis_view page;
- decode version 39 fixtures with 2- and 4-byte type-definition,
  generic-container and parameter indices.

* docs(il2cpp): attach the decoder comment to readIl2cppMetadata

* fix(il2cpp): deliver complete rows by default like the other inspection tools

inspect_il2cpp_metadata defaulted to detail summary, the only inspection
tool to do so. Omitted detail now returns every row inline, as
inspect_artifact, decode_interface_builder and the capture tools do;
summary stays one argument away and the guide, CLI reference and skill
reference say to select it first for large games, whose complete MCP
delivery is refused at the stdio budget with retained Evidence.

* test(il2cpp): cover narrow-width -1 sentinels and fix the skill's default

An empty image stores its type start as the all-ones value of a one- or
two-byte index; the decoder reads it as -1, but no fixture exercised it,
so removing either conversion passed the suite. The fixture can now append
an empty image, and both widths decode it. The skill still described a
summary default; it now says to select summary first, as the guide does.

* docs(il2cpp): request summary explicitly in the summary example

* chore(il2cpp): hash the verifier metadata through owned file resources

* fix(il2cpp): count escaped name length without building the escaped string

* fix(il2cpp): keep the verifier's check failure and small-table last page

* feat(domain): count JSON string length without building the escaped string

* fix(il2cpp): keep descriptor cleanup owners and share the JSON length count

* test(domain): give the backslash case real backslashes

* fix(il2cpp): select the CLI path and finish the command like the other tools

Follow main's absoluteCallerPath (#4067) and pass the command signal to finishAnalysisCommand.

* fix(il2cpp): select the verifier input path like the CLI

Use absoluteCallerPath (#4067) so a path with a symlink followed by .. names the same file the CLI and MCP inspect.

* feat(il2cpp): add compact composable metadata queries

Retain source-indexed Evidence for filtered batch and field queries. Bound representation growth before serialization, yield decoding for cancellation, and share CLI Evidence publication with desktop inspection. Verify public Unity metadata against independent byte and managed-DLL oracles and exercise actual stdio SDK workflows.

* fix(il2cpp): retain the validated metadata header magic

* test(il2cpp): remove obsolete execution wording exception

* fix(artifacts): preserve export selection and completed source facts

---------

Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>

src/domain/il2cpp/il2cppMetadata.ts

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { digestSchema } from "../digests.js";
+import { localPathStringSchema } from "../localPath.js";
+
+/** Unsigned little-endian signature observed at file offset zero. */
+export const IL2CPP_METADATA_MAGIC = 0xfab11baf;
+
+/** Header section order shared by global-metadata.dat versions 29, 31 and 39. */
+export const IL2CPP_METADATA_SECTION_NAMES = [
+  "stringLiterals",
+  "stringLiteralData",
+  "strings",
+  "events",
+  "properties",
+  "methods",
+  "parameterDefaultValues",
+  "fieldDefaultValues",
+  "fieldAndParameterDefaultValueData",
+  "fieldMarshaledSizes",
+  "parameters",
+  "fields",
+  "genericParameters",
+  "genericParameterConstraints",
+  "genericContainers",
+  "nestedTypes",
+  "interfaces",
+  "vtableMethods",
+  "interfaceOffsets",
+  "typeDefinitions",
+  "images",
+  "assemblies",
+  "fieldRefs",
+  "referencedAssemblies",
+  "attributeData",
+  "attributeDataRanges",
+  "unresolvedIndirectCallParameterTypes",
+  "unresolvedIndirectCallParameterRanges",
+  "windowsRuntimeTypeNames",
+  "windowsRuntimeStrings",
+  "exportedTypeDefinitions",
+] as const;
+
+/** Decoded metadata versions; 29 and 31 use fixed 4-byte indices. */
+export const IL2CPP_METADATA_VERSIONS = [29, 31, 39] as const;
+
+const count = z.number().int().nonnegative();
+/** Serialized metadata indices use -1 for an absent reference. */
+const optionalIndex = z.number().int().min(-1);
+const indexWidth = z.union([z.literal(1), z.literal(2), z.literal(4)]);
+
+/** One explicit local file; detail selects delivery, never decoding coverage. */
+export const inspectIl2cppMetadataInputSchema = z.strictObject({
+  path: localPathStringSchema.describe(
+    "Absolute filesystem path to a Unity IL2CPP global-metadata.dat file",
+  ),
+  detail: z
+    .enum(["complete", "summary"])
+    .default("summary")
+    .describe(
+      "summary (default) retains complete Evidence and returns identity and collection counts; complete returns every image, type and method row inline",
+    ),
+});
+
+export const il2cppMetadataSectionSchema = z.strictObject({
+  name: z.enum(IL2CPP_METADATA_SECTION_NAMES),
+  offset: count,
+  size: count,
+  /** Header-recorded entry count; versions 29 and 31 record none. */
+  count: count.nullable(),
+});
+
+/** Assembly image and its contiguous type-definition range. */
+export const il2cppMetadataImageSchema = z.strictObject({
+  name: z.string(),
+  type_start: optionalIndex,
+  type_count: count,
+});
+
+/** Type definition; row position is its TypeDefinitionIndex. */
+export const il2cppMetadataTypeSchema = z.strictObject({
+  name: z.string(),
+  namespace: z.string(),
+  method_start: optionalIndex,
+  method_count: count,
+  nested_type_start: optionalIndex,
+  nested_type_count: count,
+  /** Enclosing type derived from the nestedTypes section. */
+  declaring_type: optionalIndex.describe(
+    "Enclosing TypeDefinitionIndex derived from nestedTypes; -1 means no enclosing metadata type was recorded",
+  ),
+});
+
+/** Method definition; row position is its MethodIndex. */
+export const il2cppMetadataMethodSchema = z.strictObject({
+  name: z.string(),
+  declaring_type: optionalIndex.describe(
+    "Declared TypeDefinitionIndex from this MethodDefinition; -1 is an absent reference",
+  ),
+});
+
+/** Unrefined report fields, shared with projections that omit row collections. */
+export const il2cppMetadataObjectSchema = z.strictObject({
+  artifact: z.strictObject({
+    path: localPathStringSchema,
+    sha256: digestSchema,
+    bytes: count,
+  }),
+  magic: z.literal(IL2CPP_METADATA_MAGIC),
+  metadata_version: z.union(
+    IL2CPP_METADATA_VERSIONS.map((version) => z.literal(version)),
+  ),
+  index_widths: z.strictObject({
+    type_definition: indexWidth,
+    generic_container: indexWidth,
+    parameter: indexWidth,
+    type: indexWidth,
+    type_width_source: z.enum([
+      "interface-offsets-record",
+      "type-definition-record",
+      "fixed-width-version",
+    ]),
+  }),
+  sections: z
+    .array(il2cppMetadataSectionSchema)
+    .length(IL2CPP_METADATA_SECTION_NAMES.length),
+  images: z.array(il2cppMetadataImageSchema),
+  types: z.array(il2cppMetadataTypeSchema),
+  methods: z.array(il2cppMetadataMethodSchema),
+  limitations: z.array(z.string()),
+});
+
+/** Complete name and count inventory of one decoded global-metadata.dat file. */
+export const il2cppMetadataSchema = il2cppMetadataObjectSchema.superRefine(
+  (report, context) => {
+    report.sections.forEach((section, index) => {
+      if (section.name !== IL2CPP_METADATA_SECTION_NAMES[index])
+        context.addIssue({
+          code: "custom",
+          path: ["sections", index, "name"],
+          message: "Sections must follow header order.",
+        });
+      if (section.offset + section.size > report.artifact.bytes)
+        context.addIssue({
+          code: "custom",
+          path: ["sections", index],
+          message: "Section range is outside the selected artifact.",
+        });
+    });
+  },
+);
+
+export type InspectIl2cppMetadataInput = z.infer<
+  typeof inspectIl2cppMetadataInputSchema
+>;
+export type Il2cppMetadataProviderInput = Omit<
+  InspectIl2cppMetadataInput,
+  "detail"
+>;
+export type Il2cppMetadataSection = z.infer<typeof il2cppMetadataSectionSchema>;
+export type Il2cppMetadata = z.infer<typeof il2cppMetadataSchema>;