# Sorcery-Go Documentation Standard (SGDS)

Every module, spell, or Essence in the Coven must follow this standard.

## Engine

- **Engine:** Go 1.21+ (statically linked)
- **Storage:** Content-Addressable Essence (.ess) — Merkle trees
- **Security:** eBPF Tomb Guard + cgroup filters + network firewall isolation
- **Orchestration:** Cockpit-integrated WebUI (Coven Mirror)
- **Cluster:** Firewall-isolated Ley-Lines, Fester-scheduled distributed builds

## Essence Specification

Every Essence bundle documents its Merkle root and layering order:

```markdown
# Essence: openssl-3.2.1
## Cryptography
- **Root Hash:** `sha256:9f4e2a8b...`
- **Signature:** `ed25519:...`
- **Signer:** Build-Master-01

## Composition
- **Parent Essence:** `base-glibc-2.35.ess`
- **Added Blobs:** 142
- **Deduplication Ratio:** 84.2%

## Linkage
- **Type:** `ELF-Dynamic`
- **Libc:** `glibc-2.35`
- **Portable:** `False`
```

## Deployment Manifest (LXC Target)

Used by the deployment manager to hydrate a container:

```markdown
# Deployment: web-farm-alpha
## Infrastructure
- **Target Engine:** systemd / OpenRC
- **Firewall:** OPNsense (active) + OpenSnitch / Portmaster (per-process)
- **Isolation:** eBPF Tomb Guard (in-kernel enforcement)

## Hydration Recipe
1. Load `core-runtime.ess`
2. Inject `security-headers.ess`
3. Bind `/var/lib/sorcery-go/essences` (read-only)
```

## Compliance Profiles

| Profile         | Posture      | Use Case                     |
|-----------------|--------------|------------------------------|
| `strict_copyleft` | FSF/GNU    | Pure free-software fleet     |
| `corporate_lite` | MIT/Apache  | Risk-averse enterprise       |
| `lawless`       | Wildcard     | Sovereign — no license restrictions |

## Module Documentation

Every package under `pkg/` opens with a Go doc comment that explains:

1. The package's role in the Coven.
2. The public API (key types and methods).
3. Any side effects (disk I/O, network, kernel state).

See `pkg/dag/dag.go`, `pkg/tomb/storage.go`, and `pkg/toolchain/btc.go` for
examples.