Determinism

Documentation Index

Fetch the complete documentation index at: https://filepacks.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Determinism is a core guarantee of the current public format. For the same logical input, a canonical producer should emit the same .fpk bytes.

​

What the current implementation does

The public core package achieves deterministic output through:

• lexical directory traversal
• lexical sorting of manifest file entries
• lexical sorting of payload archive entries
• exact payload bytes without conversion
• fixed tar header metadata
• stable manifest serialization
• manifest.json written first

​

Why deterministic bytes matter

Deterministic output makes the archive digest meaningful. That matters when you want to:

• identify an artifact by hash
• compare repeated runs without ambiguous packaging differences
• preserve CI or agent evidence in a form another machine can trust later
• prove that two producers emitted the same artifact for the same logical input

​

Tar header canonicalization

The current public spec fixes these tar header values for every archive entry:

​

Test coverage

The current core tests verify:

• identical logical input produces byte-for-byte identical archives
• the shipped valid example artifact remains byte-stable and verifiable
• malformed archives such as non-file entries are rejected deterministically

​

What breaks determinism

Determinism would be broken by behavior such as:

• non-lexical traversal
• carrying through source filesystem timestamps or ownership
• emitting directory entries
• changing manifest serialization
• writing payload entries in a non-canonical order

Those behaviors are intentionally excluded from the current public format.

​

Practical takeaway

If two .fpk artifacts have the same archive digest, they are byte-for-byte identical. If they differ, compare will tell you whether the packaged file inventory changed structurally.