docs: state the rule that makes the media field decode safe

[jkmassel]

Stacked on #687. Last of nine PRs splitting #621.

What?

Writes down why decoding the editor's form fields as UTF-8 can't corrupt them, and adds tests for the one condition this code could break on its own.

Why?

formFields reads every non-file form value as UTF-8. UTF-8 decoding doesn't fail on bad bytes — it quietly swaps in a replacement character. So if bad bytes ever did arrive, a caption would come back mangled and nothing would report an error.

That can't happen today, but only because of who is on the other end, and nothing in the code says so. Three things have to stay true:

1. Only the editor's own page can reach this server. It only accepts connections from the device itself, and every request has to carry a per-session token.
2. Text the editor puts in a form field is already valid Unicode. The browser guarantees that when the value is set.
3. The only way a browser can put raw bytes in a form is a file or a Blob, and those always arrive with a filename. Anything with a filename is handled as the file, never as a field.

If one of those stops being true, iOS and Android mangle the value differently, so there's no single behaviour that could be documented in place of the rule. Turning off each platform's filename check shows it: the same three bad bytes (ED A0 80) come back as three replacement characters on iOS and one on Android. Both measured, not guessed.

How?

• The three conditions, as a comment on formFields, on both platforms.
• Rewrote the comment where the request gets rebuilt — the path used when a processor has changed the file. It said the field bytes were appended "so a non-UTF-8 value is forwarded verbatim rather than coerced", which reads as though bad values were expected there. They can't get there. On iOS the real reason is that String(data:encoding:) returns nil on bad UTF-8, and the ?? "" you'd reach for behind it would throw away the whole field. On both platforms, using the raw bytes keeps this path sending exactly the same request as the plain pass-through it stands in for, so an upload doesn't change shape just because the image got resized.

Testing Instructions

The tests cover condition 3, the only one this code controls. A request carrying a second part that looks like a Blob — it has a filename, and its bytes aren't valid UTF-8 — must not show up in fields, and must not get uploaded in place of the real file.

Both test bodies put file first and the other fields after, which is the order the editor actually sends them. Keep it that way. The server treats the first part that has a filename as the file, so moving the Blob ahead of file makes the Blob the upload and throws the real file away — while the check on fields still passes, so nothing catches it.

The Blob part reaches neither fields nor the request sent on to WordPress; it is dropped. This PR doesn't change that.

• The Blob test fails if the server stops excluding parts that have a filename — both platforms
• It also fails if the server takes the last part with a filename instead of the first. The check on the uploaded filename is what catches that; without it, the test still passed under that change
• swift test — 396 tests green
• :Gutenberg:testDebugUnitTest — 30 tests in MediaUploadServerTest green
• SwiftLint clean

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/688")

_{Built from 5620d2b}

[dcalhoun]

Looks good. Captured a few inline suggestions from Claude, but none of them are blocking.

[dcalhoun]

Finding from Claude:

Two predicates doing two different jobs on the same array:

• :210 — parts.first(where: { $0.filename != nil }) picks the file: the first filename-bearing part.
• :216 — parts.filter { $0.filename == nil } picks the fields: only the filename-less ones.

So a second filename-bearing part is neither. first has already returned, and the filter excludes it for having a filename — it falls out of the request entirely. (On this path, at least; the passthrough at :301 relays the original body verbatim, so it survives there.)

The rule's conclusion is still safe — :216 excludes every filename-bearing part, so raw bytes can't reach the decode. It's the stated reason that's off: "never as a field" holds for all of them, but "handled as the file" holds only for the first, and implies a second Blob gets processed as an upload when it's actually dropped.

Suggested change

	/// 3. The only way a browser can put *raw* bytes in a form is a file or a Blob, and
	/// those always arrive with a filename. Anything with a filename is handled as
	/// the file, never as a field — so raw bytes never reach this decode.
	/// 3. The only way a browser can put *raw* bytes in a form is a file or a Blob, and
	/// those always arrive with a filename. Anything with a filename is excluded from
	/// the fields, so raw bytes never reach this decode. (The first such part is the
	/// file; on this path any others are dropped.)

Same wording on MediaUploadServer.kt:614-616.

[dcalhoun]

Finding from Claude:

This says bad bytes can't reach multipartBodyStream, but multipartBodyPreservesNonUTF8FieldValue — "forwards a non-UTF-8 field value verbatim", MediaUploadServerTests.swift:836 — calls this function with exactly those bytes. The rationale this replaced was the text that test pointed at.

The risk is someone reads the new sentence and deletes the test as vacuous. Scoping it would keep both true, e.g. "Bad bytes can't reach here via the server; this function's own handling of them is pinned by multipartBodyPreservesNonUTF8FieldValue."

Same on MediaUploadServer.kt:719.