File and Wire Formats

Extensibility through options is what lets fragcap carry attribution in a file that unmodified tools still read as an ordinary capture.

The governing rule is constitution principle P-5: an unmodified analyzer must read the file as ordinary pcapng and ignore annotations it does not understand. Attribution data is worth having only if the file remains a capture file. The annotation profile carries its own version, independent of the fragcap version, because the grammar and the software change on different schedules.

Its option area is where fragcap writes attribution, which is what makes the annotation invisible to tools that do not look for it.

Its byte-order magic is what makes a capture readable on a machine with the opposite endianness. fragcap always declares little-endian rather than host order: both are valid, and only one produces the same bytes for the same input on every architecture, which is what a golden comparison needs.

Interfaces are identified positionally, by declaration order, and every packet block references one by that index. An identifier with no preceding declaration leaves a reader with no link type, so the packet cannot be dissected at all.

Its standard fields describe losses upstream of the capturing application, and fragcap has counters of its own that no standard field expresses. Constitution principle P-4 makes an unsurfaced discard a defect, and P-9 forbids reporting a fragcap loss as an operating system loss, so those counters travel in a declared comment rather than being omitted or overloaded onto a field that means something else.

A comment rather than a custom option, deliberately. Every pcapng reader displays comments, so attribution is visible in an unmodified analyzer with no configuration, which is constitution principle P-5 in its practical form. Custom options would also require a Private Enterprise Number this project does not hold. The cost is parsing overhead in consumers and a modest size increase, and both are accepted.

Retained attribution is inferential rather than observed: an endpoint that closed and was reassigned to a different process inside the retention window attributes incorrectly. Recording which packets are exposed to that is what lets analysis discount them. A consumer never infers this value, because the distinction between an observation and an inference is precisely what a reader cannot reconstruct from the data.

Tests written alongside an implementation encode the author's assumptions, including the wrong ones. A golden encodes what the code actually produced on a day somebody looked, so a later change is visible to a reviewer who was not there. This only works if output is deterministic, which is why the writer reads no clock and fixes its byte order: a golden that legitimately varies is a golden that gets deleted the first time it fails.

The property that matters is that a line is self-contained: a stream can be split, tailed, filtered, or truncated with ordinary line tools and every surviving line is still a complete record. fragcap writes it for consumers that do not read pcapng, and it drives the differences from the .fcapng profile. The interface name appears on every record here and only in multi-interface captures there, because a pcapng file holds the interface in its container and a line has no container to hold it.

Its absence is the only way a consumer can tell a truncated stream from a complete one, which makes it load-bearing rather than decorative. It carries every counter even when zero, so that "nothing was lost" is distinguishable from "this build does not report that": the same reasoning that puts the counters in an Interface Statistics Block for the other format, and the reason constitution principle P-4 is satisfied for a consumer who never sees the pcapng file.

The key is omitted entirely rather than emitted empty, because an empty payload is a real observation that renders as an empty string. A consumer distinguishes the two by the length fields, which are present in both modes.

Lossless and reversible, which is why widening the escaped set beyond the grammar's own reserved characters does not conflict with constitution principle P-9. The alternative for a process name containing a newline would be stripping or replacing it, which alters the observation.