Puzzle API and frozen source publication review

Reviewed the high-level Python API, existing native solve/decrypt contract, and the public release artifacts/evidence. No Rust/client verification changes were made for this review.

Findings

1. Custom key output parent was not prepared before expensive solving — fixed. Reproduced Puzzle.solve(checkpoint=new/state/progress.jsonl, key_out=new/keys/epoch.key) against the real Nitro diagnostic fixture/native solver: computation completed, the checkpoint was retained, and key publication failed with ENOENT. The wrapper now creates the key directory with mode0700 and checks write/search access before entering the native solver. The regression uses separate new checkpoint/key directories, then resumes to the default output path and compares recovered keys. An invalid key parent that is an existing file fails before creating checkpoint state.

2. Checkpoint hardlink could corrupt the preserved manifest — fixed. The explicit collision check compares resolved paths, which catches symlinks but not two paths naming the same inode. A checkpoint hardlinked to the authenticated manifest passes that check. Actual native execution then appends checkpoint records into the manifest: reproduced file growth from 1,541 to 18,426 bytes with a successful solve. The wrapper now rejects samefile() aliases among existing paths before invoking native code, for both solve and decrypt operations. A regression with the real authenticated fixture and native binary configured proves original manifest/checkpoint bytes are retained and no key is written. Aliased decrypt inputs also fail before creating plaintext. This concerns local file preservation, not remote Nitro authentication.

3. Record-signature wording overstated the native guarantee — clarified. Native decryption verifies the manifest signature and record AEAD/epoch/key binding. The record envelope has no service signature. Once the epoch key becomes public, another key holder can produce a valid envelope, so matching an original archive record additionally needs a trusted digest/publication record. The README now states that distinction; the parent corrected the method docstring. The historical JSON fixture remains unchanged.

Trust and publication checks

Puzzle.from_url requires an independent PCR0, a content-addressed bundle URL, and successful historical Nitro/Graviton5 verification. It does not infer trust from a URL, bundled signer or displayed unsigned policy. Redirects, malformed pins, substituted artifacts and inconsistent unsigned policy are rejected by the current tests. Local HTTP is explicit and changes only outer transport.

The public release identifies frozen commit 474083ea74d0df069275da613e62a985d6960056 and the image observed warming. It explicitly excludes later entropy/CBOR patches and does not claim public relay readiness. Metadata identifies its separate evidence commit and distinguishes matching PCRs from differing complete EIF hashes. The plain archive and minimal shallow checkout contain exactly the frozen source; the shallow object store has one commit and no ancestors. The public manifest lists artifact byte hashes, and the local publication proof records anonymous full-byte checks for all ten objects, version IDs, restricted-public-read policy, 403 scope checks and the 412 no-overwrite probe. Versioning is not described as independent immutable retention. The scanner's limitations are disclosed.

One minor runbook wording limitation: shallow archives are intentionally reused after exact HEAD/clean-tree checks, rather than compared byte-for-byte to each new temporary checkout's index metadata. Source and other staged release files are compared byte-for-byte. This does not change the published artifact hashes.

Validation after both file-handling fixes: all 12 native-package tests passed, including real Nitro identity, offline native solve/resume/decrypt and tampered-record rejection. The hardlink case above was reproduced against the real native binary before the fix and now fails safely before native execution.