2.8 KiB

Executable File

Raw Blame History

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.

2.8 KiB Executable File Raw Blame History