Writer — Deep Reference (Gated)

Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.

At a glance

This page documents the incremental-update append-only rule and Object Stream limits beyond the public landing page. The wording follows controlled, single-meaning terms because this content is signature-adjacent.

Edition gate

Requires NextPDF Pro, installed via composer require nextpdf/premium. Get a license.

License feature flag

No per-feature license flag. The Pro edition gates the code.

Behavior contract

IncrementalUpdateWriter::writeRevision writes one revision. It snapshots the existing buffer prefix before writing. It re-writes the catalog with merged entries, registers new object offsets, writes a traditional cross-reference table grouped into contiguous subsections, and writes a trailer with /Size, /Root, /Prev, and /ID. After writing, it compares the prefix again. If any earlier byte changed, it raises a writer exception that carries an append-only-violation state, and it does not return a usable output. On success it returns the byte offset of the new cross-reference table for chaining further revisions. Mixing cross-reference tables and streams across revisions is permitted.

ObjectStreamWriter accumulates objects. addObject raises an overflow error when the combined index and body would exceed the maximum (65,536 bytes uncompressed). build raises an error on an empty stream; otherwise it compresses the index plus body and returns the Object Stream content with the /Type /ObjStm, /N, /First, /Length, and /Filter /FlateDecode entries. The caller assigns the object number and wraps the markers.

Public API surface

composer require nextpdf/premium

Public types: IncrementalUpdateWriter, ObjectStreamWriter, ObjectStreamEntry, ObjStmCompressor, ObjStmCompressionResult, and the Object Stream write exception. The append-only rule is enforced inside the writer for every caller.

Conformance

The source annotates the ISO 32000-2 incremental-update grammar and Object Stream model, and the ETSI EN 319 142-1 PAdES revision-chaining requirements. The RAG corpus was unavailable at authoring time, so this page repeats only the clause references the source declares and asserts no additional external clause identifiers.

Edge cases & FIPS-mode behavior

The append-only check copies the existing prefix. Its cost grows with the size of the already-written document. This cost is intentional.
The Object Stream limit applies to the uncompressed index plus body. Place the encryption dictionary and other excluded object types as direct indirect objects.
The writer performs no cryptographic operations itself. It protects signed bytes by refusing to emit when an earlier byte would change. FIPS algorithm selection is governed by the signing module.