docs(swarm): SWARM_SPEC.md v1 — wire-format contract (closes #74)

[Dewinator]

Summary

• Adds docs/SWARM_SPEC.md v1.0 — the wire-format contract for the decentralized mycelium swarm.
• Spec-only (no code, no migrations). Future swarm phases (1–9) implement against this single contract.
• Restates the three unverletzlichen Designprinzipien (Souveränität, Generalisierung-vor-Sharing, Diversität) at the top so every later phase can be checked against them.

Research summary

• Existing docs/ style mirrors affect-observables.md and middleware.md — design-doc voice, mermaid where it earns its keep, explicit rejection rules.
• No prior SWARM* material in the repo; closest precedent is the older engram-mcp Stand 2026-04-23 commit 925b6f9 docs swarm roadmap referenced in vector-memory.
• Recall surfaced the Schwarm-These (3acb8bb1-…): "Diversität ist nicht reproduzierbar — kein GPU-Count schlägt sie." Encoded directly into Designprinzip 3 and the rejection-rule design (no convergence pressure).
• RFC 8785 (JCS) is the only widely-implemented JSON canonicalization with reference libraries in JS, Rust, Go, Elixir — picked for v1. Implementer-warning subsection added because ECMAScript number serialization on float[768] embeddings is the obvious footgun.
• Ed25519 chosen as the only signature algorithm in v1; key rotation explicitly deferred to v2 to keep node_id = multihash(pubkey) self-certifying.

What this does NOT do

• No implementation of any wire type — that is the next 9 swarm phases.
• No DB migrations, no schema changes, no MCP tool changes.
• No transport beyond HTTPS — no libp2p, no DHT, no WebSocket push, no NAT traversal, no key rotation, no encrypted-record envelope, no differential privacy. All explicitly listed in §6 as out-of-scope-for-v1.
• No README.md cross-link or other repo-wide doc reshuffle. Easy follow-up if desired.
• No change to CONSTITUTION.md.

Constitution affirmation

This spec touches:

• Pillar 1 — Decentralized, networked AI → reinforced. Discovery via .well-known + gossip; no central registry; every endpoint optional; offline is the default-correct state.
• Pillar 3 — Swarm intelligence → reinforced. Lesson and HubAnchor are the units that let many specialized nodes pool knowledge without flattening difference; the Generalization rule (§3.1) keeps episodic diversity local.
• Pillar 6 — Cyber security → reinforced. Every wire record is signed (Ed25519 over JCS), node_id is self-certifying via multihash, transport is TLS-only, rejection rules are uniform across implementations.

No pillar is weakened. Pillars 2, 4, 5 are not touched and continue to be governed by their respective subsystems.

Test plan

• Read docs/SWARM_SPEC.md end-to-end.
• Verify the three Designprinzipien in §0 match the recalled Schwarm-These memory and the Constitution.
• Pick one wire type (e.g. Lesson) and try to derive a Postgres column list from §3.1 alone — should be unambiguous (uuid, text, vector(768), int, text, timestamptz, bytea, timestamptz, text[], text). If two reviewers get different types, the spec failed acceptance criterion N2: Middleware-Skelett (Reverse-Proxy vor dem Gateway) #2.
• Confirm mermaid block in §7 renders on GitHub.
• Confirm §6 lists every deferred concern from the issue body (NAT, libp2p/DHT, WebSocket, key rotation, encrypted transport beyond HTTPS, differential privacy).

[Dewinator]

The conductor auto-merger will not merge this PR for the following reason(s):

• mergeStateStatus=UNKNOWN

Resolve the blockers (or remove the agent-opened label for human review) to proceed.

[Dewinator]

The conductor auto-merger will not merge this PR for the following reason(s):

• mergeStateStatus=UNKNOWN

Resolve the blockers (or remove the agent-opened label for human review) to proceed.