69 lines
2.0 KiB
Markdown
Executable File
69 lines
2.0 KiB
Markdown
Executable File
# 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. |