sorcery-go/docs/ESSENCE_SPEC.md

Essence Specification (.ess)

"Every Essence is sealed with a Merkle root. If a single bit flips, the Warding rejects it."

1. File Format

An Essence is not a single file — it is a logical bundle stored in the Tomb:

/var/lib/sorcery-go/tomb/
├── epitaphs/                      # metadata sidecars
│   └── <merkle_root>.json         # the Sarcophagus
└── blobs/                         # content-addressed file bytes
    ├── ab/
    │   ├── abc123...              # one file, named by its sha256
    │   └── abd456...
    └── cd/
        └── cdef789...

2. Sarcophagus (Epitaph)

Every Essence has an Epitaph — a JSON sidecar that records the metadata.

{
  "essence_id":   "9f4e2a8b...",
  "spell_name":   "wget",
  "version":      "1.21.4",
  "variant_hash": "7c3d1e9f...",
  "arch":         "x86_64",
  "linkage":      "dynamic",
  "config": {
    "ssl": true,
    "ipv6": true,
    "nls": false
  },
  "files": {
    "/usr/bin/wget":  "abc123...",
    "/usr/share/man/man1/wget.1.gz": "def456..."
  },
  "created_at": "2026-03-17T22:07:18Z",
  "toolchain": "gcc-15.1.0-musl",
  "license":   "GPL-3.0-or-later"
}

3. Variant Hash

The Variant Hash is the "Soul" of a binary. Every unique combination of (version, y/n flags, arch, toolchain, linkage) produces a unique hash:

variant_hash = sha256(spell_name || version || sorted(flags) || arch || toolchain || linkage)

Two different flag combinations never collide in the Tomb — this lets the Coven simultaneously hold multiple "flavors" of the same spell.

4. Merkle Root

The essence_id is the Merkle root of the file set:

merkle_root = sha256( concat( sort(paths) || file_hashes ) )

If any file in the Sarcophagus changes — even by a single bit — the recomputed root diverges from the stored essence_id and the Warding rejects the Essence as Tainted.

5. Linkage Specification

Type	Libc	Use Case
dynamic	glibc	Standard LXC fleet (small footprint, central patching)
static	musl	Portable Tool Bin (runs on any Linux kernel)
hermetic	musl + bundle	AppImage-style self-contained Essence

6. Multi-Arch Essences

The arch field prevents the Hydration engine from accidentally mapping x86_64 binaries into an AArch64 container:

{
  "arch": "aarch64",
  "instruction_set": "ARMv8-A",
  "merkle_root": "9f4e2a8b..."
}

7. PGP Attestation

While the Coven handles internal Merkle sealing, the Grimoire itself is expected to be PGP-signed by the High Mage:

gpg --detach-sign -a grimoire/libs/openssl/DETAILS
sorcery-go cast openssl --verify-pgp

The Tablet records who signed each spell — the WebUI shows a "Trusted Source" badge next to the Essence in the Tomb.