Skip to main content

​
FORGERY: Gamified Network Research, Development & Testing Subsystem

Document ID: FORGERY-SPEC-001
Version: 1.0
Date: December 16, 2025
Status: Technical & Business Requirements Specification
Audience: Product Engineering, DevOps, Business Leadership

​
Executive Summary

Forgery is Sparki.tools’ gamified subsystem for network research, development, and testing. It transforms tedious CI/CD testing, domain model validation, and network protocol research into engaging, rewarding experiences using game mechanics, achievements, leaderboards, and narrative progression.

​
Core Value Proposition

  • For Developers: Turn boring test suites into epic quests; unlock achievements; compete on leaderboards
  • For Teams: Collaborative testing sprints; guild-based tournaments; shared progress
  • For Enterprises: Compliance testing gamification; risk scoring; automated domain model validation
  • For Sparki: Tiered monetization with 3x revenue lift from gamified engagement

​
1. SYSTEM OVERVIEW

​
1.1 Core Concept: “Forging Domain Models”

Forgery reimagines CI/CD testing as smithing—developers “forge” domain models through increasingly difficult test suites, network simulations, and validation challenges. Metaphor Breakdown:
  • Ore = raw domain models (from Manuscript)
  • Forge = test harness + validation environment
  • Anvil = CI/CD pipeline infrastructure
  • Smith = developer executing the forging process
  • Ingot = validated, production-ready domain model
  • Legendary Weapon = enterprise-grade, battle-tested system

​
1.2 Command Structure

# Core commands
sparki forge                      # Enter Forgery interactive mode
sparki forge scan                 # Detect forgeable domain models
sparki forge quest <domain>       # Start a testing quest for a domain
sparki forge smith <artifact>     # Manually test an artifact
sparki forge inventory            # Show earned achievements + artifacts
sparki forge leaderboard          # Show global/team leaderboards
sparki forge tournament <name>    # Create or join a testing tournament
sparki forge ritual <name>        # Execute automated testing ritual

# Advanced
sparki forge transmute            # Evolve a tested domain into next tier
sparki forge crucible             # Advanced network stress testing
sparki forge guild <action>       # Manage or create guilds
sparki forge lore                 # View system lore and domain history

​
1.3 Subsystem Architecture

Forgery Subsystem
├── Core Engine
│   ├── Quest System (test generation + orchestration)
│   ├── Smith Engine (artifact testing harness)
│   ├── Ritual Engine (automated test workflows)
│   └── Crucible (network stress testing)
├── Gamification Layer
│   ├── XP & Leveling
│   ├── Achievement System
│   ├── Leaderboards (local, team, global)
│   └── Guild System
├── Domain Integration
│   ├── Manuscript Auto-detection
│   ├── Proto Validation
│   └── Domain Sync (via Scribe)
├── Monetization Layer
│   ├── Polar Payment Integration
│   ├── Tier Gate System
│   ├── Feature Flags
│   └── Usage Metering
└── Visualization
    ├── Bubbletea TUI Dashboard
    ├── ASCII Art Smithy Representation
    └── Real-time Progress Tracking

​
2. CORE MECHANICS

​
2.1 The Forging Quest System

​
Quest Types

1. Smoke Tests (Tier 1 - Apprentice)
  • Difficulty: Easy | Duration: 2-5 min | XP: 50-100
  • Validate basic proto compilation
  • Check domain model exports
  • Verify import paths
  • Example: “Forge the User Domain Proto” → compile + quick import test
2. Integration Tests (Tier 2 - Journeyman)
  • Difficulty: Medium | Duration: 10-30 min | XP: 250-500
  • Cross-domain model validation
  • Service-to-service communication
  • Event schema compatibility
  • Example: “Test Document-Collaboration Handshake” → simulate document creation + collaboration events
3. Network Trials (Tier 3 - Master)
  • Difficulty: Hard | Duration: 30min-2h | XP: 1000-2500
  • Simulate real-world network conditions
  • Latency, packet loss, timeout scenarios
  • Concurrent load testing
  • Example: “Survive the Storm” → 1000 concurrent events + 30% packet loss
4. Transmutation Rituals (Tier 4 - Legend)
  • Difficulty: Extreme | Duration: Variable | XP: 5000+
  • Multi-service orchestration tests
  • Full CI/CD pipeline validation
  • Enterprise compliance checking
  • Example: “The Grand Alchemy” → deploy, test, validate across entire ecosystem

