Freeze File¶

The freeze file (freeze1.pgn.yaml) is auto-generated by pGenie the first time pgn generate is run. It records the content hash of every code generator URL referenced in project1.pgn.yaml.

Purpose¶

The freeze file serves the same role as package-lock.json, Cargo.lock, or cabal.project.freeze: it ensures that everyone who runs pgn generate on a project gets identical output, regardless of when or where they run it.

Without a freeze file, a generator URL such as https://example.com/gen/Gen.dhall could silently change its content between runs (for example, if the remote file is updated or the CDN caches a different version). The freeze file prevents this by pinning each generator to a specific content hash. If the downloaded content does not match the recorded hash, pGenie aborts with an error.

Format¶

<generator_url>: sha256:<content_hash>

Each line maps a generator URL to the SHA-256 hash of the file at that URL at the time it was first fetched. Example:

https://raw.githubusercontent.com/pgenie-io/haskell-hasql.gen/v0.1.0/gen/Gen.dhall: sha256:fcc51fe6ae2f774bcb13684b680aae1a9b827451c3f56c1ae2875f1e64fe78e5

Lifecycle¶

Event	What pGenie does
First run (no freeze file)	Downloads each generator and writes `freeze1.pgn.yaml` with the content hashes
Subsequent runs (freeze file present)	Downloads each generator and verifies it matches the recorded hash; aborts if there is a mismatch
Generator URL updated in `project1.pgn.yaml`	The old hash entry is no longer used; pGenie downloads the new URL and adds a new entry
Freeze file deleted	Treated as "first run" — pGenie re-fetches all generators and writes a new freeze file

Upgrading a Generator¶

To upgrade to a newer version of a generator:

Update the URL in project1.pgn.yaml to point to the new version tag.
Delete the corresponding line from freeze1.pgn.yaml (or delete the entire file).
Run pgn generate. The new generator is fetched and its hash is recorded.

Version Control¶

Commit freeze1.pgn.yaml to version control alongside project1.pgn.yaml and your signature files. This guarantees that CI/CD pipelines and other contributors reproduce exactly the same generated artifacts.

Versioning¶

The filename suffix freeze1 refers to version 1 of the freeze file format. Future breaking changes to the format would introduce freeze2.pgn.yaml.