[TrimmableTypeMap] Improve trimmable typemap build incrementality (#11764)

## Summary

Makes the **trimmable** typemap build pipeline (`_AndroidTypeMapImplementation=trimmable`, used by CoreCLR and NativeAOT) fully incremental, skipped in design‑time builds, and self‑consistent on every rebuild. Extracted as a focused, well‑tested slice from the larger #11617, and implemented on top of `main`'s current generator/task API rather than the runtime rewrite in that PR.

The bulk of this description is a deep dive into **how incrementality is achieved**, because the pipeline has several non‑obvious moving parts (two generator passes, content‑based writes, dynamic outputs vs. `IncrementalClean`, and a post‑link Java regeneration step).

---

## Background: what the trimmable typemap generator produces

The legacy typemap implementations (`llvm-ir`, `managed`) embed the managed ↔ Java type mapping into native binaries. The **trimmable** implementation instead generates, from a scan of the app's assemblies:

- a set of small managed **TypeMap assemblies** — one `_<Assembly>.TypeMap.dll` per input assembly plus a `_Microsoft.Android.TypeMaps.dll` root — that are trimmer‑friendly (unused entries are removed by the IL linker), and
- the **Java Callable Wrapper** (`*.java`, "JCW") sources that Java needs to call back into managed code, plus `acw-map.txt` and a merged `AndroidManifest.xml`.

This is driven by the `GenerateTrimmableTypeMap` MSBuild task. The active runtime is selected by `$(_AndroidRuntime)` (`CoreCLR` or `NativeAOT`); runtime‑specific targets extend the shared pipeline (`…TypeMap.Trimmable.CoreCLR.targets`, `…TypeMap.Trimmable.NativeAOT.targets`).

---

## The pipeline (target graph)

### Shared / Debug CoreCLR & NativeAOT (no trimming)

```
CoreCompile
   └─► _GenerateTrimmableTypeMap            (AfterTargets="CoreCompile")
          • scans @(ReferencePath) + framework/SDK assemblies + the app .dll
          • writes typemap/_*.TypeMap.dll + _Microsoft.Android.TypeMaps.dll
          • writes typemap/java/**/*.java (JCWs), acw-map.txt, merged AndroidManifest.xml
          • prunes stale JCWs, then touches typemap/_GenerateTrimmableTypeMap.stamp
   …
_ReadGeneratedTrimmableTypeMapAssemblies    (reads typemap-assemblies.txt → items)
_PrepareTrimmableNativeConfigAssemblies     (feeds _GeneratePackageManagerJava)
_PrepareTrimmableTypeMapAssemblies          (feeds packaging / assembly store)
_GenerateJavaStubs                          (copies JCWs → android/src, manifest, acw-map)
   └─► _CompileJava ─► _CompileToDalvik ─► packaging
```

`_GenerateJavaStubs` **overrides** the legacy target of the same name from `BuildOrder.targets`; on the trimmable path the JCWs already exist, so it only copies them into `$(IntermediateOutputPath)android/src` and wires up the manifest/`acw-map.txt`/native config.

### Release CoreCLR (`PublishTrimmed=true`) — two generator passes

```
CoreCompile ─► _GenerateTrimmableTypeMap            (pre-trim: full assembly set)
…
ILLink (trim) ─► CrossGen/R2R
   └─► _ComputePostTrimTrimmableTypeMapInputs        (collect existing linked .dll)
   └─► _GeneratePostTrimTrimmableTypeMapJavaSources   (post-trim)
          • regenerates JCWs from the *linked* assemblies only
          • writes typemap/linked-java/**/*.java (GenerateTypeMapAssemblies=false)
          • touches stamp/_GeneratePostTrimTrimmableTypeMapJavaSources.stamp
_GenerateJavaStubs                                    (copies linked-java → android/src)
```

The post‑trim pass exists because, after trimming, the set of types that still need JCWs is a **subset** of the pre‑trim set. `_GenerateJavaStubs` sources its JCWs from `$(_TypeMapJavaStubsSourceDirectory)`, which is `typemap/linked-java` for CoreCLR + `PublishTrimmed` and `typemap/java` otherwise.

NativeAOT (`PublishTrimmed=true` as well) does **not** use the post‑trim Java pass — it feeds the pre‑trim JCWs to ILC and its own native steps — so for NativeAOT the sources stay `typemap/java`.

---

## How incrementality is achieved (deep dive)

The pipeline follows the repo's [MSBuild best practices](https://github.com/dotnet/android/blob/main/Documentation/guides/MSBuildBestPractices.md): every expensive target declares `Inputs`/`Outputs`, re‑emits its dynamic `FileWrites`, and uses stamp files where a real output can't serve as a reliable timestamp sentinel. There are six principles at work.

### 1. Stamp files are the incremental sentinels — because the real outputs are content‑addressed

`GenerateTrimmableTypeMap` writes every output with `Files.CopyIfStreamChanged` (and the per‑assembly `WriteAssembliesToDisk` additionally compares timestamps): **an output whose content did not change keeps its old timestamp**. That's exactly what you want to avoid churning downstream Java/native compilation — but it makes those files unusable as MSBuild `Outputs`, because their timestamps can be *older* than the `Inputs` even on a successful run, which makes MSBuild consider the target perpetually out‑of‑date and re‑run it every build.

So `_GenerateTrimmableTypeMap` declares a **dedicated stamp** as its sole output and touches only that stamp:

```xml
Inputs="@(ReferencePath);@(PrivateSdkAssemblies);@(FrameworkAssemblies);$(IntermediateOutputPath)$(TargetFileName);$(_AndroidManifestAbs);$(_AndroidBuildPropertiesCache)"
Outputs="$(_TrimmableTypeMapOutputStamp)"
…
<Touch Files="$(_TrimmableTypeMapOutputStamp)" AlwaysCreate="true" />
```

The stamp is always touched on a run and never touched on a skip, so the target is correctly skipped iff none of its inputs changed. The generated DLLs and `typemap-assemblies.txt` are **not** touched and are **not** declared as outputs — they are content‑addressed, and no other target consumes them as timestamp `Inputs` (verified), so touching them would be pure churn. *(This is the `@jonathanpeppers` review point.)*

> The `Inputs` deliberately include `@(PrivateSdkAssemblies)` and `@(FrameworkAssemblies)`: they can contribute managed ↔ Java mappings, so a change in them must re‑run generation.

`_GenerateJavaStubs` uses the analogous idea, but its sentinel must reflect **whichever** pass produced the JCWs it copies:

```xml
Inputs="$(_TrimmableJavaSourceStamp);@(_EnvironmentFiles)"
```

where `_TrimmableJavaSourceStamp` resolves to the **post‑trim** stamp for CoreCLR + `PublishTrimmed`, and the **pre‑trim generator** stamp otherwise. This is what lets `_GenerateJavaStubs` react to post‑trim JCW regeneration while staying incremental on no‑op builds. *(This is the `@Copilot` review point; the non‑trim default was previously the TypeMap DLL, whose timestamp is unreliable for the reason above.)*

### 2. `Inputs` must reference files that actually exist

MSBuild treats a **non‑existent `Inputs` file as "out of date"** and runs the target. The post‑trim pass originally declared `Inputs="@(ResolvedFileToPublish)"`, which also lists non‑assembly publish outputs — e.g. `…/bin/Release/<rid>/UnnamedProject.runtimeconfig.json` — whose paths do not exist when the target runs. That single phantom input made `_GeneratePostTrimTrimmableTypeMapJavaSources` run on **every** build, wiping and regenerating `linked-java` each time.

The fix factors input collection into `_ComputePostTrimTrimmableTypeMapInputs`, which keeps only `.dll` items that exist on disk:

```xml
<_PostTrimTrimmableTypeMapInputAssemblies Include="@(ResolvedFileToPublish)"
    Condition=" '%(Extension)' == '.dll' and Exists('%(FullPath)') and (…RID filter…) " />
```

so the post‑trim pass is now genuinely incremental and its stamp is a trustworthy sentinel for `_GenerateJavaStubs`.

### 3. Dynamic outputs must be re‑published to `@(FileWrites)` on skipped builds

The set of generated assemblies and JCWs is data‑dependent (it comes from scanning), so the `ItemGroup`s that register those files into `@(FileWrites)` live **inside** the generating targets — and therefore don't execute on a no‑op build where those targets are skipped. If nothing re‑declares them, MSBuild's `IncrementalClean` sees the previously‑tracked files as orphaned and **deletes them** before packaging reads its inputs.

`_RecordTrimmableTypeMapFileWrites` runs unconditionally (gated only on the assemblies‑list file existing) and re‑emits the previous dynamic outputs back into `@(FileWrites)` before `IncrementalClean`:

- the generated TypeMap assemblies (read back from `typemap-assemblies.txt`),
- the pre‑trim JCWs (`typemap/java`) **and** their `android/src` copies,
- the post‑trim JCWs (`typemap/linked-java`) **and** their `android/src` copies, plus the post‑trim stamp, and
- the merged manifest, `acw-map.txt`, `ApplicationRegistration.java`, and the generator stamp.

The post‑trim entries are new in this PR: once `_GeneratePostTrimTrimmableTypeMapJavaSources` became skippable (principle 2), its `linked-java` outputs would otherwise be deleted by `IncrementalClean` on the builds where it's skipped. The globs are empty for configurations that have no post‑trim pass, so this is a no‑op there.

> Two more targets — `_PrepareTrimmableNativeConfigAssemblies` and `_PrepareTrimmableTypeMapAssemblies` — exist for the same "skipped target leaves item groups empty" reason: they re‑populate the TypeMap‑assembly item groups (used by packaging, the assembly store, and native config) from the on‑disk list via `BeforeTargets`, so incremental builds that skip generation still package correctly.

### 4. Content‑based writes + explicit stale pruning keep `android/src` exact

Because generation is content‑addressed (`CopyIfStreamChanged`) and the `android/src` copy uses `SkipUnchangedFiles="true"`, an unchanged JCW never updates a timestamp and never triggers Java recompilation.

The flip side is removal: when a JCW disappears between builds — a type deleted from source, or **trimmed away** on the `PublishTrimmed` path — its `android/src` copy must not linger, or it would be compiled and packaged. Both generator passes report the JCWs they no longer produce as `DeletedJavaFiles`; the owning target mirrors each deletion into the `android/src` copy and, if anything was deleted, deletes `$(_AndroidCompileJavaStampFile)` so `_CompileJava` re‑runs and drops the stale `.class`:

```xml
<Delete Files="@(_DeletedCopiedJavaFiles)" />
<Delete Files="$(_AndroidCompileJavaStampFile)" Condition=" '@(_DeletedCopiedJavaFiles->Count())' != '0' " />
```

The two passes compute the deleted set differently because of how each manages its output directory:

- **Pre‑trim** (`_GenerateTrimmableTypeMap`, writing `typemap/java`): the task scans the output dir and deletes any `*.java` the current pass didn't produce.
- **Post‑trim** (`_GeneratePostTrimTrimmableTypeMapJavaSources`, writing `typemap/linked-java` with `CleanJavaSourceOutputDirectory=true`): the dir is wiped before regeneration, so the task snapshots the previous `*.java` set *before* the wipe and reports `previous − regenerated`. This keeps the deletion precise — only files the generator itself previously produced are ever removed from `android/src`, never unrelated sources like `ApplicationRegistration.java`.

The net invariant is two‑directional: **`android/src` contains exactly the JCWs the active pass produces** (`typemap/linked-java` for `PublishTrimmed`, `typemap/java` otherwise) — no missing files (copied by `_GenerateJavaStubs`) and no stale files (pruned via `DeletedJavaFiles`). Exercised directly by the `…KeepsAndroidSrcConsistentWithLinkedJava` and `…DeletesStaleAndroidSrcWhenLinkedJavaShrinks` tests.

### 5. The generator is skipped in design‑time builds and runs exactly once

`_GenerateTrimmableTypeMap` is gated on `'$(DesignTimeBuild)' != 'true'`: in a design‑time build, project references may resolve to target paths that aren't produced when `SkipCompilerExecution=true`, and the output isn't needed for IDE information. Combined with the existing `'$(_OuterIntermediateOutputPath)' == ''` guard (which skips inner per‑RID builds), the generator runs exactly once per outer build.

### 6. Two‑pass consistency under trimming

For CoreCLR + `PublishTrimmed`, correctness depends on the pre‑trim and post‑trim sentinels composing cleanly:

- **No‑op rebuild** — both passes are skipped (their inputs are unchanged); `_GenerateJavaStubs` keys off the stable post‑trim stamp and is also skipped. *(Newly true; previously the post‑trim pass ran every build.)*
- **Managed source change** — the pre‑trim generator re‑runs (its inputs changed) and re‑linking changes the linked assemblies, so the post‑trim pass re‑runs too; `_GenerateJavaStubs` re‑copies.
- **Trim‑only change** (e.g. a change that alters the linked output without touching the pre‑trim inputs) — the linked `.dll` change re‑runs the post‑trim pass, which touches the post‑trim stamp, so `_GenerateJavaStubs` re‑runs even though the pre‑trim generator did not. This is precisely the staleness the `@Copilot` review flagged, and is why `_GenerateJavaStubs` must key off `_TrimmableJavaSourceStamp` rather than the generator stamp alone.

---

## What changed in this PR

| Area | Change |
| ---- | ------ |
| `…TypeMap.Trimmable.targets` | Stamp sentinel for `_GenerateTrimmableTypeMap` (sole `Output`, sole `Touch`); expanded `Inputs` (`PrivateSdkAssemblies`/`FrameworkAssemblies`); design‑time‑build skip; `SkipUnchangedFiles` JCW copy; stale‑JCW deletion wiring; `_GenerateJavaStubs` keyed off `_TrimmableJavaSourceStamp`; post‑trim outputs re‑emitted in `_RecordTrimmableTypeMapFileWrites`. |
| `…TypeMap.Trimmable.CoreCLR.targets` | New `_ComputePostTrimTrimmableTypeMapInputs` (existing‑`.dll` inputs) so `_GeneratePostTrimTrimmableTypeMapJavaSources` is incremental; post‑trim pass now mirrors `DeletedJavaFiles` into `android/src` + busts the Java compile stamp. |
| `Tasks/GenerateTrimmableTypeMap.cs` | New `DeletedJavaFiles` output + `DeleteStaleJavaSources()`; in the `CleanJavaSourceOutputDirectory` (post‑trim) case it snapshots the prior JCW set before the wipe and reports `previous − regenerated`. |
| `Microsoft.Android.Sdk.TrimmableTypeMap/README.md` | Documents the pipeline and its incrementality design. |
| `TrimmableTypeMapBuildTests.cs` | Tests for stale‑JCW pruning (both directions), updated‑JCW copying, the `android/src` ↔ `linked-java` invariant, post‑trim no‑op incrementality, and stale `android/src` removal when `linked-java` shrinks. |

### Review feedback addressed
- **@Copilot** (×2): `_GenerateJavaStubs` now keys off `$(_TrimmableJavaSourceStamp)` (post‑trim stamp for `PublishTrimmed`, generator stamp otherwise), and the non‑trim default of `_TrimmableJavaSourceStamp` was changed from the TypeMap DLL to the generator stamp. The underlying reason the bare generator stamp was insufficient — a non‑incremental post‑trim pass — is fixed too.
- **@jonathanpeppers**: `_GenerateTrimmableTypeMap` declares only the stamp as its `Outputs` and touches only the stamp; the DLLs/list are content‑addressed and not consumed as timestamp inputs elsewhere.

---

## Scope notes (and a little beyond)

- All changes are gated on `_AndroidTypeMapImplementation == 'trimmable'`; non‑trimmable (`llvm-ir`/`managed`) builds are unaffected.
- Unlike #11617, this PR **keeps** `main`'s CoreCLR post‑trim `linked-java` machinery intact and instead makes it incremental.
- **Beyond this PR**, the post‑trim pass still regenerates `linked-java` wholesale (`CleanJavaSourceOutputDirectory=true`) when it runs; it now also reports the JCWs it dropped so `android/src` stays exact. A further optimization would replace the wholesale clean with content‑based writes + in‑place stale pruning (as the pre‑trim pass does), letting unchanged `linked-java` JCWs keep stable timestamps across a post‑trim run. Left as a follow‑up.

---

## Testing

Verified locally against a Debug local SDK.

**Host (`Xamarin.Android.Build.Tests`, full `TrimmableTypeMapBuildTests`): 24 passed, 2 skipped, 0 failed**, including:
- `…IncrementalBuild` (Debug CoreCLR, Release CoreCLR, Release NativeAOT)
- `…DeletesStaleGeneratedJavaSourcesAndCopies`, `…CopiesUpdatedGeneratedJavaSources`
- `…PublishTrimmed_KeepsAndroidSrcConsistentWithLinkedJava` (the `android/src` ↔ `linked-java` invariant)
- `…PublishTrimmed_DeletesStaleAndroidSrcWhenLinkedJavaShrinks` (a JCW dropped from `linked-java` is removed from `android/src`)
- `…PublishTrimmed_PostTrimJavaGenerationIsIncremental` (no‑op rebuild skips post‑trim and `_GenerateJavaStubs`)
- `…Succeeds`, `…ArrayRankChangeRegeneratesTypeMap`, `…DoesNotHitCopyIfChangedMismatch`, R2R/multi‑RID packaging tests

**Emulator (`MSBuildDeviceIntegration`, API 36 / arm64):** `DotNetRun` deploy+run for trimmable CoreCLR (Debug + Release) and NativeAOT (Release), and `TrimmableTypeMapInheritedVirtualOverrideUsesCorrectUco`.

Author: simonrozsival

src/Microsoft.Android.Sdk.TrimmableTypeMap/README.md

@@ -0,0 +1,165 @@
+# Trimmable typemap build pipeline
+
+This document describes how the **trimmable** typemap implementation
+(`_AndroidTypeMapImplementation=trimmable`) is produced during an Android app
+build, and how the MSBuild targets are kept incremental. It is aimed at
+contributors working on the targets in
+`src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.TypeMap.Trimmable*.targets`
+and the `GenerateTrimmableTypeMap` MSBuild task.
+
+## Background
+
+The legacy typemap implementations (`llvm-ir`, `managed`) embed the
+managed ↔ Java type mapping into native binaries. The **trimmable**
+implementation instead generates a set of small managed *TypeMap assemblies*
+(one per input assembly, plus a `_Microsoft.Android.TypeMaps` root) and the Java
+Callable Wrapper (JCW) `*.java` sources from the same scan. This keeps the
+mapping trimmer-friendly: unused entries are removed by the IL linker.
+
+The work happens in the `GenerateTrimmableTypeMap` task, invoked from the
+`_GenerateTrimmableTypeMap` target. The runtime is selected by `_AndroidRuntime`
+(`CoreCLR` or `NativeAOT`); the runtime-specific imports
+(`*.Trimmable.CoreCLR.targets`, `*.Trimmable.NativeAOT.targets`) extend the
+shared pipeline.
+
+## Target pipeline (CoreCLR, non-trimmed Debug build)
+
+```
+CoreCompile
+   └─► _GenerateTrimmableTypeMap   (AfterTargets="CoreCompile")
+          • scans @(ReferencePath) + framework/SDK assemblies + the app .dll
+          • writes typemap/_*.TypeMap.dll + _Microsoft.Android.TypeMaps.dll
+          • writes typemap/java/**/*.java (JCWs) and acw-map.txt
+          • writes the merged AndroidManifest.xml
+          • touches typemap/_GenerateTrimmableTypeMap.stamp
+   ...
+_ReadGeneratedTrimmableTypeMapAssemblies    (reads typemap-assemblies.txt)
+_PrepareTrimmableNativeConfigAssemblies     (feeds _GeneratePackageManagerJava)
+_PrepareTrimmableTypeMapAssemblies          (feeds packaging / assembly store)
+_CollectTrimmableTypeMapJavaFiles           (globs the JCW *.java)
+_GenerateJavaStubs                          (copies JCWs into android/src, manifest, acw-map)
+   └─► _CompileJava ─► _CompileToDalvik ─► packaging
+```
+
+`_GenerateJavaStubs` **overrides** the legacy target of the same name from
+`BuildOrder.targets`; in the trimmable path the JCWs already exist, so this
+target only copies them into `$(IntermediateOutputPath)android/src` and wires up
+the manifest, `acw-map.txt`, and native config.
+
+For `CoreCLR` + `PublishTrimmed=true`, a second pass
+(`_GeneratePostTrimTrimmableTypeMapJavaSources`, in the CoreCLR targets)
+regenerates the JCWs from the **linked** assemblies into a `linked-java`
+directory, which then becomes the source for `_GenerateJavaStubs`.
+
+## Incrementality design
+
+The pipeline follows the repository's
+[MSBuild best practices](../../Documentation/guides/MSBuildBestPractices.md):
+every expensive target declares `Inputs`/`Outputs`, re-emits its dynamic
+`FileWrites`, and uses stamp files where a real output cannot serve as a
+reliable timestamp sentinel.
+
+### 1. A stamp file is the generator's incremental sentinel
+
+`_GenerateTrimmableTypeMap` declares:
+
+```xml
+Inputs="@(ReferencePath);@(PrivateSdkAssemblies);@(FrameworkAssemblies);$(IntermediateOutputPath)$(TargetFileName);$(_AndroidManifestAbs);$(_AndroidBuildPropertiesCache)"
+Outputs="$(_TypeMapOutputDirectory)$(_TypeMapAssemblyName).dll;$(_TypeMapAssembliesListFile);$(_TrimmableTypeMapOutputStamp)"
+```
+
+The generated TypeMap DLLs are written with `Files.CopyIfStreamChanged`, so an
+assembly whose **content** is unchanged keeps its old timestamp. If those DLLs
+were the only `Outputs`, MSBuild would consider the target perpetually
+out-of-date (its inputs are always newer than the untouched outputs) and re-run
+it on every build. To avoid this, the target unconditionally `Touch`es a
+dedicated stamp:
+
+```xml
+<Touch Files="@(_GeneratedTypeMapAssemblies);$(_TypeMapAssembliesListFile);$(_TrimmableTypeMapOutputStamp)" AlwaysCreate="true" />
+```
+
+so the stamp is always newer than the inputs after a run, and the target is
+correctly **skipped** when none of the inputs changed.
+
+> All assemblies that can contribute managed&nbsp;↔&nbsp;Java mappings must be
+> inputs — including `@(PrivateSdkAssemblies)` and `@(FrameworkAssemblies)` —
+> otherwise a change in one of them would not trigger regeneration.
+
+### 2. `_GenerateJavaStubs` keys off the stamp
+
+```xml
+Inputs="$(_TrimmableTypeMapOutputStamp);@(_EnvironmentFiles)"
+Outputs="$(_AndroidStampDirectory)_GenerateJavaStubs.stamp"
+```
+
+The stamp captures "the generator ran because its inputs changed" and is left
+stable when the generator is skipped, so the JCW copy into `android/src` only
+re-runs when something relevant actually changed. The copy uses
+`SkipUnchangedFiles="true"` so unchanged JCWs do not churn downstream Java
+compilation. For `CoreCLR` + `PublishTrimmed`, the JCWs are sourced from the
+`linked-java` directory produced by `_GeneratePostTrimTrimmableTypeMapJavaSources`,
+which is itself incremental; the stamp remains the sentinel so a no-op build
+still skips `_GenerateJavaStubs`.
+
+### 3. Stale generated Java sources are pruned (both passes)
+
+When a managed type is removed — or trimmed away on the `PublishTrimmed` path —
+its JCW must not linger in `android/src`, where it would otherwise be compiled
+and packaged. Both generator passes report the JCWs they no longer produce as
+`DeletedJavaFiles` (with `RelativePath` metadata), and the owning target mirrors
+each deletion into the `android/src` copy and, if anything was deleted, deletes
+`$(_AndroidCompileJavaStampFile)` so `_CompileJava` re-runs and drops the stale
+`.class` outputs:
+
+```xml
+<Delete Files="@(_DeletedCopiedJavaFiles)" />
+<Delete Files="$(_AndroidCompileJavaStampFile)" Condition=" '@(_DeletedCopiedJavaFiles->Count())' != '0' " />
+```
+
+The two passes compute the deleted set differently because of how each manages
+its output directory:
+
+- **Pre-trim** (`_GenerateTrimmableTypeMap`, writing `typemap/java`): the task
+  scans the output directory and deletes any `*.java` the current pass did not
+  produce.
+- **Post-trim** (`_GeneratePostTrimTrimmableTypeMapJavaSources`, writing
+  `typemap/linked-java` with `CleanJavaSourceOutputDirectory=true`): the
+  directory is wiped before regeneration, so the task snapshots the previous
+  `*.java` set *before* the wipe and reports `previous − regenerated`. This keeps
+  the deletion precise — only files the generator itself previously produced are
+  ever removed from `android/src`, never unrelated sources such as
+  `ApplicationRegistration.java`.
+
+The invariant is two-directional: **`android/src` contains exactly the JCWs the
+active pass produces** — no missing files (copied via `_GenerateJavaStubs`) and
+no stale files (pruned via `DeletedJavaFiles`).
+
+### 4. Dynamic `FileWrites` are re-emitted on no-op builds
+
+The set of generated assemblies and JCWs is data-dependent, so a build that
+*skips* `_GenerateTrimmableTypeMap` never executes the `ItemGroup` that registers
+those files in `@(FileWrites)`. `_RecordTrimmableTypeMapFileWrites` re-reads the
+generated outputs from `typemap-assemblies.txt` (and globs the JCWs) and
+re-emits them — plus the stamp — into `@(FileWrites)` *before* MSBuild's
+`IncrementalClean`, so the outputs are not seen as orphaned and deleted between
+incremental builds.
+
+### 5. The generator does not run in design-time builds, and runs once
+
+`_GenerateTrimmableTypeMap` is gated on `'$(DesignTimeBuild)' != 'true'`: in a
+design-time build, project references may resolve to target paths that are not
+produced when `SkipCompilerExecution=true`, and the generator output is not
+needed to provide IDE information. Combined with the
+`'$(_OuterIntermediateOutputPath)' == ''` guard (which skips inner per-RID
+builds), the generator runs exactly once per outer build.
+
+## Files
+
+| File | Role |
+| ---- | ---- |
+| `Microsoft.Android.Sdk.TypeMap.Trimmable.targets` | Shared pipeline: generation, Java stubs, packaging hookup, incremental `FileWrites`. |
+| `Microsoft.Android.Sdk.TypeMap.Trimmable.CoreCLR.targets` | CoreCLR specifics, incl. the post-trim `linked-java` regeneration. |
+| `Microsoft.Android.Sdk.TypeMap.Trimmable.NativeAOT.targets` | NativeAOT specifics (ILC inputs, proguard). |
+| `Tasks/GenerateTrimmableTypeMap.cs` | The MSBuild task front-end for the generator. |
+| `Microsoft.Android.Sdk.TrimmableTypeMap/**` | The generator/scanner library invoked by the task. |

src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.TypeMap.Trimmable.CoreCLR.targets

@@ -48,16 +48,28 @@
         OutputFile="$(_ProguardProjectConfiguration)" />
   </Target>
 
+  <Target Name="_ComputePostTrimTrimmableTypeMapInputs"
+      Condition=" '$(_AndroidTypeMapImplementation)' == 'trimmable' and '$(PublishTrimmed)' == 'true' and '$(_ComputeFilesToPublishForRuntimeIdentifiers)' != 'true' "
+      AfterTargets="_ResolveAssemblies">
+    <ItemGroup>
+      <_PostTrimTrimmableTypeMapInputAssemblies Remove="@(_PostTrimTrimmableTypeMapInputAssemblies)" />
+      <!-- Only the linked .dll assemblies that already exist on disk are valid inputs.
+           @(ResolvedFileToPublish) also contains non-assembly publish outputs (e.g.
+           runtimeconfig.json) whose paths do not exist when this target runs; declaring a
+           non-existent file as an Input would make MSBuild consider the target perpetually
+           out-of-date and run it on every build. -->
+      <_PostTrimTrimmableTypeMapInputAssemblies Include="@(ResolvedFileToPublish)"
+          Condition=" '%(Extension)' == '.dll' and Exists('%(FullPath)') and ('%(RuntimeIdentifier)' == '' or '$(_PostTrimTypeMapFirstRuntimeIdentifier)' == '' or '%(RuntimeIdentifier)' == '$(_PostTrimTypeMapFirstRuntimeIdentifier)') " />
+    </ItemGroup>
+  </Target>
+
   <Target Name="_GeneratePostTrimTrimmableTypeMapJavaSources"
       Condition=" '$(_AndroidTypeMapImplementation)' == 'trimmable' and '$(PublishTrimmed)' == 'true' and '$(_ComputeFilesToPublishForRuntimeIdentifiers)' != 'true' "
+      DependsOnTargets="_ComputePostTrimTrimmableTypeMapInputs"
       AfterTargets="_ResolveAssemblies"
       BeforeTargets="_GenerateJavaStubs;_CompileJava;_CompileToDalvik"
-      Inputs="@(ResolvedFileToPublish)"
+      Inputs="@(_PostTrimTrimmableTypeMapInputAssemblies)"
       Outputs="$(_PostTrimTrimmableTypeMapJavaStamp)">
-    <ItemGroup>
-      <_PostTrimTrimmableTypeMapInputAssemblies Include="@(ResolvedFileToPublish)"
-          Condition=" '%(Extension)' == '.dll' and ('%(RuntimeIdentifier)' == '' or '$(_PostTrimTypeMapFirstRuntimeIdentifier)' == '' or '%(RuntimeIdentifier)' == '$(_PostTrimTypeMapFirstRuntimeIdentifier)') " />
-    </ItemGroup>
 
     <GenerateTrimmableTypeMap
         ResolvedAssemblies="@(_PostTrimTrimmableTypeMapInputAssemblies)"
@@ -73,18 +85,33 @@
         AcwMapOutputFile="$(IntermediateOutputPath)acw-map.txt"
         ApplicationRegistrationOutputFile="$(IntermediateOutputPath)android/src/net/dot/android/ApplicationRegistration.java">
       <Output TaskParameter="GeneratedJavaFiles" ItemName="_PostTrimGeneratedJavaFiles" />
+      <Output TaskParameter="DeletedJavaFiles" ItemName="_PostTrimDeletedJavaFiles" />
     </GenerateTrimmableTypeMap>
 
+    <!-- Mirror any JCWs the post-trim pass no longer produces (e.g. trimmed-away types) into
+         the android/src copies so a stale .java (and stale .class) is not left behind. Busting
+         the Java compile stamp forces _CompileJava to drop the corresponding class output. -->
+    <ItemGroup>
+      <_PostTrimDeletedCopiedJavaFiles Remove="@(_PostTrimDeletedCopiedJavaFiles)" />
+      <_PostTrimDeletedCopiedJavaFiles Include="@(_PostTrimDeletedJavaFiles->'$(IntermediateOutputPath)android/src/%(RelativePath)')" />
+    </ItemGroup>
+    <Delete Files="@(_PostTrimDeletedCopiedJavaFiles)" />
+    <Delete Files="$(_AndroidCompileJavaStampFile)" Condition=" '@(_PostTrimDeletedCopiedJavaFiles->Count())' != '0' " />
+
     <MakeDir Directories="$([System.IO.Path]::GetDirectoryName('$(_PostTrimTrimmableTypeMapJavaStamp)'))" />
     <Touch Files="$(_PostTrimTrimmableTypeMapJavaStamp)" AlwaysCreate="true" />
 
     <ItemGroup>
+      <FileWrites Remove="@(_PostTrimDeletedJavaFiles)" />
+      <FileWrites Remove="@(_PostTrimDeletedCopiedJavaFiles)" />
       <FileWrites Include="@(_PostTrimGeneratedJavaFiles)" />
       <FileWrites Include="$(IntermediateOutputPath)acw-map.txt" />
       <FileWrites Include="$(IntermediateOutputPath)android/src/net/dot/android/ApplicationRegistration.java" />
       <FileWrites Include="$(_PostTrimTrimmableTypeMapJavaStamp)" />
       <_PostTrimTrimmableTypeMapInputAssemblies Remove="@(_PostTrimTrimmableTypeMapInputAssemblies)" />
       <_PostTrimGeneratedJavaFiles Remove="@(_PostTrimGeneratedJavaFiles)" />
+      <_PostTrimDeletedJavaFiles Remove="@(_PostTrimDeletedJavaFiles)" />
+      <_PostTrimDeletedCopiedJavaFiles Remove="@(_PostTrimDeletedCopiedJavaFiles)" />
     </ItemGroup>
   </Target>
   <!-- Add linked TypeMap DLLs to the normal publish assembly pipeline.  The SDK R2R