​
Quest Attributes

quest:
    id: 'quest_user_smoke_v1'
    name: 'Forge the User Domain'
    description: 'Validate the User domain model and its basic operations'
    tier: 1
    difficulty: easy
    estimated_duration: '5m'

    # Gamification
    xp_reward: 100
    achievement_unlocks:
        - 'first_forge'
        - 'user_domain_master'

    # Testing specs
    tests:
        - type: 'proto_compile'
          target: 'user/v1.proto'
          assert: 'success'
        - type: 'import_test'
          imports: ['github.com/materi/domain/proto/user']
          assert: 'no_errors'
        - type: 'schema_validation'
          schemas:
              - 'UserCreated'
              - 'UserUpdated'
          assert: 'all_fields_present'

    # Rewards
    rewards:
        - type: 'artifact'
          name: 'User Domain Ingot'
          rarity: 'common'
        - type: 'badge'
          name: 'Proto Apprentice'
          color: 'bronze'

​
2.2 The Smith Engine

The Smith Engine is the core test harness that executes quests and generates real-time feedback. Phases:
  1. Preparation - Load quest, set up test environment
  2. Ignition - Start the forge (compile domains, prep fixtures)
  3. Tempering - Run tests with real-time monitoring
  4. Quenching - Cool down, generate results
  5. Inspection - Grade artifacts, unlock rewards
Real-time Feedback Loop: 
Quest Start
  ↓
[Ignition - 10% progress]
  ├─ Compiling domain proto
  ├─ Validating schemas
  └─ Preparing test fixtures
  ↓
[Tempering - 40% progress]
  ├─ Running test 1/5 ✓ (2.3ms)
  ├─ Running test 2/5 ✓ (1.8ms)
  ├─ Running test 3/5 ✗ (ERROR)
  ├─ Running test 4/5 (in progress...)
  └─ Running test 5/5 (pending)
  ↓
[Inspection - 100%]
  ├─ ✓ 4/5 tests passed
  ├─ +250 XP earned
  ├─ 🏅 Achievement unlocked: "Test Master"
  └─ Artifact: "User Domain Ingot (Tier 2)" added to inventory

​
2.3 Ritual System (Automated Testing)

Rituals are templated, reusable testing sequences for common scenarios. 
ritual:
    id: 'ritual_domain_sync'
    name: 'The Synchronization Ritual'
    description: 'Validate all domain models are in sync with manuscript'

    steps:
        - action: 'scan_domains'
          description: 'Scan for all .proto files'

        - action: 'compile_all'
          description: 'Compile all domains'
          timeout: 300s

        - action: 'validate_exports'
          description: 'Ensure all types are properly exported'

        - action: 'run_integration_tests'
          description: 'Test cross-domain imports'

        - action: 'verify_checksums'
          description: 'Verify proto checksums match'

    # Recurring execution
    schedule:
        frequency: 'daily'
        time: '02:00 UTC'
        on_failure: 'notify_team'

    # Rewards for completion
    rewards:
        xp: 500
        achievements:
            - 'ritual_master'
            - 'consistency_champion'

​
2.4 Crucible: Network Stress Testing

The Crucible is Forgery’s advanced network simulation engine for testing under adverse conditions. 
crucible:
  id: "crucible_storm"
  name: "Survive the Storm"
  description: "Test system resilience under extreme network conditions"

  # Load configuration
  load:
    concurrent_events: 5000
    event_rate: "10,000 events/sec"
    duration: 3600s  # 1 hour

  # Network conditions
  conditions:
    - phase: "clear_skies" (0-10 min)
      latency: "5-10ms"
      packet_loss: 0%

    - phase: "approaching_storm" (10-20 min)
      latency: "50-100ms"
      packet_loss: "5-10%"

    - phase: "full_storm" (20-50 min)
      latency: "500ms-2s"
      packet_loss: "30-50%"
      timeout_rate: "20%"

    - phase: "calm_after_storm" (50-60 min)
      latency: "10-50ms"
      packet_loss: "1%"

  # Success criteria
  assertions:
    - "success_rate >= 95%"
    - "no_data_loss"
    - "eventual_consistency_within_5s"
    - "graceful_degradation"

  # Rewards
  rewards:
    xp: 5000
    artifact: "Storm-Tested Ingot (Legendary)"
    achievements:
      - "storm_survivor"
      - "master_of_resilience"

