thevoidforge 21.0.11 → 21.0.12

package/dist/docs/patterns/game-loop.ts

@@ -0,0 +1,113 @@
+/**
+ * Pattern: Fixed-Timestep Game Loop
+ *
+ * Key principles:
+ * - Fixed timestep for physics/logic (deterministic, reproducible)
+ * - Variable rendering (render as fast as possible, interpolate between states)
+ * - Frame budget tracking (detect when logic takes too long)
+ * - Pause/resume without state corruption
+ * - requestAnimationFrame for browser, custom loop for Node/native
+ *
+ * Agents: Spike-GameDev (architecture), L-Profiler (frame budget), Gimli (performance)
+ *
+ * Engine adaptations:
+ *   Phaser: this.time.addEvent() for fixed timestep, scene.update() for variable
+ *   Godot: _physics_process(delta) for fixed, _process(delta) for variable
+ *   Unity: FixedUpdate() for fixed, Update() for variable
+ *   Three.js: This file (manual loop with clock.getDelta())
+ */
+
+// --- Configuration ---
+const FIXED_TIMESTEP = 1 / 60  // 60 Hz physics/logic
+const MAX_FRAME_TIME = 0.25     // Cap to prevent spiral of death
+const FRAME_BUDGET_MS = 16.67   // Target: 60 FPS
+
+// --- Game State ---
+interface GameState {
+  paused: boolean
+  time: number          // Total elapsed game time (paused time excluded)
+  frameCount: number
+  entities: Entity[]
+}
+
+interface Entity {
+  x: number
+  y: number
+  prevX: number         // Previous position for interpolation
+  prevY: number
+  vx: number
+  vy: number
+  update(dt: number): void
+}
+
+// --- The Loop ---
+
+let accumulator = 0
+let lastTime = 0
+let state: GameState = { paused: false, time: 0, frameCount: 0, entities: [] }
+
+function gameLoop(currentTime: number): void {
+  if (state.paused) {
+    lastTime = currentTime   // Reset so unpause doesn't cause a time jump
+    requestAnimationFrame(gameLoop)
+    return
+  }
+
+  let frameTime = (currentTime - lastTime) / 1000  // Convert ms to seconds
+  lastTime = currentTime
+
+  // Cap frame time to prevent spiral of death (e.g., tab was backgrounded)
+  if (frameTime > MAX_FRAME_TIME) frameTime = MAX_FRAME_TIME
+
+  accumulator += frameTime
+
+  // --- Fixed timestep: update logic/physics ---
+  while (accumulator >= FIXED_TIMESTEP) {
+    // Save previous positions for interpolation
+    for (const entity of state.entities) {
+      entity.prevX = entity.x
+      entity.prevY = entity.y
+    }
+
+    // Update at fixed rate
+    for (const entity of state.entities) {
+      entity.update(FIXED_TIMESTEP)
+    }
+
+    state.time += FIXED_TIMESTEP
+    accumulator -= FIXED_TIMESTEP
+  }
+
+  // --- Variable rendering: interpolate between states ---
+  const alpha = accumulator / FIXED_TIMESTEP  // 0.0 to 1.0
+
+  for (const entity of state.entities) {
+    const renderX = entity.prevX + (entity.x - entity.prevX) * alpha
+    const renderY = entity.prevY + (entity.y - entity.prevY) * alpha
+    // render(entity, renderX, renderY)
+  }
+
+  // --- Frame budget tracking ---
+  const frameEndTime = performance.now()
+  const frameDuration = frameEndTime - currentTime
+  if (frameDuration > FRAME_BUDGET_MS) {
+    console.warn(`Frame ${state.frameCount} exceeded budget: ${frameDuration.toFixed(1)}ms`)
+    // L-Profiler flags: investigate which entities/systems took too long
+  }
+
+  state.frameCount++
+  requestAnimationFrame(gameLoop)
+}
+
+// --- Pause/Resume ---
+function pause(): void { state.paused = true }
+function resume(): void { state.paused = false }
+
+// --- Start ---
+function startGame(): void {
+  lastTime = performance.now()
+  requestAnimationFrame(gameLoop)
+}
+
+export { gameLoop, startGame, pause, resume, FIXED_TIMESTEP }
+export type { GameState, Entity }

