Release note · August 4, 2026

A package thumbnail is a review boundary—not a preview claim

By SybilGambleyyu · DocFence 0.34.0 · DCAB 0.24.0

A thumbnail image stored in an OOXML package is easy to overlook because it is neither ordinary Word text nor a document-rendering instruction. It is still a relationship-bound package part. A handoff or publishing review can need to know that this stored boundary changed without extracting the image, guessing what it depicts, or promising that any client will show it.

DocFence 0.34 records that narrow boundary, and Document Change Assurance Benchmark (DCAB) 0.24 supplies a reproducible pair for it. Both releases are static-analysis work: they do not decode an image, render a document, open Word, or claim preview behavior in Word, Explorer, or another client.

Why a filename is not enough

The OOXML Thumbnail Part contract describes an image reached through a thumbnail relationship from the package or a part. The relationship is internal, each source can have at most one thumbnail relationship, and the thumbnail part cannot carry relationships of its own. The Open XML SDK exposes the same surface through AddThumbnailPart.

_rels/.rels                 root relationship material
  └─ metadata/thumbnail ──> docProps/thumbnail.png
[Content_Types].xml         image/png declaration
docProps/thumbnail.png      opaque stored bytes

That topology is what makes the boundary specific. DocFence accepts only the exact standard thumbnail relationship in Transitional or Strict OOXML, from the package or a stored part. The target must be internal, stored, image-typed, and relationship-free; malformed recognized topology fails closed. A member merely named thumbnail.png without the standard relationship remains generic package residue instead of becoming a guessed thumbnail.

Review evidence without an image side channel

Public DocFence reports expose only thumbnail_relationship_count and thumbnail_part_count. Image bytes, content types, relationship sources and targets, and part paths stay inside a private digest. That means a same-count image rewrite remains visible as package_thumbnail_inventory_changed without turning CI output into a copy of package metadata or image material.

There are two readable policy choices, depending on the intended boundary:

rules:
  require_no_package_thumbnails: true
  no_package_thumbnail_changes: true

require_no_package_thumbnails is a candidate-state gate for a clean handoff. no_package_thumbnail_changes compares an approved baseline with a candidate that may intentionally retain a thumbnail. They answer different questions, so a team can use either or both. The resulting findings are DFP080 and DFP081; neither includes image pixels or relationship details.

A deterministic, target-free benchmark pair

DCAB 0.24 adds its thirty-fifth pair: review.package_thumbnail_payload_changed. Baseline and candidate preserve one standard root thumbnail relationship, the image/png content-type declaration, their package-member set, and every stored w:t value. Only a fully synthetic 1×1 PNG payload changes.

_rels/.rels                 byte-identical
[Content_Types].xml         byte-identical
word/document.xml           byte-identical
docProps/thumbnail.png      the sole changed package member

The public truth names only package_thumbnail_payload_changed. It omits the relation source and target, part path, content type, image bytes, and fingerprints. The structural verifier regenerates the package byte-for-byte and checks the relationship and member boundary without decoding or rendering the stored PNG. A construction test verifies that the deterministic image is a valid inert 1×1 PNG; that is not a claim about document previews.

Evidence from an independent package

As a package-compatibility smoke test, the DocFence release profiles the public Open XML SDK AcademicLetter Word template. It reports one thumbnail relationship and one thumbnail part. The test does not inspect the thumbnail pixels or assert how a document client displays them.

DCAB’s optional adapter reaches a strict 35/35 score from DocFence 0.34’s public aggregate evidence. Its CI matrix passed on Python 3.11, 3.12, and 3.13, including a fresh DocFence 0.34 installation. Fresh wheel and source-distribution installs validate the bundled 35-case corpus, and the public Hugging Face dataset mirror was atomically synchronized and compared byte-for-byte for the release files.

Use the releases

python -m pip install https://github.com/SybilGambleyyu/docfence/releases/download/v0.34.0/docfence-0.34.0-py3-none-any.whl
python -m pip install https://github.com/SybilGambleyyu/document-change-benchmark/releases/download/v0.24.0/document_change_benchmark-0.24.0-py3-none-any.whl

docfence check approved.docx candidate.docx --policy docfence.yml --format sarif --output docfence.sarif
dcab validate
dcab docfence-observations --executable docfence --output observations.json
dcab score --observations observations.json --strict

The tagged policy reference, threat model, validation notes, and DCAB research notes define the exact scope. A package thumbnail is stored evidence worth reviewing when a policy says it is—not a rendering result and not a claim about what a user will see.