> ## 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

> Why filepacks artifacts are byte-stable and why that matters for review, CI, and agent workflows.

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:

| Field   | Value        |
| ------- | ------------ |
| `uid`   | `0`          |
| `gid`   | `0`          |
| `uname` | empty string |
| `gname` | empty string |
| `mode`  | `0644`       |
| `mtime` | Unix epoch   |
| `type`  | regular file |

## 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.