package/dist/docs/patterns/game-state.ts

@@ -0,0 +1,143 @@
+/**
+ * Pattern: Hierarchical Game State Machine
+ *
+ * Key principles:
+ * - Every game has states: Menu → Playing → Paused → GameOver (minimum)
+ * - Transitions have enter/exit hooks (load assets on enter, clean up on exit)
+ * - States can have sub-states (Playing → Cutscene, Playing → Dialog)
+ * - History: can return to previous state (Pause → resume to Playing, not Menu)
+ * - Serializable: save/load works by serializing the state stack
+ *
+ * Agents: Spike-GameDev (architecture), Éowyn-GameFeel (transitions), Constantine (state bugs)
+ *
+ * Engine adaptations:
+ *   Phaser: this.scene.start('GameOver'), this.scene.pause('Playing')
+ *   Godot: SceneTree.change_scene(), custom state machine node
+ *   Unity: SceneManager.LoadScene(), or custom FSM MonoBehaviour
+ */
+
+// --- State Definition ---
+interface GameStateConfig {
+  name: string
+  enter?: () => void | Promise<void>     // Called when entering this state
+  exit?: () => void | Promise<void>      // Called when leaving this state
+  update?: (dt: number) => void          // Called every frame while active
+  handleInput?: (input: GameInput) => void
+}
+
+interface GameInput {
+  type: 'keydown' | 'keyup' | 'click' | 'gamepad'
+  key?: string
+  button?: number
+  x?: number
+  y?: number
+}
+
+// --- State Machine ---
+class StateMachine {
+  private states: Map<string, GameStateConfig> = new Map()
+  private stack: string[] = []             // State stack for history
+  private current: GameStateConfig | null = null
+
+  register(config: GameStateConfig): void {
+    this.states.set(config.name, config)
+  }
+
+  get currentState(): string | null {
+    return this.current?.name ?? null
+  }
+
+  async transition(stateName: string): Promise<void> {
+    const next = this.states.get(stateName)
+    if (!next) throw new Error(`Unknown state: ${stateName}`)
+
+    // Exit current state
+    if (this.current?.exit) await this.current.exit()
+
+    // Push to history
+    if (this.current) this.stack.push(this.current.name)
+
+    // Enter new state
+    this.current = next
+    if (this.current.enter) await this.current.enter()
+  }
+
+  async back(): Promise<void> {
+    if (this.stack.length === 0) return
+
+    const previousName = this.stack.pop()!
+    const previous = this.states.get(previousName)
+    if (!previous) return
+
+    if (this.current?.exit) await this.current.exit()
+    this.current = previous
+    if (this.current.enter) await this.current.enter()
+  }
+
+  update(dt: number): void {
+    if (this.current?.update) this.current.update(dt)
+  }
+
+  handleInput(input: GameInput): void {
+    if (this.current?.handleInput) this.current.handleInput(input)
+  }
+
+  // Serialize for save/load
+  serialize(): { current: string | null; stack: string[] } {
+    return { current: this.current?.name ?? null, stack: [...this.stack] }
+  }
+
+  async restore(saved: { current: string | null; stack: string[] }): Promise<void> {
+    this.stack = [...saved.stack]
+    if (saved.current) {
+      this.current = this.states.get(saved.current) ?? null
+      if (this.current?.enter) await this.current.enter()
+    }
+  }
+}
+
+// --- Usage Example ---
+/*
+const sm = new StateMachine()
+
+sm.register({
+  name: 'menu',
+  enter: () => showMainMenu(),
+  handleInput: (input) => {
+    if (input.key === 'Enter') sm.transition('playing')
+  }
+})
+
+sm.register({
+  name: 'playing',
+  enter: () => startLevel(),
+  exit: () => cleanupLevel(),
+  update: (dt) => updateGameplay(dt),
+  handleInput: (input) => {
+    if (input.key === 'Escape') sm.transition('paused')
+    if (playerDead) sm.transition('gameover')
+  }
+})
+
+sm.register({
+  name: 'paused',
+  enter: () => showPauseMenu(),
+  handleInput: (input) => {
+    if (input.key === 'Escape') sm.back()  // Resume playing, not go to menu
+  }
+})
+
+sm.register({
+  name: 'gameover',
+  enter: () => showGameOverScreen(),
+  handleInput: (input) => {
+    if (input.key === 'Enter') sm.transition('menu')
+  }
+})
+
+// Start the game
+await sm.transition('menu')
+*/
+
+export { StateMachine }
+export type { GameStateConfig, GameInput }

