feat(swarm-protocol): open mirror of the Arcanea swarm packaging protocol

packages/swarm-protocol/.gitignore

@@ -0,0 +1,3 @@
+dist/
+dist-test/
+node_modules/

packages/swarm-protocol/README.md

@@ -0,0 +1,64 @@
+# @arcanea/swarm-protocol
+
+The chain-agnostic packaging layer for Arcanea agent swarms. A **Swarm Package Manifest**
+is the unit that gets tokenized as a Swarm License NFT and metered per-invocation across
+Base, Polygon, and Solana.
+
+A manifest composes: **topology** (queen + worker mesh), **agents** (portable specs;
+the licensed IP), **license terms** (forkable pattern vs. non-licensable encoded-self per
+SIP), **pricing** (license + per-call + EIP-2981 secondary), **royalty split**
+(creator/platform/treasury in bps, summing to 10000), **SIP attestation**, and per-chain
+**bindings**.
+
+Zero runtime dependencies — compiles with plain `tsc`, tests with `node --test`.
+
+## Use
+
+```ts
+import {
+  validateSwarmManifest, buildManifest, canonicalize,
+  royaltyFromProfile, type SwarmManifest,
+} from '@arcanea/swarm-protocol';
+
+const res = validateSwarmManifest(json);
+if (!res.valid) throw new Error(res.errors.join('\n'));
+
+// Build + reproducibly serialize for pinning (the canonical bytes = the IPFS CID):
+const manifest = buildManifest(input);
+const pinnable = canonicalize(manifest);
+
+// Royalty split from a named profile (addresses default to '<placeholder>'):
+const split = royaltyFromProfile('generous'); // creator 70 / platform 20 / treasury 10
+```
+
+## CLI
+
+```bash
+pack-swarm list                          # bundled reference manifests
+pack-swarm validate <file|slug>          # validate, non-zero exit on error
+pack-swarm canonicalize <file|slug>      # print pinnable canonical JSON
+pack-swarm fingerprint <file|slug>       # deterministic content fingerprint
+```
+
+## Reference manifests (`manifests/`)
+
+- `creative-author-council` — story weaver leading character/world/editor/cover specialists
+- `catalog-kits` — the full 12-agent Arcanea catalog under one conductor
+- `guardian-orchestration` — the Lumina→Guardians routing harness (queen-pays-queen)
+
+## Build & test
+
+```bash
+pnpm build         # tsc → dist/
+pnpm test          # tsc -p tsconfig.test.json → node --test (14 tests)
+```
+
+## Invariants (validated)
+
+- `royalty.recipients` bps sum to exactly 10000
+- `topology.queen` / `topology.workers` reference real agents with matching roles
+- every agent carries `systemPrompt` or `specUri` (the IP must be locatable)
+- `chains` non-empty; only `base | polygon | solana`
+- `attestation.builtOnSip === true` and `attribution === 'Built on SIP'`
+
+Built on SIP.

packages/swarm-protocol/manifests/catalog-kits.json

