sorcery-go/README.md

# Sorcery-Go — The Sovereign Coven

**Sorcery-Go is an independent project developed by dcos.net. It is not
produced by, affiliated with, endorsed by, or connected to Source Mage
GNU/Linux or sourcemage.org in any official capacity.**

Sorcery-Go is a high-concurrency, source-based infrastructure management
suite. It implements a spell format compatible with Source Mage GNU/Linux
grimoires for convenience, but the two projects have separate maintainers,
separate codebases, and separate governance.

It organizes independent Linux Sanctums (LXC containers or bare-metal hosts)
into a unified Coven, connected by firewall-isolated Ley-Lines. Every spell
cast through the Cauldron is sealed as a content-addressable Essence inside the
Tomb, defended by the Warding, and audited by the Legal Sentinel.

## Core Components

| Component        | Role                                    | Modern Upgrade                                           |
|------------------|-----------------------------------------|----------------------------------------------------------|
| The Cauldron     | Build engine that boils source to bins  | High-concurrency Go + OverlayFS sandboxes                 |
| The Tablet       | Persistent y/n configuration memory     | ACID BoltDB (journalled, recoverable)                     |
| The Tomb         | Binary storage / CAS                    | Merkle-tree, deduplicated Sarcophagi                      |
| The Warding      | Security and integrity boundary         | eBPF Tomb Guard + cgroup filters + OpenSnitch/Portmaster + firewall isolation |
| The Sanctum      | Isolated runtime                        | LXC / Podman / Firecracker / baremetal (reflink hydration)|
| The Coven        | Distributed cluster                     | Firewall-isolated Ley-Lines, Fester-scheduled builds      |
| The Gaze         | Inventory and audit query               | Reverse path index, SBOM export                           |
| The Legal Sentinel| License compliance                      | SPDX/CycloneDX, 3 posture templates                       |
| The Coven Mirror | WebUI (Cockpit-integrated)              | Monaco IDE, Fleet dashboard, Portable Bin                 |

## Security Model

Sorcery-Go uses a **firewall-first security architecture**. Transport security
is delegated to the network boundary (OPNsense / IPFire). There is no
application-layer TLS or mTLS — no certificate management, no key rotation,
no CRL propagation. The defense-in-depth model relies on:

1. **eBPF LSM (Tomb Guard)** — in-kernel enforcement blocking writes to the Tomb
2. **eBPF cgroup filters** — device and network control
3. **Network firewall** — OPNsense / IPFire isolating the Coven
4. **Per-process filtering** — OpenSnitch or Portmaster
5. **Content-addressing** — Merkle root + per-blob hashing for integrity
6. **Quarantine** — cgroup freezer for containment

All `crypto/rand`, `crypto/tls`, and `crypto/x509` code has been removed.
Task IDs are generated deterministically using atomic counters and nanosecond
timestamps.

## Quick Start

### Drop into an existing Source Mage-compatible chroot

If you have a Source Mage chroot with a modern toolchain (GCC 12+, glibc 2.35+):

```bash
make build
sudo make drop-in                        # installs to /usr/local/sbin/sorcery-go
sudo sorcery-go cast busybox --static --default
sorcery-go gaze install busybox
sudo sorcery-go web --port 8080
```

Full guide: [docs/INSTALL.md](docs/INSTALL.md)

### Resurrect an old Source Mage tarball (0.62-11 / 0.63 test)

The 8-phase staging pipeline in `scripts/smgl-getting-started.sh` walks you
through purging GRUB 1, injecting a modern kernel, swapping to the live test
grimoire, step-upgrading the toolchain ladder, and dropping in sorcery-go.
Note: Source Mage tarballs are produced by the Source Mage project at
sourcemage.org. Sorcery-Go can use them but is not affiliated with that
project.

Full guide: [docs/GETTING_STARTED_SMGL_CHROOT.md](docs/GETTING_STARTED_SMGL_CHROOT.md)

## BTC.sh Cross-Compilation Integration

Sorcery-Go integrates with BTC.sh for multi-architecture cross-compilation via
`pkg/toolchain/btc.go`. The integration probes for golden images, parses
manifest JSON sidecars, and configures build environments for 19 supported
targets:

