Pack Format

Pack Format

Persona packs are content-addressed, signed tarballs designed for deterministic distribution.

Structure

A pack is a directory containing at minimum a pack.toml manifest:

my-persona/
  pack.toml       # Required: manifest
  persona.toml    # Optional: typed source (identity, voice, anchors)
  rules.toml      # Optional: typed source (L1/L2 rules)
  skills.toml     # Optional: typed source (skill declarations)
  patterns.toml   # Optional: typed source (code patterns)

Content addressing

Pack contents are hashed deterministically:

1. Recursive directory walk with files sorted by path.
2. Unicode normalization (NFC) on all paths and text content.
3. SHA-256 hash of the canonicalized byte stream.

Identical contents always produce the same hash, regardless of filesystem ordering, OS, or platform.

Signing

Packs are signed with Ed25519:

author_handle = "ghost-frame"
author_pubkey = "ed25519:<hex-encoded-public-key>"

The signature covers the canonical hash. Verification checks that the signature matches the declared public key and that the hash matches the pack contents.

Unsigned packs use author_pubkey = "UNSIGNED" -- valid for local development but not for marketplace distribution.

Cache layout

Installed packs live in the content-addressed cache:

$XDG_DATA_HOME/frameshift/cache/<sha256-hex>/

Multiple projects can share the same cached pack. The cache is a flat directory keyed by hash.

Lockfile

Each project tracks installed packs in lock.toml:

[[persona]]
name = "cryptographic"
version = "0.1.0"
hash = "sha256:<hex>"
author_handle = "ghost-frame"
author_pubkey = "ed25519:<hex>"

The lockfile records the exact version, hash, and author identity. frameshift sync reconciles the lockfile with the cache.

Garbage collection

frameshift gc

Removes cache entries not referenced by any project's lockfile. Safe to run at any time.