139 lines
7.3 KiB
Markdown
Executable File
139 lines
7.3 KiB
Markdown
Executable File
# Sorcery-Go Architecture
|
|
|
|
## 1. The Core Thesis
|
|
|
|
Traditional source-based package management suffers from sequential fragility:
|
|
if a single shell script fails, the entire system state becomes ambiguous.
|
|
Sorcery-Go replaces procedural "instructional scripts" with declarative state
|
|
managed by Go-grade concurrency and ACID transactions.
|
|
|
|
## 2. The Three Pillars
|
|
|
|
### I. Deterministic Isolation (The Sandbox)
|
|
|
|
- **Old way:** `make install` writes directly to the live root. If it fails, the
|
|
system is tainted.
|
|
- **Go logic:** Every build occurs in an OverlayFS sandbox. The compiler sees
|
|
the system, but the system never sees the compiler.
|
|
- **Result:** Installations are atomic — they either succeed completely and are
|
|
committed, or they fail and vanish without a trace.
|
|
|
|
### II. Relational Intelligence (The DAG)
|
|
|
|
- **Old way:** Procedural loops check dependencies one by one.
|
|
- **Go logic:** The entire Grimoire is indexed into a directed acyclic graph
|
|
with feature-aware edges (Build / Runtime / Optional + sub-depends).
|
|
- **Result:** Parallelism is no longer a guess — the engine knows exactly which
|
|
spells can be built simultaneously without a race condition.
|
|
|
|
### III. The Single Source of Truth (BoltDB)
|
|
|
|
- **Old way:** Flat text files in `/var/lib/sorcery` that can be partially
|
|
written or corrupted.
|
|
- **Go logic:** A transactional, ACID-compliant KV store (bbolt) journals every
|
|
intent.
|
|
- **Result:** If the power cuts out, the recovery engine reads the journal and
|
|
resumes the exact byte-stream where it left off.
|
|
|
|
## 3. System Map
|
|
|
|
```
|
|
+-----------------------------------------------+
|
|
| The Coven (Firewall-Isolated Ley-Lines) |
|
|
| +----------+ +----------+ +--------+ |
|
|
| | Master |--| Worker A |--| Worker | |
|
|
| | Sanctum | | (x86_64) | | B(arm) | |
|
|
| +----+-----+ +----------+ +--------+ |
|
|
| | |
|
|
| +----v--------------------------------------------+ |
|
|
| | Cauldron (Cast Pipeline) | |
|
|
| | +-- Sub-Depends Solver | |
|
|
| | +-- Variant Hash (y/n + arch) | |
|
|
| | +-- Sandbox (OverlayFS + NS) | |
|
|
| | +-- Committer (atomic rename) | |
|
|
| +----+--------------------------------------------+ |
|
|
| | |
|
|
| +----v-------+ +--------------------+ |
|
|
| | Tomb | | Warding | |
|
|
| | (Merkle |<-->| (eBPF Tomb Guard) | |
|
|
| | CAS) | +--------------------+ |
|
|
| +----+-------+ |
|
|
| | |
|
|
| +----v--------------------------------------------+ |
|
|
| | Tablet (BoltDB) | |
|
|
| | +-- Journal (resume on reboot) | |
|
|
| | +-- Manifests (file list/spell) | |
|
|
| | +-- Tablet (y/n answers) | |
|
|
| | +-- Configs (variant hashes) | |
|
|
| +-------------------------------------------------+ |
|
|
| |
|
|
| +--------------------+ +-----------+ |
|
|
| | Legal Sentinel | | Coven | |
|
|
| | (SPDX/SBOM) | | Mirror | |
|
|
| +--------------------+ | (WebUI) | |
|
|
| +-----------+ |
|
|
+--------------------------------------------------------+
|
|
|
|
|
v
|
|
+-----------------+
|
|
| Sanctums |
|
|
| (LXC / Podman |
|
|
| / Firecracker |
|
|
| / baremetal) |
|
|
+-----------------+
|
|
```
|
|
|
|
## 4. Lifecycle of a Spell
|
|
|
|
1. **Query** — User defines intent via CLI, TUI, or WebUI.
|
|
2. **Resolve** — Sub-Depends Solver ensures every library variant is compatible.
|
|
3. **Forge** — Master shards the build; workers execute in isolated namespaces.
|
|
Distributed scheduling is delegated to Fester when a cluster is active.
|
|
4. **Sign** — Resulting binary is hashed and stored as a Sarcophagus in the Tomb.
|
|
5. **Hydrate** — Target Sanctums are atomically updated via reflink/hardlink swaps.
|
|
6. **Verify** — Warding recomputes the Merkle root on first execution; mismatch
|
|
triggers quarantine.
|
|
|
|
## 5. Toolchain Synergy
|
|
|
|
| Tool | Role | Logic |
|
|
|-----------|-----------------|-------------------------------------------------------------|
|
|
| Quill | The Scribe | Type-safe metadata generation. No more sed hacking. |
|
|
| Sorcery | The Engine | High-concurrency worker-stealing build orchestration. |
|
|
| Cauldron | The Blacksmith | Image composition via JSON/YAML manifests. |
|
|
| Gaze | The Eye | Reverse-path inventory + SBOM export. |
|
|
| Warding | The Shield | eBPF Tomb Guard + OpenSnitch/Portmaster + firewall isolation.|
|
|
| Legal | The Lawyer | License policy + SBOM + attribution bundles. |
|
|
| BTC.sh | The Forge | Sovereign cross-compilation across 19 target architectures. |
|
|
|
|
## 6. Why Go
|
|
|
|
- **Static binaries** — The entire toolchain is one binary. It can repair a
|
|
system even if glibc or bash is broken.
|
|
- **Concurrency** — Goroutines handle thousands of package checks with minimal
|
|
RAM.
|
|
- **Low-level access** — Direct syscall management of namespaces and mounts
|
|
without external wrappers.
|
|
|
|
## 7. Deployment Targets
|
|
|
|
- LXC / LXD containers managed by Cockpit
|
|
- Podman rootless containers
|
|
- Firecracker micro-VMs
|
|
- Bare-metal Source Mage hosts (systemd or OpenRC)
|
|
- Immutable infrastructure (squashfs ISOs from the Cauldron)
|
|
- CI/CD pipelines (automated spell testing + essence promotion)
|
|
|
|
The eBPF Tomb Guard provides in-kernel enforcement that works uniformly
|
|
across all of the above runtimes — no per-runtime profile syntax needed.
|
|
|
|
## 8. Architecture Summary
|
|
|
|
| Layer | Component | Tech Stack |
|
|
|-----------|---------------|---------------------------------------------------|
|
|
| Logic | Sorcery-Go | Go (static binary) |
|
|
| Storage | Tomb | Content-addressable Merkle CAS |
|
|
| Scheduling| Fester | DAG-driven distributed build execution (port 8181)|
|
|
| Security | Warding | eBPF LSM + cgroup filters + firewall + OpenSnitch |
|
|
| Compliance| Legal Sentinel | SPDX / CycloneDX |
|
|
| Control | Coven Mirror | Cockpit + WebUI API (port 8080) | |