sorcery-go/docs/RITUAL_OF_CASTING.md

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:

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