105 lines
2.8 KiB
Markdown
Executable File
105 lines
2.8 KiB
Markdown
Executable File
# 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.
|