Output formats and session bundles

Published baseline: v0.10.3.

This page describes the native bundle contract shipped in v0.10.0 on 2026-09-15 and retained by v0.10.3. It does not claim that an independent security audit or universal live-title compatibility has been demonstrated. S151 changes no artifact schema or retained observation contract; the Native product contract owns the complete status boundary.

Capture outputs

Capture writes standard pcapng or packet JSON Lines per sink. .fcapng is ordinary pcapng with process, role, stage, direction, and attribution fidelity in standard packet comments. Unmodified analyzers read it as packet truth, even when they ignore those comments. --out FILE.fcapng and file: select packet output; jsonl: selects packet JSON Lines. The CLI reference defines the actual sink grammar.

Packet JSON Lines begins with a header, has one packet per intervening line, and ends with a reconciling trailer after orderly finalization. It is not application.jsonl. Committed pipeline goldens are generated and checked by product tests; use them rather than a shortened example whose counts cannot reconcile. A missing trailer is an unfinished stream, not successful finalization.

Selected Capture scope governs packet admission. Default target scope omits other-process and unattributed packets with named counts; --scope all retains them with attribution state. --no-payload explicitly omits admitted payload bytes while retaining metadata. Packet, kernel, buffer, sink, scope, and bound counts do not describe proxy inspectability or application retention. Encrypted wire bytes remain ciphertext in packet truth.

Native manifest version 2

Read manifest.json first when it exists. Manifest version 2 separates the bundle schema from product.version and declares expected artifact roles, authority, sensitivity, relative paths, finalization, completeness, loss, correlation, and omissions. Version 1 is a legacy read-only format; new native bundles use version 2.

The published schema is byte-identical to the embedded schema. Full synthetic complete, partial, and crash-prefix specimens are validated by the actual ManifestDocument reader. fragcap schema validate owns target documents; it is not a general manifest, application-stream, or HAR validator.

Independent outcomes

A completed operation does not establish complete observation of every target flow. A partial operation can clean up successfully. A retained file can be useful despite an incomplete stream. Unknown and unavailable outcomes stay explicit rather than borrowing another artifact's success.

Artifact authority and lifetime

Expected does not mean produced. Absent artifacts have omission or failure declarations instead of fabricated paths. Private-material sensitivity follows the manifest's exact class; a packet artifact's ordinary class does not make it safe to publish. Completed evidence is retained until exact confirmed cleanup. Normal shutdown removes owned runtime effects and private temporary material, not the operator's evidence bundle.

Application JSON Lines version 2

application.jsonl begins with application.header, appends typed observations and loss records, and finishes with one reconciling application.trailer on orderly shutdown. A readable prefix remains useful but incomplete. Protocol metadata and payload bytes preserve available representations, including explicit base64 fields for byte-bearing values. HTTP/1.1 keeps wire metadata order and casing; HTTP/2 declares original HPACK bytes and compressed cross-name order unavailable rather than inventing them.

Raw observed bodies, WebSocket frames, generic stream chunks, and routed UDP datagrams remain independent from bounded retained prefixes and decoded derivations. Forwarding does not wait for retention. Queue, storage, truncation, transformation, and bounded identity overflow are counted. SSE and gRPC retain events, envelopes, and status without pretending to understand application-specific protobuf meaning. Traffic support specifies each engine's scope and refusal boundary.

HAR is a projection

--har requests http.har. Native HAR projection requires a complete reconciling application source and complete eligible HTTP transaction evidence. It does not fill unknown response status, size, timing, or body with guessed values or synthetic zeroes. Incomplete transactions and unavailable representations are omitted or declared under the projection contract. Projection is bounded and atomically published; it never outranks its application source.

Proxy-owned TLS key logs

--key-log requests client-facing server TLS material under the session authority. Its exact retained path is available to the analyzer workflow, but upstream TLS never enters that key log. Empty or unavailable production remains an omission, not a decryption claim. Pinning and trust failures are not bypassed. Treat retained key logs as highly sensitive and review the exact manifest declaration before sharing.

Correlation and omission vocabulary

Native connection correlation is reconciled after collection against timestamped packet-flow ownership. Session, proxy connection, HTTP stream, process instance, and flow identifiers answer different joins. Exact eligible matches can add ownership; ambiguous, unavailable, proxy-only, and packet-only states stay explicit. Timing or content similarity alone never invents attribution. No match does not prove no traffic occurred.

Manifest omission reasons are typed and separate from protocol refusals and cleanup dispositions. Read each role's reason, severity, completeness, loss, and correlation fields. Not requested, not produced, incomplete source, unsupported representation, and failed writing are different situations. The reader rejects unsafe relative paths and duplicate aliases rather than allowing arbitrary files to acquire bundle ownership.

Cleanup and sharing

Plain Doctor is read-only and leaves healthy retained evidence as history. Confirmed doctor --fix reconciles exact owned unfinished obligations; approval for a new session cannot authorize old-session recovery. Sensitive cleanup and export are separate actions:

fragcap doctor
fragcap doctor --fix
fragcap bundle export sample-bundle --out sample-share-copy
fragcap bundle cleanup sample-bundle --yes

Review the exact displayed bundle and declaration before destructive confirmation. Export creates a separate atomic transformed copy with a transformation manifest, leaving original observations intact. It does not guarantee every remaining packet, URL, header, identifier, or process detail is anonymous. Read security and privacy before sharing and Doctor troubleshooting when cleanup remains unresolved.