​
3. DOMAIN MODEL INTEGRATION

​
3.1 Manuscript Auto-Detection

Forgery automatically scans Manuscript (.msx) for forgeable domains. 
// Pseudocode: Domain Scanner
func ScanForgeableDomains(manuscriptPath string) []Domain {
  domains := []Domain{}

  // Scan .msx/domains/*/v1.proto
  for _, protoFile := range findProtoFiles(manuscriptPath) {
    domain := Domain{
      Name: parsePackageName(protoFile),
      ProtoPath: protoFile,
      Events: parseMessages(protoFile),
      Complexity: estimateComplexity(protoFile),
      QuestTier: calculateTier(domain),
    }
    domains = append(domains, domain)
  }

  return domains
}

// Auto-generated quests for each domain
func GenerateQuestsForDomain(d Domain) []Quest {
  quests := []Quest{
    SmokeTestQuest(d),           // Tier 1
    IntegrationTestQuest(d),     // Tier 2
    NetworkTrialQuest(d),         // Tier 3
    TransmutationRitual(d),       // Tier 4
  }
  return quests
}

​
3.2 Proto Validation Pipeline

Manuscript (.msx)
  ↓
[Domain Scanner]
  ├─ user/v1.proto
  ├─ document/v1.proto
  ├─ collaboration/v1.proto
  └─ ... (8 domains total)
  ↓
[Forgery Orchestrator]
  ├─ Generate Smoke Quests (Tier 1)
  ├─ Generate Integration Quests (Tier 2)
  ├─ Generate Network Quests (Tier 3)
  └─ Generate Transmutation Rituals (Tier 4)
  ↓
[Developer Execution]
  └─ sparki forge quest user

​
3.3 Scribe Integration (Domain Sync)

Forgery integrates with Scribe CLI for automatic domain synchronization: 
# Forgery detects domain changes via Scribe
sparki forge ritual sync-with-manuscript
  └─ Calls: scribe sync msx
  └─ Detects changes in proto files
  └─ Re-generates quests automatically
  └─ Notifies developers of new challenges

​
4. GAMIFICATION MECHANICS

[Detailed in FORGERY-GAMIFICATION-001]

​
5. MONETIZATION & TIER GATING

[Detailed in FORGERY-POLAR-MONETIZATION-001]

​
6. IMPLEMENTATION ROADMAP

​
Phase 1: Foundation (Weeks 1-4)

  • Core quest system infrastructure
  • Smith engine (basic test harness)
  • XP & achievement system
  • Bubbletea TUI dashboard
  • Manuscript integration

​
Phase 2: Gamification (Weeks 5-8)

  • Leaderboards (local/team/global)
  • Guild system
  • Tournament framework
  • Advanced achievements
  • Lore system

​
Phase 3: Monetization (Weeks 9-12)

  • Polar payment integration
  • Tier gating system
  • Usage metering
  • Feature flags
  • Billing dashboard

​
Phase 4: Advanced Features (Weeks 13+)

  • Crucible (network stress testing)
  • AI-powered quest suggestions
  • Mobile companion app
  • Marketplace for artifacts
  • Guild tournaments

​
7. SUCCESS METRICS

MetricTargetTimeline
Quests Completed/Day (Community)1,000+Month 2
Team Tier Conversion15%Month 3
Pro Tier Conversion5%Month 4
Monthly Recurring Revenue (Forgery)$50K+Month 6
Guild Participation30% of active usersMonth 5
Repeat Quest Rate60%+Month 3

​
8. TECHNICAL DEPENDENCIES

  • Sparki Core - Command routing, TUI framework
  • Manuscript - Proto file access, domain models
  • Scribe CLI - Domain sync, proto compilation
  • Polar - Payment processing
  • Bubbletea - Terminal UI
  • PostgreSQL (Team+) - Leaderboards, achievements, persistence

​
9. NEXT STEPS

  1. Review & Approval - Stakeholder sign-off on spec
  2. Gamification Design - Finalize achievement system (FORGERY-GAMIFICATION-001)
  3. Monetization Strategy - Validate Polar integration (FORGERY-POLAR-MONETIZATION-001)
  4. Architecture Design - Detailed technical design (FORGERY-ARCHITECTURE-001)
  5. Sprint Planning - Break into 2-week sprints
Document Status: Awaiting Gamification & Monetization Specification Reviews