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

```json
{
  "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:

```json
{
  "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:

```bash
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.