edge-computing

name	edge-computing
description	Edge computing mastery. Cloudflare Workers, Vercel Edge Functions, Durable Objects, edge-compatible data patterns, cold start elimination, caching policies (Stale-While-Revalidate), and global data locality. Use when designing globally distributed, extreme low-latency applications architectures.
allowed-tools	Read, Write, Edit, Glob, Grep
version	2.0.0
last-updated	"2026-04-02T00:00:00.000Z"
applies-to-model	gemini-2.5-pro, claude-3-7-sonnet
routing	{"domain":"general","tier":"basic"}

Hallucination Traps (Read First)

• ❌ Importing Node.js-only APIs (fs, net, child_process) in edge functions -> ✅ Edge runtime has NO Node.js APIs; use Web APIs only
• ❌ Using global or module-level mutable state in edge -> ✅ Edge functions are stateless across requests; use KV/Durable Objects for state
• ❌ Assuming edge functions have unlimited execution time -> ✅ Cloudflare Workers: 30s, Vercel Edge: 25s; design for millisecond responses

---

Edge Computing — Global Latency Mastery

---

1. The Edge Model (V8 Isolates vs Node.js)

Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standard Node.js environments.

What This Means:

1. Extremely fast cold starts (< 5ms) because there is no underlying OS process bootup.
2. Hard memory/time limits per request (e.g., 50ms CPU time max).
3. NO NATIVE NODE MODULES. You cannot use fs, child_process, or heavy native C++ binaries (e.g., standard bcrypt, sharp).

// ❌ BAD: Attempting to use Node native core modules
import fs from "fs";
import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge

// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(password));

---

2. Advanced Route Caching (Stale-While-Revalidate)

The highest value proposition of the edge is intercepting requests before they cross the ocean.

// Standard Edge Proxy request handling
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    // 1. Cache API responses at the edge
    const cache = caches.default;
    let response = await cache.match(request);

    if (!response) {
      // 2. Fetch Origin (The real server in Virginia)
      response = await fetch(request);

      // 3. Mutate Headers for SWR (Stale-While-Revalidate)
      // Instructs the Edge CDN: Serve the stale version instantly to the user,
      // but fire an async request in the background to update the cache for the next user.
      response = new Response(response.body, response);
      response.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=86400");

      // 4. Store in Cache asynchronously (do not block the user response)
      ctx.waitUntil(cache.put(request, response.clone()));
    }

    return response;
  },
};

---

3. Edge Data Locality (The Database Problem)

Running logic globally while querying a monolithic database in us-east-1 is counter-productive. The latency of establishing a connection across the Atlantic will negate any Edge benefits.

Solutions:

1. Edge KV Stores: (Cloudflare KV, Vercel KV) Eventually consistent, highly localized read-latency configs suitable for configuration routing, user sessions, or feature flags.
2. Distributed SQLite: (Cloudflare D1, Turso) Replicas distributed to edge nodes automatically.
3. Connection Pooling: Use an HTTP/Connection Pool proxy strictly (e.g., Prisma Accelerate, Supabase Edge Pooler). You cannot establish TCP pg:// connections directly from millions of spinning V8 isolates, you will OOM crash the database.

// ✅ Turso / LibSQL (Distributed Edge DB) usage:
import { createClient } from "@libsql/client/web";

const client = createClient({
  url: env.TURSO_DATABASE_URL,
  authToken: env.TURSO_AUTH_TOKEN,
});

const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);

---

4. WebSockets at the Edge (Durable Objects)

Standard Edge functions are stateless. To hold persistent state (like a live multiplayer gaming room, or a chat room's WebSocket connections across multiple users), you must funnel those connections into a single point of state: a Durable Object.

// A Durable Object serves as a single source of truth that users globally connect into
export class ChatRoom {
  constructor(state, env) {
    this.state = state;
    this.sessions = [];
  }

  async fetch(request) {
    // Upgrade standard HTTP to WebSocket
    const pair = new WebSocketPair();

    // Accept connection, store it globally
    this.sessions.push(pair.server);
    pair.server.accept();

    // Handle incoming Chat messages
    pair.server.addEventListener("message", (msg) => {
      // Broadcast to all other connected edge users
      this.sessions.forEach((session) => session.send(msg.data));
    });

    return new Response(null, { status: 101, webSocket: pair.client });
  }
}

---

---

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

---

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

Pre-Flight Checklist

• Have I reviewed the user's specific constraints and requests?
• Have I checked the environment for relevant existing implementations?

VBC Protocol (Verification-Before-Completion)

You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

---

🤖 LLM-Specific Traps

AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:

1. Over-engineering: Proposing complex abstractions or distributed systems when a simpler approach suffices.
2. Hallucinated Libraries/Methods: Using non-existent methods or packages. Always // VERIFY or check package.json / requirements.txt.
3. Skipping Edge Cases: Writing the "happy path" and ignoring error handling, timeouts, or data validation.
4. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.
5. Silent Degradation: Catching and suppressing errors without logging or re-raising.

---

🏛️ Tribunal Integration (Anti-Hallucination)

Slash command: /review or /tribunal-full Active reviewers: logic-reviewer · security-auditor

❌ Forbidden AI Tropes

1. Blind Assumptions: Never make an assumption without documenting it clearly with // VERIFY: [reason].
2. Silent Degradation: Catching and suppressing errors without logging or handling.
3. Context Amnesia: Forgetting the user's constraints and offering generic advice instead of tailored solutions.

✅ Pre-Flight Self-Audit

Review these questions before confirming output:

✅ Did I rely ONLY on real, verified tools and methods?
✅ Is this solution appropriately scoped to the user's constraints?
✅ Did I handle potential failure modes and edge cases?
✅ Have I avoided generic boilerplate that doesn't add value?

🛑 Verification-Before-Completion (VBC) Protocol

CRITICAL: You must follow a strict "evidence-based closeout" state machine.

• ❌ Forbidden: Declaring a task complete because the output "looks correct."
• ✅ Required: You are explicitly forbidden from finalizing any task without providing concrete evidence (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.