package/dist/docs/patterns/job-queue.ts

@@ -0,0 +1,225 @@
+/**
+ * Pattern: Background Job / Queue Worker
+ *
+ * Key principles:
+ * - Jobs are idempotent — running the same job twice produces the same result
+ * - Idempotency keys prevent duplicate processing
+ * - Retry with exponential backoff for transient failures
+ * - Dead letter queue for permanently failed jobs
+ * - Minimal payloads — pass IDs, fetch fresh data in the handler
+ * - Graceful shutdown — finish current job before stopping
+ *
+ * Agents: Thor (queue engineer), Barton (error handling), L (monitoring)
+ *
+ * Framework adaptations:
+ *   Next.js/Node: BullMQ + Redis, or Inngest for serverless
+ *   Django: Celery + Redis/RabbitMQ
+ *   Rails: Sidekiq + Redis, or ActiveJob
+ *   Express: BullMQ + Redis, or Agenda + MongoDB
+ *
+ * === Django + Celery Deep Dive ===
+ *
+ *   # app/tasks.py
+ *   from celery import shared_task
+ *   from .services import EmailService
+ *
+ *   @shared_task(bind=True, max_retries=3, default_retry_delay=60)
+ *   def send_welcome_email(self, user_id: int):
+ *       try:
+ *           EmailService.send_welcome(user_id)
+ *       except Exception as exc:
+ *           self.retry(exc=exc)
+ *
+ *   # Idempotency: use task_id or a dedupe key in the DB to prevent re-processing
+ *   # Dead letter: configure task_reject_on_worker_lost=True + dlx in broker
+ *   # Monitoring: Flower (celery monitor) or Sentry integration
+ *   # Beat scheduler: periodic tasks via django-celery-beat
+ *
+ * === FastAPI + ARQ Deep Dive ===
+ *
+ *   # app/tasks.py
+ *   from arq import create_pool
+ *   from arq.connections import RedisSettings
+ *
+ *   async def send_welcome_email(ctx, user_id: int):
+ *       await EmailService.send_welcome(user_id)
+ *
+ *   class WorkerSettings:
+ *       functions = [send_welcome_email]
+ *       redis_settings = RedisSettings()
+ *       max_tries = 3
+ *       retry_delay = 60
+ *
+ *   # ARQ is async-native (matches FastAPI). Alternative: Celery still works with FastAPI.
+ *   # Same principles: idempotency, retry with backoff, dead letter, monitoring.
+ */
+
+// --- Job definition (enqueue side) ---
+
+import { Queue } from 'bullmq'
+import { redis } from '@/lib/redis'
+
+// One queue per job domain (not one per job type)
+const emailQueue = new Queue('email', { connection: redis })
+
+// Enqueue with idempotency key to prevent duplicates
+export async function enqueueWelcomeEmail(userId: string) {
+  await emailQueue.add(
+    'welcome-email',
+    { userId },  // Minimal payload — just the ID
+    {
+      jobId: `welcome-email:${userId}`,  // Idempotency key
+      attempts: 3,
+      backoff: {
+        type: 'exponential',
+        delay: 1000,  // 1s, 2s, 4s
+      },
+      removeOnComplete: { age: 86400 },  // Clean up after 24h
+      removeOnFail: { age: 604800 },     // Keep failures for 7 days
+    }
+  )
+}
+
+// --- Job handler (worker side) ---
+
+import { Worker } from 'bullmq'
+import { db } from '@/lib/db'
+import { emailService } from '@/lib/services/email'
+
+const emailWorker = new Worker(
+  'email',
+  async (job) => {
+    const { userId } = job.data
+
+    // Fetch fresh data — don't trust stale payload
+    const user = await db.user.findUnique({ where: { id: userId } })
+
+    if (!user) {
+      // User was deleted between enqueue and processing — skip, don't retry
+      console.log(JSON.stringify({
+        event: 'job.skipped',
+        queue: 'email',
+        job: job.name,
+        jobId: job.id,
+        reason: 'user_not_found',
+        userId,
+      }))
+      return
+    }
+
+    // Idempotency check — has this already been sent?
+    const alreadySent = await db.emailLog.findFirst({
+      where: { userId, type: 'welcome', sentAt: { not: null } },
+    })
+
+    if (alreadySent) {
+      console.log(JSON.stringify({
+        event: 'job.skipped',
+        queue: 'email',
+        job: job.name,
+        jobId: job.id,
+        reason: 'already_sent',
+        userId,
+      }))
+      return
+    }
+
+    // Do the work
+    await emailService.sendWelcome(user)
+
+    // Record that it was sent (for idempotency on retry)
+    await db.emailLog.create({
+      data: { userId, type: 'welcome', sentAt: new Date() },
+    })
+
+    // Structured log for monitoring (L — observability)
+    console.log(JSON.stringify({
+      event: 'job.completed',
+      queue: 'email',
+      job: job.name,
+      jobId: job.id,
+      userId,
+      duration: Date.now() - job.timestamp,
+    }))
+  },
+  {
+    connection: redis,
+    concurrency: 5,           // Max parallel jobs
+    limiter: {
+      max: 10,
+      duration: 1000,         // Rate limit: 10 jobs/sec
+    },
+  }
+)
+
+// --- Error handling ---
+
+emailWorker.on('failed', (job, error) => {
+  console.error(JSON.stringify({
+    event: 'job.failed',
+    queue: 'email',
+    job: job?.name,
+    jobId: job?.id,
+    attempt: job?.attemptsMade,
+    maxAttempts: job?.opts.attempts,
+    error: error.message,
+    // If max attempts reached, this goes to the dead letter queue
+    deadLettered: job?.attemptsMade === job?.opts.attempts,
+  }))
+})
+
+// --- Graceful shutdown ---
+
+async function shutdown() {
+  console.log('Shutting down email worker...')
+  await emailWorker.close()  // Finish current job, stop accepting new ones
+  process.exit(0)
+}
+
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)
+
+// --- Django equivalent (Celery) ---
+/*
+# tasks/email.py
+from celery import shared_task
+from django.core.mail import send_mail
+from users.models import User, EmailLog
+
+@shared_task(
+    bind=True,
+    max_retries=3,
+    default_retry_delay=60,
+    acks_late=True,  # Acknowledge after completion, not before
+)
+def send_welcome_email(self, user_id: str):
+    try:
+        user = User.objects.get(id=user_id)
+    except User.DoesNotExist:
+        return  # User deleted — skip
+
+    if EmailLog.objects.filter(user=user, type='welcome').exists():
+        return  # Already sent — idempotent
+
+    send_mail(subject='Welcome', message='...', recipient_list=[user.email])
+    EmailLog.objects.create(user=user, type='welcome')
+*/
+
+// --- Rails equivalent (Sidekiq) ---
+/*
+# app/jobs/welcome_email_job.rb
+class WelcomeEmailJob
+  include Sidekiq::Job
+  sidekiq_options retry: 3, queue: 'email', unique: :until_executed
+
+  def perform(user_id)
+    user = User.find_by(id: user_id)
+    return unless user  # Deleted — skip
+
+    return if EmailLog.exists?(user: user, email_type: 'welcome')  # Idempotent
+
+    UserMailer.welcome(user).deliver_now
+    EmailLog.create!(user: user, email_type: 'welcome', sent_at: Time.current)
+  end
+end
+*/

