81 lines
3.9 KiB
Markdown
Executable File
81 lines
3.9 KiB
Markdown
Executable File
# The Ritual of Casting
|
|
|
|
A guide for the Sovereign Admin — from the veteran shell-scripter to the new
|
|
hire. This ritual transforms raw source code into a hardened, portable Essence.
|
|
|
|
## I. The Gathering (Dependency and License Check)
|
|
|
|
Before the fires are lit, the Cauldron and the Warding must agree on the
|
|
ingredients.
|
|
|
|
- **The Ancestry** — the engine scans `DETAILS` and `DEPENDS`. If a library
|
|
is missing, it is queued for forging.
|
|
- **The Legal Seal** — the Legal Sentinel checks the spell's license against
|
|
the active posture (strict_copyleft, corporate_lite, or lawless). If you try
|
|
to cast a blacklisted AGPL tool under `corporate_lite`, the Warding
|
|
blocks the build before it starts.
|
|
|
|
## II. The Incantation (The Interactive y/n ICE)
|
|
|
|
The admin interacts with the Tablet. This is where you define the Soul of the
|
|
binary.
|
|
|
|
- **The Query** — the CLI asks: `? [wget] Enable SSL support? (y/n) [default: y]:`
|
|
- **The Memory** — your choice is saved in BoltDB. Next time you cast, the
|
|
Tablet remembers — ensuring your configuration is consistent across the
|
|
entire fleet.
|
|
|
|
Three interfaces share the same Tablet, so an answer you give in the WebUI
|
|
appears the next time you cast from the CLI.
|
|
|
|
## III. The Forging (Cross-Compilation and Toolchains)
|
|
|
|
- **The Cauldron** uses cross-toolchains — a powerful x86_64 Master node can
|
|
forge an AArch64 binary for an ARM edge-device, or an ARM binary for a
|
|
Raspberry Pi using a BTC.sh-forged toolchain.
|
|
- **The Coven** — if the build is massive (like glibc) and Fester is active,
|
|
the Master shards the work across cluster nodes via DAG-driven scheduling.
|
|
|
|
## IV. The Sealing (Merkle Hashing and the Tomb)
|
|
|
|
Once the binary is forged, it is sealed so it can never be corrupted.
|
|
|
|
- **The Merkle Tree** — every file in the build is hashed. These hashes are
|
|
combined into one final root hash (the `essence_id`).
|
|
- **The Tomb** — the Essence is stored under `/var/lib/sorcery-go/tomb/blobs/`.
|
|
It is now immutable. If a single bit changes, the Warding detects it
|
|
instantly and refuses Reanimation.
|
|
|
|
## V. The Hydration (Container Deployment)
|
|
|
|
Now the Essence must be brought to life inside a Sanctum.
|
|
|
|
- **Reflink / Hardlink** — instead of copying files, the engine links the
|
|
Essence into the container's filesystem. On btrfs or xfs this is zero-copy.
|
|
- **Atomic Swap** — when you upgrade a tool, the engine points the link to
|
|
the new Essence hash. To the container it looks like a standard update,
|
|
but it happens in under a second.
|
|
|
|
## Admin Troubleshooting — The Gaze
|
|
|
|
When a ritual fails or a node acts strangely, use the Gaze to see the truth:
|
|
|
|
```bash
|
|
sorcery-go gaze install <spell> # "Show me every file this spell owns."
|
|
sorcery-go gaze tablet <spell> # "Show me exactly how this was configured."
|
|
sorcery-go gaze essence <hash> # "Which spell + flags produced this blob?"
|
|
sorcery-go gaze whereis /usr/bin/wget # "Who owns this file?"
|
|
sorcery-go ward status # "Is the Warding active? Any tainted Essences?"
|
|
```
|
|
|
|
## Vocabulary Cross-Reference
|
|
|
|
| Traditional Term | Sovereign Term | Plain English |
|
|
|--------------------|--------------------|------------------------------------------------------------|
|
|
| Package | Essence | A cryptographically sealed folder of files |
|
|
| Build Server | The Coven | A team of servers compiling code together |
|
|
| Firewall / Audit | The Warding | The layer that stops bad code and illegal licenses |
|
|
| Symlink / Mount | Hydration | Attaching a tool to a container so it can run |
|
|
| State DB | The Tablet | The journal of every y/n answer you have ever given |
|
|
| Binary cache | The Tomb | The content-addressable storage where Essences rest |
|
|
| Container / Node | The Sanctum | The isolated runtime where software executes | |