| Family           | Targets                                                        | ISA Tiers        |
|------------------|----------------------------------------------------------------|------------------|
| Intel HEDT/Server| haswell, haswell-ep, skylake, skylake-x, skylake-server       | AVX2, AVX512     |
| AMD Ryzen/EPYC   | znver1, znver2, znver3, znver4                                 | AVX2, AVX512     |
| AMD APU          | apu-zn1, apu-zn2, apu-zn3, apu-zn4                             | AVX2             |
| Intel Atom       | atom-silvermont, atom-goldmont, atom-tremont, atom-sierraforest| SSE4_2           |
| Embedded         | mipselr2, armv7, tilegx                                        | MIPS32, NEON, TILE|

## Project Layout

```
sorcery-go/
+-- cmd/
|   +-- sorcery/    # Unified CLI (cast, reanimate, tomb, ward, legal, web, gaze)
|   +-- quill/      # Spell creation wizard
|   +-- cauldron/   # Image compositor + portable bin
|   +-- warding/    # Security monitor CLI
|   +-- gaze/       # Inventory query CLI
+-- pkg/
|   +-- config/     # Runtime config + path management
|   +-- eventbus/   # Typed pub/sub (CLI/TUI/WebUI shared truth)
|   +-- dag/        # Dependency graph + cycle detection + sub-depends solver
|   +-- grimoire/   # DETAILS / DEPENDS parser + indexer (spell format compatible with SMGL)
|   +-- sandbox/    # OverlayFS + namespaces + streaming IO + toolchain attach
|   +-- state/      # bbolt journal + atomic committer + recover + reverse index
|   +-- tomb/       # Sharded Merkle CAS + Sarcophagus + reflink Reanimate
|   +-- cast/       # End-to-end pipeline + Summon + Unpack + ICE
|   +-- warding/    # PGP attestation + audit log watcher + cgroup quarantine
|   +-- legal/      # License policy + SBOM export
|   +-- cluster/    # Coven firewall-isolated cluster + Fester integration
|   +-- toolchain/  # BTC.sh validator + cross-compilation environment
|   +-- quill/      # Spell generator (text/template)
|   +-- cauldron/   # Image compositor + Portable Bin + Emergency Kit
|   +-- inventory/  # Gaze query engine (state + tomb lookups)
|   +-- web/        # Coven Mirror HTTP/WS server + per-task EventBus streaming
|   +-- cas/        # Shared CAS client for Fester artifact caching
|   +-- templates/  # Embedded DETAILS/BUILD/CONFIGURE templates
|   +-- ui/         # Bubble Tea TUI
+-- docs/           # Markdown standards (SGDS) + guides
+-- manifests/      # Runtime configs, eBPF profiles, OpenSnitch, Cockpit, ISO profiles
+-- scripts/        # bootstrap, deploy_grid, forge_first_sanctum
+-- grimoire/       # The spell directory
+-- go.mod
+-- Makefile
```

## Documentation

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — full system map
- [docs/SECURITY.md](docs/SECURITY.md) — Warding + eBPF Tomb Guard + firewall-first model
- [docs/INSTALL.md](docs/INSTALL.md) — drop-in installation guide
- [docs/GETTING_STARTED_SMGL_CHROOT.md](docs/GETTING_STARTED_SMGL_CHROOT.md) — ancient tarball resurrection
- [docs/QUICKSTART.md](docs/QUICKSTART.md) — first-flight cheat sheet
- [docs/TOOLCHAIN_SPEC.md](docs/TOOLCHAIN_SPEC.md) — custom compiler metadata
- [docs/SPELL_SPEC.md](docs/SPELL_SPEC.md) — per-spell schema
- [docs/ESSENCE_SPEC.md](docs/ESSENCE_SPEC.md) — Essence / Sarcophagus format
- [docs/METADATA.md](docs/METADATA.md) — documentation standard
- [docs/RITUAL_OF_CASTING.md](docs/RITUAL_OF_CASTING.md) — admin guide
- [docs/DISASTER_RECOVERY.md](docs/DISASTER_RECOVERY.md) — restore from Tomb backup

## License

Sorcery-Go is released under the AGPL-3.0-or-later by dcos.net.

**NOT AFFILIATED with Source Mage GNU/Linux or sourcemage.org.** Source Mage
GNU/Linux is developed at https://www.sourcemage.org/ under its own project
governance. Sorcery-Go implements a compatible spell format for convenience
but is an entirely separate project.