feat!: collapse FileMeta into a single type

[andiwand]

🤖 Generated with Claude Code

Clears the second of the two Breaking API changes (next major) items in
docs/design/README.md (the first landed in #625). With this the section is empty
and both entries are removed, so nothing deprecated or explicitly deferred remains
before the v6 tag.

Why

FileMeta carried an std::optional<DocumentMeta>, so every reader of a document
property went through two hops and an optional check, and every backend building
one had to remember to materialise the nested struct first. The indirection bought
nothing — DocumentMeta was never handed out independently except through
DocumentFile::document_meta(), which is just a second way of reading what
file_meta() already returns.

What

DocumentMeta's fields move up into FileMeta; the optional's presence check
becomes document_type != DocumentType::unknown.

Breaking changes

C++

• odr::DocumentMeta is gone; its fields are members of odr::FileMeta.
• FileMeta::document_meta is gone. document_type is a direct member, unknown
  when the file is not a document; the remaining document fields are only
  meaningful when it is set.
• DocumentFile::document_meta() and the abstract::DocumentFile::document_meta()
  virtual are gone — use file_meta().
• FileMeta's two constructors are gone; it is an aggregate.

Java — DocumentMeta removed, its fields are on FileMeta,
DocumentFile.documentMeta() removed.

Python — DocumentMeta removed, its fields are on FileMeta,
DocumentFile.document_meta() removed.

One JSON change (an earlier revision of this description wrongly said "unchanged")

meta_to_json is unchanged for every file with a known document type — it already
flattened both structs into one object.

It does change for an office container whose document type cannot be named.
The old backends assigned a default-constructed DocumentMeta before returning,
so an encrypted OOXML package emitted "documentType": "unknown". The flat struct
cannot distinguish "not a document" from "document of unknown type", so those files
now omit the document keys like any other non-document.

The reference-output run puts an exact number on the blast radius: 326 of 328
outputs matched, and the two that changed are docx/encrypted.docx/meta.json and
xlsx/encrypted.xlsx/meta.json, each losing one line:

 {
-    "documentType": "unknown",
     "fileCategory": "unknown",
     "fileType": "unnamed",
     "isEncrypted": true
 }

That line said nothing its three neighbours did not already say, and a plain text
file never got a documentType key at all — so the new behaviour is also the more
consistent one. Reference outputs updated accordingly (no HTML moved, and
odr-private is untouched).

Thanks @chatgpt-codex-connector for catching this — it was a real behaviour change
hiding behind an "output unchanged" claim. The gate is now commented in
odr_meta_util.cpp so it reads as deliberate.

Note on the PDF backend

populate_document_meta was all-or-nothing: a parse throw left document_meta
unset rather than half-filled. Flattening would have silently lost that, since
fields are now written straight onto FileMeta, so the helper fills a copy and
commits it only on success. Behaviour is preserved and the invariant is now
spelled out in pdf/AGENTS.md.

Note on aggregate initialisation

The backends first used designated initializers naming only the three non-document
members. GCC rejects that under -Werror=missing-field-initializers even though
the remaining members have default member initializers, so they build the value
field by field instead — matching how odf_meta / ooxml_meta / oldms_file
already did it.

Test plan

• Full C++ suite (excluding the slow HTML-output regression): 466 passed.
• Full suite incl. HTML output, compared against the reference tree: 326/328
  matched before the reference bump, the 2 above after.
• Python bindings: 41 passed, incl. a new assertion that a non-document (CSV)
  reports document_type == unknown with the document fields unset — the sentinel
  that replaces the optional.
• JNI bindings: 31 passed, incl. the reworked FileMeta constructor signature.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5abc4472a7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".