sorcery-go/docs/METADATA.md

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:

# 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:

# 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.