package/dist/docs/patterns/kongo-integration.ts

@@ -0,0 +1,164 @@
+/**
+ * Pattern: Kongo Integration
+ * When to use: Integrating an external landing page engine with growth/campaign systems
+ * Covers: authenticated client, from-PRD page generation, growth signal, webhook handling
+ *
+ * This pattern demonstrates first-party API integration for a product the team owns.
+ * Unlike adapter patterns (ad-platform-adapter.ts), there's no abstraction layer —
+ * the client talks directly to the external API with typed request/response shapes.
+ *
+ * Architecture: ADR-036
+ *
+ * Framework adaptations:
+ * - Next.js: Webhook route at /api/webhooks/kongo
+ * - Express: Router mounted at /webhooks/kongo
+ * - Django/DRF: View at /api/webhooks/kongo/ with raw body parsing
+ * - FastAPI: POST endpoint with Request.body() for raw access
+ */
+
+// ── Section 1: Client Interface ──────────────────────────
+//
+// Authenticated HTTP client with rate limiting.
+// API key stored in financial vault (never .env).
+
+interface KongoClientConfig {
+  apiKey: string;          // ke_live_ prefix, vault-sourced
+  baseUrl?: string;        // Default: https://kongo.io/api/v1
+  timeoutMs?: number;      // Default: 30_000
+  rateLimitPerMinute?: number;  // Default: 60 (client-side safety)
+}
+
+// Client methods: get<T>, post<T>, put<T>, patch<T>, delete<T>
+// All return parsed response data (envelope unwrapped).
+// Automatic retry on 429/503 with exponential backoff (3 attempts).
+// Rate limiter: sliding window, throws KongoApiError on exhaustion.
+
+// Error type extends the standard ApiError pattern:
+class KongoApiError extends Error {
+  constructor(
+    public code: string,     // Kongo error code (UNAUTHORIZED, RATE_LIMITED, etc.)
+    message: string,
+    public status: number,   // HTTP status
+    public retryable: boolean,
+    public retryAfterMs?: number,
+  ) {
+    super(message);
+  }
+}
+
+// ── Section 2: From-PRD Page Generation ──────────────────
+//
+// Maps PRD content to Kongo's page creation API.
+// No custom endpoint needed — uses existing POST /engine/pages
+// with the `brief` field for structured input.
+
+interface PrdSeedContent {
+  projectName: string;
+  headline: string;
+  subheadline: string;
+  valueProps: string[];      // 3-5 bullet points
+  ctaText: string;
+  ctaUrl: string;
+  brandColors: { primary: string; secondary: string; accent: string };
+  logoUrl?: string;
+  socialProof?: string[];
+  campaignId?: string;       // VoidForge campaign ID for UTM linking
+  platform?: string;         // Target ad platform (affects page style)
+}
+
+// Seed → Kongo mapping:
+//   PrdSeedContent.projectName  → CreatePageRequest.companyName
+//   PrdSeedContent.*            → CreatePageRequest.brief (structured)
+//   PrdSeedContent.*            → CreatePageRequest.content (flattened text)
+//   PrdSeedContent.brandColors  → CreatePageRequest.style.colors
+//   Always: template='landing-page', hosted=true
+//   Metadata: source='voidforge', projectName, campaignId, platform
+
+// Polling: awaitPage() polls GET /engine/pages/:id every 3s until READY.
+// Timeout: 120s default. Throws KongoApiError on ERROR status.
+
+// ── Section 3: Growth Signal ─────────────────────────────
+//
+// Kongo doesn't have a dedicated growth-signal endpoint.
+// Compute it client-side from campaign analytics.
+
+interface ComputedGrowthSignal {
+  campaignId: string;
+  winningVariantId: string | null;  // null if no winner yet
+  confidence: number;               // 0.0-1.0
+  conversionRateDelta: number;      // Lift over control
+  recommendation: 'scale' | 'iterate' | 'kill' | 'wait';
+  reasoning: string;
+  sampleSize: { control: number; variant: number };
+}
+
+// Algorithm: Two-proportion z-test comparing best challenger vs control (first variant by creation order).
+// Minimum thresholds: 200 total views, 100 per variant.
+// Confidence mapping:
+//   ≥0.95 + positive delta → 'scale' (winner found)
+//   ≥0.80 + positive delta → 'iterate' (promising, need more data)
+//   ≥0.95 + negative/zero delta + 500+ views → 'kill'
+//   else → 'wait'
+
+// ── Section 4: Webhook Handlers ──────────────────────────
+//
+// Kongo sends webhooks for page lifecycle events.
+// Signature: X-Kongo-Signature: t=timestamp,v1=hmac_sha256
+
+// Verification steps:
+// 1. Parse header: split by comma → extract t= and v1= parts
+// 2. Check freshness: reject if timestamp > 5 minutes old
+// 3. Compute expected: HMAC-SHA256 of "timestamp.rawBody" with secret
+// 4. Compare: timing-safe comparison (prevents timing attacks)
+
+// Events:
+// - page.completed → update page status in heartbeat state
+// - page.failed → log error, flag for retry on next daemon cycle
+
+// Router pattern:
+//   const router = createWebhookRouter();
+//   router.on('page.completed', async (payload) => { ... });
+//   router.on('page.failed', async (payload) => { ... });
+//   await router.handle(rawBody, signature, secret);
+
+// ── Section 5: Campaign-Page Linkage ─────────────────────
+//
+// Ad campaigns point to Kongo pages with UTM parameters.
+
+// UTM taxonomy (standardized with Vin):
+//   utm_source   = voidforge
+//   utm_medium   = paid | organic | email | social
+//   utm_campaign = {voidforge_campaign_id}
+//   utm_content  = {kongo_variant_id}
+//   utm_term     = {keyword} (paid search only)
+
+// Kongo campaigns use rotation strategies:
+//   'weighted' — manual traffic weights per variant
+//   'equal'    — even split across all variants
+//   'bandit'   — multi-armed bandit (auto-optimize)
+
+// AI variant generation:
+//   POST /engine/campaigns/:id/variants/generate
+//   count: 1-20, vary: ['headline', 'tagline', 'cta_text'], context: string
+//   ~$0.01, ~3s for 5 variants (Claude Sonnet)
+
+// ── Section 6: Daemon Jobs ───────────────────────────────
+//
+// Three Kongo-specific heartbeat jobs:
+
+// kongo-signal (hourly):
+//   Poll getGrowthSignal() for all published campaigns.
+//   Log signals to heartbeat.json. Forward 'scale'/'kill' for daemon action.
+//   Fault-tolerant: continues polling other campaigns if one fails.
+
+// kongo-seed (event-driven):
+//   Triggered when Wayne's A/B evaluation declares a page variant winner.
+//   Extracts winning variant's slotValues.
+//   Available as seed for next createPageFromPrd() cycle.
+
+// kongo-webhook (event-driven):
+//   Receives POST from Kongo on daemon's callback port.
+//   Verifies HMAC signature. Routes to typed handlers.
+//   Conditional: only registered when Kongo API key exists in vault.
+
+export {};