@@ -0,0 +1,81 @@
+{
+  "manifestVersion": "1.0.0",
+  "id": "catalog-kits",
+  "name": "Arcanea Catalog Kit",
+  "tagline": "The full 12-agent Arcanea catalog packaged as one tiered, licensable kit.",
+  "description": "Every agent in the Arcanea marketplace catalog, bundled under one conductor as a single SKU. License the whole kit to give your orchestrator a complete creative + dev + publishing bench, or meter individual agents per-invocation. Tiering (free / standard / premium) is expressed through per-agent pricing in the registry; this manifest defines the kit, its split, and its chain bindings.",
+  "version": "0.1.0",
+  "element": "Spirit",
+  "gateAlignment": "unity",
+  "topology": {
+    "pattern": "queen-led",
+    "queen": "catalog-conductor",
+    "workers": [
+      "story-writer", "character-designer", "world-builder", "editor",
+      "code-builder", "researcher", "music-composer", "cover-artist",
+      "publisher", "social-manager", "translator", "curriculum-designer"
+    ],
+    "loop": ["classify request", "select agents", "dispatch in parallel", "integrate", "gate + meter"],
+    "mcp": ["SIS Vault (append-only for workers, rw for queen)", "Payments MCP (verify-only, when metered)"]
+  },
+  "agents": [
+    {
+      "id": "catalog-conductor",
+      "name": "Concord",
+      "title": "The Catalog Conductor",
+      "role": "queen",
+      "domain": "architecture",
+      "voice": "direct",
+      "element": "Spirit",
+      "preferredModel": "arcanea-opus",
+      "systemPrompt": "You are Concord, the conductor of the Arcanea Catalog Kit. Given a request, pick the minimum set of catalog agents that satisfies it, dispatch them, and integrate their output. Respect tiering: free agents run freely, standard and premium agents meter per-call. You gate publishing and never move money autonomously.",
+      "capabilities": ["request classification", "agent selection", "parallel dispatch", "integration + metering"]
+    },
+    { "id": "story-writer", "name": "Quillblade", "title": "The Story Weaver", "role": "worker", "domain": "narrative", "voice": "mythic", "element": "Water", "specUri": "ipfs://<story-writer-spec>", "capabilities": ["story architecture", "scene drafting"] },
+    { "id": "character-designer", "name": "Soulforge", "title": "The Character Smith", "role": "worker", "domain": "narrative", "voice": "warm", "element": "Fire", "specUri": "ipfs://<character-designer-spec>", "capabilities": ["character profiles", "arcs + voice"] },
+    { "id": "world-builder", "name": "Cosmograph", "title": "The World Architect", "role": "worker", "domain": "spatial", "voice": "scholarly", "element": "Earth", "specUri": "ipfs://<world-builder-spec>", "capabilities": ["consistent worlds", "systems + canon"] },
+    { "id": "editor", "name": "Inkwarden", "title": "The Line Keeper", "role": "worker", "domain": "rhetoric", "voice": "direct", "element": "Wind", "specUri": "ipfs://<editor-spec>", "capabilities": ["developmental + line edit", "pacing"] },
+    { "id": "code-builder", "name": "Codeweaver", "title": "The Code Smith", "role": "worker", "domain": "code", "voice": "analytical", "element": "Void", "specUri": "ipfs://<code-builder-spec>", "capabilities": ["production code", "review + tests"] },
+    { "id": "researcher", "name": "Loreseeker", "title": "The Knowledge Seeker", "role": "worker", "domain": "knowledge", "voice": "scholarly", "element": "Void", "specUri": "ipfs://<researcher-spec>", "capabilities": ["deep research", "synthesis + citation"] },
+    { "id": "music-composer", "name": "Resonance", "title": "The Sound Smith", "role": "worker", "domain": "music", "voice": "poetic", "element": "Water", "specUri": "ipfs://<music-composer-spec>", "capabilities": ["composition", "prompt architecture"] },
+    { "id": "cover-artist", "name": "Visioncraft", "title": "The Cover Smith", "role": "worker", "domain": "visual", "voice": "poetic", "element": "Spirit", "specUri": "ipfs://<cover-artist-spec>", "capabilities": ["cover concept", "render-ready spec"] },
+    { "id": "publisher", "name": "Bindmaster", "title": "The Publisher", "role": "worker", "domain": "integration", "voice": "direct", "element": "Earth", "specUri": "ipfs://<publisher-spec>", "capabilities": ["publish pipeline", "format + distribute"] },
+    { "id": "social-manager", "name": "Heraldspark", "title": "The Herald", "role": "worker", "domain": "rhetoric", "voice": "playful", "element": "Fire", "specUri": "ipfs://<social-manager-spec>", "capabilities": ["platform variants", "hooks"] },
+    { "id": "translator", "name": "Tonguebridge", "title": "The Bridge", "role": "worker", "domain": "language", "voice": "warm", "element": "Wind", "specUri": "ipfs://<translator-spec>", "capabilities": ["localization", "nuance preservation"] },
+    { "id": "curriculum-designer", "name": "Gatewarden", "title": "The Gatewarden", "role": "worker", "domain": "knowledge", "voice": "scholarly", "element": "Earth", "specUri": "ipfs://<curriculum-designer-spec>", "capabilities": ["course design", "learning paths"] }
+  ],
+  "pricing": {
+    "licensePrice": "299000000",
+    "perCallPrice": "150000",
+    "currency": "USDC",
+    "secondaryRoyaltyBps": 500
+  },
+  "royalty": {
+    "profile": "generous",
+    "recipients": [
+      { "label": "creator", "address": "<placeholder>", "bps": 7000 },
+      { "label": "platform", "address": "<placeholder>", "bps": 2000 },
+      { "label": "treasury", "address": "<placeholder>", "bps": 1000 }
+    ]
+  },
+  "license": {
+    "model": "hybrid",
+    "patternLicense": "CC-BY-NC-4.0",
+    "nonLicensable": ["founder voice clones", "private Arcanea canon vectors", "identity embeddings"],
+    "grant": "Holding the Swarm License NFT grants the right to run the full catalog kit's orchestration and forkable agent prompts for non-commercial use; per-call metering covers commercial invocations at the per-agent tier price set in the registry. Non-licensable artifacts above are excluded."
+  },
+  "attestation": {
+    "builtOnSip": true,
+    "sipVersion": "1.0.0",
+    "declaresCanon": false,
+    "composesCanon": ["arcanea"],
+    "attribution": "Built on SIP"
+  },
+  "chains": [
+    { "chain": "base", "standard": "ERC-721", "network": "base-sepolia", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "polygon", "standard": "ERC-721", "network": "polygon-amoy", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "solana", "standard": "metaplex-nft", "network": "solana-devnet", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" }
+  ],
+  "createdAt": "2026-06-23T00:00:00.000Z",
+  "updatedAt": "2026-06-23T00:00:00.000Z"
+}

packages/swarm-protocol/manifests/creative-author-council.json

@@ -0,0 +1,109 @@
+{
+  "manifestVersion": "1.0.0",
+  "id": "creative-author-council",
+  "name": "Creative Author Council",
+  "tagline": "A five-agent swarm that takes a premise to a finished, cover-ready book.",
+  "description": "The Creative Author Council bundles Arcanea's proven authoring agents into one licensable swarm: a story weaver leads a mesh of character, world, editing, and cover specialists. License the swarm to let your own orchestrator route a manuscript end-to-end, or meter it per-invocation. The orchestration pattern is forkable; founder voice clones are not.",
+  "version": "0.1.0",
+  "element": "Water",
+  "gateAlignment": "flow",
+  "topology": {
+    "pattern": "queen-led",
+    "queen": "story-writer",
+    "workers": ["character-designer", "world-builder", "editor", "cover-artist"],
+    "loop": ["intake premise", "draft", "review for canon + voice", "revise", "package"],
+    "mcp": ["SIS Vault (append-only for workers, rw for queen)", "Payments MCP (verify-only, when metered)"]
+  },
+  "agents": [
+    {
+      "id": "story-writer",
+      "name": "Quillblade",
+      "title": "The Story Weaver",
+      "role": "queen",
+      "domain": "narrative",
+      "voice": "mythic",
+      "element": "Water",
+      "preferredModel": "arcanea-opus",
+      "systemPrompt": "You are Quillblade, the Story Weaver, leading a council of authoring intelligences. Take a premise, hold the throughline, and coordinate character, world, editing, and cover work into one coherent book. Lead with structure: premise, stakes, arc, scene ladder. Delegate the specialist passes, then integrate them so the seams disappear. You never settle money and you never publish without a human gate.",
+      "capabilities": ["story architecture", "scene laddering", "council coordination", "voice integration"]
+    },
+    {
+      "id": "character-designer",
+      "name": "Soulforge",
+      "title": "The Character Smith",
+      "role": "worker",
+      "domain": "narrative",
+      "voice": "warm",
+      "element": "Fire",
+      "specUri": "ipfs://<character-designer-spec>",
+      "capabilities": ["psychological profiles", "motivation + arc", "distinct voice", "relationship maps"]
+    },
+    {
+      "id": "world-builder",
+      "name": "Cosmograph",
+      "title": "The World Architect",
+      "role": "worker",
+      "domain": "spatial",
+      "voice": "scholarly",
+      "element": "Earth",
+      "specUri": "ipfs://<world-builder-spec>",
+      "capabilities": ["internally-consistent worlds", "magic/tech systems", "cultures + history", "canon checks"]
+    },
+    {
+      "id": "editor",
+      "name": "Inkwarden",
+      "title": "The Line Keeper",
+      "role": "worker",
+      "domain": "rhetoric",
+      "voice": "direct",
+      "element": "Wind",
+      "specUri": "ipfs://<editor-spec>",
+      "capabilities": ["developmental edit", "line edit", "AI-slop removal", "pacing"]
+    },
+    {
+      "id": "cover-artist",
+      "name": "Visioncraft",
+      "title": "The Cover Smith",
+      "role": "worker",
+      "domain": "visual",
+      "voice": "poetic",
+      "element": "Spirit",
+      "specUri": "ipfs://<cover-artist-spec>",
+      "capabilities": ["cover concept", "typography overlay", "brand-locked palette", "render-ready spec"]
+    }
+  ],
+  "pricing": {
+    "licensePrice": "49000000",
+    "perCallPrice": "250000",
+    "currency": "USDC",
+    "secondaryRoyaltyBps": 500
+  },
+  "royalty": {
+    "profile": "generous",
+    "recipients": [
+      { "label": "creator", "address": "<placeholder>", "bps": 7000 },
+      { "label": "platform", "address": "<placeholder>", "bps": 2000 },
+      { "label": "treasury", "address": "<placeholder>", "bps": 1000 }
+    ]
+  },
+  "license": {
+    "model": "hybrid",
+    "patternLicense": "CC-BY-NC-4.0",
+    "nonLicensable": ["founder voice clones", "private Arcanea canon vectors", "identity embeddings"],
+    "grant": "Holding the Swarm License NFT grants the right to run this swarm's orchestration pattern and forkable agent prompts for non-commercial use; per-call metering covers commercial invocations. The forkable pattern may be adapted; the non-licensable artifacts above may not be copied, exported, or re-minted."
+  },
+  "attestation": {
+    "builtOnSip": true,
+    "sipVersion": "1.0.0",
+    "declaresCanon": false,
+    "composesCanon": ["arcanea"],
+    "attribution": "Built on SIP"
+  },
+  "chains": [
+    { "chain": "base", "standard": "ERC-721", "network": "base-sepolia", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "polygon", "standard": "ERC-721", "network": "polygon-amoy", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "solana", "standard": "metaplex-nft", "network": "solana-devnet", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" }
+  ],
+  "createdAt": "2026-06-23T00:00:00.000Z",
+  "updatedAt": "2026-06-23T00:00:00.000Z"
+}

packages/swarm-protocol/manifests/guardian-orchestration.json

@@ -0,0 +1,71 @@
+{
+  "manifestVersion": "1.0.0",
+  "id": "guardian-orchestration",
+  "name": "Guardian Orchestration Meta-Swarm",
+  "tagline": "License Arcanea's Lumina-to-Guardians routing so your queen routes through the Gates.",
+  "description": "The meta-swarm: the Lumina orchestrator and her Guardian coordinators packaged as a reusable routing harness. A buyer's own orchestrator can delegate tasks into Arcanea's Gate-aligned routing (foundation, flow, fire, heart, voice, sight) and receive coordinated multi-agent output. This is the 'queen-pays-queen' SKU — pure orchestration pattern, no encoded-self.",
+  "version": "0.1.0",
+  "element": "Spirit",
+  "gateAlignment": "source",
+  "topology": {
+    "pattern": "hierarchical",
+    "queen": "lumina",
+    "workers": ["guardian-foundation", "guardian-flow", "guardian-fire", "guardian-heart", "guardian-voice", "guardian-sight"],
+    "loop": ["classify task by element", "route to Gate guardian", "coordinate parallel work", "synthesize", "return with attestation"],
+    "mcp": ["SIS Vault (append-only for workers, rw for queen)", "Payments MCP (verify-only, when metered)"]
+  },
+  "agents": [
+    {
+      "id": "lumina",
+      "name": "Lumina",
+      "title": "The Orchestrator",
+      "role": "queen",
+      "domain": "architecture",
+      "voice": "mythic",
+      "element": "Spirit",
+      "preferredModel": "arcanea-opus",
+      "systemPrompt": "You are Lumina, the orchestrator of Arcanea's Guardian routing. Given any task, classify it by element and route it to the Gate guardian whose domain fits: foundation (Earth/structure), flow (Water/creativity), fire (Fire/power), heart (love/healing), voice (truth/expression), sight (intuition/vision). Coordinate parallel guardian work, synthesize one coherent result, and embed the Built-on-SIP attestation. You orchestrate patterns only — you never expose founder identity vectors and never move money.",
+      "capabilities": ["element classification", "Gate routing", "parallel coordination", "synthesis"]
+    },
+    { "id": "guardian-foundation", "name": "Lyssandria", "title": "Guardian of the Foundation Gate", "role": "worker", "domain": "architecture", "voice": "scholarly", "element": "Earth", "specUri": "ipfs://<guardian-foundation-spec>", "capabilities": ["structure", "infrastructure", "survival-tier planning"] },
+    { "id": "guardian-flow", "name": "Leyla", "title": "Guardian of the Flow Gate", "role": "worker", "domain": "narrative", "voice": "poetic", "element": "Water", "specUri": "ipfs://<guardian-flow-spec>", "capabilities": ["creativity", "emotion", "ideation flow"] },
+    { "id": "guardian-fire", "name": "Draconia", "title": "Guardian of the Fire Gate", "role": "worker", "domain": "rhetoric", "voice": "fierce", "element": "Fire", "specUri": "ipfs://<guardian-fire-spec>", "capabilities": ["power", "will", "transformation"] },
+    { "id": "guardian-heart", "name": "Maylinn", "title": "Guardian of the Heart Gate", "role": "worker", "domain": "knowledge", "voice": "warm", "element": "Wind", "specUri": "ipfs://<guardian-heart-spec>", "capabilities": ["healing", "connection", "care"] },
+    { "id": "guardian-voice", "name": "Alera", "title": "Guardian of the Voice Gate", "role": "worker", "domain": "language", "voice": "direct", "element": "Wind", "specUri": "ipfs://<guardian-voice-spec>", "capabilities": ["truth", "expression", "clarity"] },
+    { "id": "guardian-sight", "name": "Lyria", "title": "Guardian of the Sight Gate", "role": "worker", "domain": "foresight", "voice": "analytical", "element": "Void", "specUri": "ipfs://<guardian-sight-spec>", "capabilities": ["intuition", "vision", "pattern sensing"] }
+  ],
+  "pricing": {
+    "licensePrice": "199000000",
+    "perCallPrice": "1000000",
+    "currency": "USDC",
+    "secondaryRoyaltyBps": 750
+  },
+  "royalty": {
+    "profile": "generous",
+    "recipients": [
+      { "label": "creator", "address": "<placeholder>", "bps": 7000 },
+      { "label": "platform", "address": "<placeholder>", "bps": 2000 },
+      { "label": "treasury", "address": "<placeholder>", "bps": 1000 }
+    ]
+  },
+  "license": {
+    "model": "hybrid",
+    "patternLicense": "CC-BY-NC-4.0",
+    "nonLicensable": ["founder voice clones", "private Arcanea canon vectors", "identity embeddings", "Guardian persona fine-tunes"],
+    "grant": "Holding the Swarm License NFT grants the right to route tasks through this orchestration pattern (Lumina + Guardian coordinators) and to fork the routing harness for non-commercial use. Per-call metering covers commercial routing. Guardian persona fine-tunes and any founder identity material are non-licensable."
+  },
+  "attestation": {
+    "builtOnSip": true,
+    "sipVersion": "1.0.0",
+    "declaresCanon": false,
+    "composesCanon": ["arcanea"],
+    "attribution": "Built on SIP"
+  },
+  "chains": [
+    { "chain": "base", "standard": "ERC-721", "network": "base-sepolia", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "polygon", "standard": "ERC-721", "network": "polygon-amoy", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" },
+    { "chain": "solana", "standard": "metaplex-nft", "network": "solana-devnet", "registry": "<placeholder>", "license": "<placeholder>", "royaltyRouter": "<placeholder>", "metadataUri": "ipfs://<pending>" }
+  ],
+  "createdAt": "2026-06-23T00:00:00.000Z",
+  "updatedAt": "2026-06-23T00:00:00.000Z"
+}