@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/patterns-standards/ES_MODULE_IMPORT_HOISTING_DOTENV.md

@@ -0,0 +1,298 @@
+# ES Module Import Hoisting & dotenv - The Silent Initialization Bug
+
+## The Problem
+
+Environment variables from `.env` files are always `undefined` when checked at module load time, even though:
+- The `.env` file exists and has correct values
+- `dotenv.config()` is called at the top of your entry file
+- The server logs show `.env` was loaded
+
+### Error Messages
+
+```
+Error: Stripe is not configured. Please set STRIPE_SECRET_KEY environment variable.
+```
+
+```
+[PaymentService] STRIPE_SECRET_KEY available: false
+[PaymentService] Stripe initialized: false
+[dotenv@17.2.3] injecting env (46) from .env    ← Notice: dotenv loads AFTER!
+[Server] Loaded environment from: .env
+```
+
+### Why It Was Hard
+
+- **Counter-intuitive** - `dotenv.config()` is at the TOP of server.js, yet runs AFTER imports
+- **Silent failure** - No errors during startup, services just initialize with `null`
+- **Misleading logs** - Server says "Loaded environment" but services already failed
+- **Works in CommonJS** - The same pattern works fine with `require()`, so developers don't expect it to break with ES Modules
+- **Intermittent appearance** - Sometimes works if import order happens to be favorable
+
+### Impact
+
+- Payment processing fails (Stripe)
+- Authentication fails (JWT secrets)
+- Database connections fail
+- Email services fail
+- Any service initialized at module load time fails
+
+---
+
+## The Solution
+
+### Root Cause: ES Module Execution Order
+
+In ES Modules, **all imports are hoisted and fully executed** before ANY of the importing module's code runs.
+
+```javascript
+// server.js - What you WRITE:
+import dotenv from 'dotenv';
+dotenv.config();  // You think this runs first
+
+import { paymentService } from './services/paymentService.js';
+
+// server.js - What ACTUALLY HAPPENS:
+// 1. paymentService.js is FULLY EXECUTED (including top-level code)
+// 2. dotenv module is loaded
+// 3. THEN server.js code runs (dotenv.config())
+```
+
+So if `paymentService.js` has:
+
+```javascript
+// paymentService.js - TOP-LEVEL CODE (runs at import time!)
+const stripe = process.env.STRIPE_SECRET_KEY
+    ? new Stripe(process.env.STRIPE_SECRET_KEY)
+    : null;  // Always null because dotenv hasn't loaded yet!
+```
+
+This code runs **before** `dotenv.config()` is called, so `process.env.STRIPE_SECRET_KEY` is always `undefined`.
+
+### How to Fix: Lazy Initialization Pattern
+
+Replace top-level initialization with a getter function that initializes on first use:
+
+**BEFORE (Broken):**
+```javascript
+// paymentService.js
+import Stripe from 'stripe';
+
+// BAD: Runs at import time, before dotenv loads!
+const stripe = process.env.STRIPE_SECRET_KEY
+    ? new Stripe(process.env.STRIPE_SECRET_KEY)
+    : null;
+
+export const createPayment = async () => {
+    if (!stripe) throw new Error('Stripe not configured');
+    // ...
+};
+```
+
+**AFTER (Fixed):**
+```javascript
+// paymentService.js
+import Stripe from 'stripe';
+
+// GOOD: Lazy initialization - runs on first use, after dotenv loads
+let stripe = null;
+let stripeInitialized = false;
+
+const getStripe = () => {
+    if (!stripeInitialized) {
+        stripeInitialized = true;
+        if (process.env.STRIPE_SECRET_KEY) {
+            stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+            console.log('[PaymentService] ✅ Stripe initialized successfully');
+        } else {
+            console.warn('[PaymentService] ⚠️ STRIPE_SECRET_KEY not set');
+        }
+    }
+    return stripe;
+};
+
+export const createPayment = async () => {
+    const stripeInstance = getStripe();
+    if (!stripeInstance) throw new Error('Stripe not configured');
+    // Use stripeInstance instead of stripe
+};
+```
+
+### Alternative Fix: Dynamic Import
+
+If you can't modify the service file, use dynamic import:
+
+```javascript
+// server.js
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Dynamic import - runs AFTER this point
+const { paymentService } = await import('./services/paymentService.js');
+```
+
+---
+
+## Testing the Fix
+
+### Before Fix - Logs Show Wrong Order
+```
+[PaymentService] STRIPE_SECRET_KEY available: false   ← Checked BEFORE dotenv
+[PaymentService] Stripe initialized: false
+[dotenv@17.2.3] injecting env from .env               ← dotenv loads AFTER
+[Server] Loaded environment from: .env
+```
+
+### After Fix - Lazy Init Works
+```
+[dotenv@17.2.3] injecting env from .env
+[Server] Loaded environment from: .env
+[Server] Starting...
+[PaymentService] ✅ Stripe initialized successfully (lazy)   ← On first use
+```
+
+### Verification Test
+```javascript
+// Add this to verify the fix
+console.log('[DEBUG] At import time, STRIPE_SECRET_KEY is:',
+    process.env.STRIPE_SECRET_KEY ? 'SET' : 'NOT SET');
+```
+
+If this shows "NOT SET" at the top of your service file but "SET" inside a function, you have this bug.
+
+---
+
+## Prevention
+
+### 1. Never Initialize at Top Level
+```javascript
+// ❌ BAD - Top-level initialization
+const client = new ThirdPartyClient(process.env.API_KEY);
+
+// ✅ GOOD - Lazy initialization
+let client = null;
+const getClient = () => {
+    if (!client && process.env.API_KEY) {
+        client = new ThirdPartyClient(process.env.API_KEY);
+    }
+    return client;
+};
+```
+
+### 2. Use Config Modules with Lazy Loading
+```javascript
+// config/stripe.js
+let stripe = null;
+let initialized = false;
+
+export const getStripe = () => {
+    if (!initialized) {
+        initialized = true;
+        if (process.env.STRIPE_SECRET_KEY) {
+            stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+        }
+    }
+    return stripe;
+};
+```
+
+### 3. Check for This Pattern in Code Reviews
+
+Look for:
+```javascript
+// Red flags at module top level:
+const x = process.env.SOMETHING;
+const client = new Client(process.env.KEY);
+if (process.env.FEATURE_FLAG) { ... }
+```
+
+### 4. Add Startup Verification
+
+```javascript
+// server.js - after dotenv.config()
+const requiredEnvVars = ['STRIPE_SECRET_KEY', 'JWT_SECRET', 'DATABASE_URL'];
+const missing = requiredEnvVars.filter(v => !process.env[v]);
+if (missing.length) {
+    console.error('Missing required environment variables:', missing);
+    process.exit(1);
+}
+```
+
+---
+
+## Related Patterns
+
+- [PM2 Environment Variable Caching](../deployment-security/PM2_ENVIRONMENT_VARIABLE_CACHING.md)
+- [Environment File Management](../deployment-security/env-file-management-production-local.md)
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Top-level `process.env` checks** - Always undefined before dotenv
+- ❌ **Assuming import order matters** - ES Modules hoist ALL imports
+- ❌ **Using CommonJS patterns in ES Modules** - `require()` order ≠ `import` order
+- ❌ **Debug logging at top level** - Shows misleading "not set" messages
+- ❌ **Conditional exports based on env** - Will always use the "else" branch
+
+---
+
+## Why This Works in CommonJS But Not ES Modules
+
+### CommonJS (require) - Works
+```javascript
+// server.js - CommonJS
+require('dotenv').config();  // Runs immediately, synchronously
+
+// This import happens AFTER dotenv.config()
+const payment = require('./services/payment');
+// payment.js top-level code now has access to env vars
+```
+
+### ES Modules (import) - Broken
+```javascript
+// server.js - ES Modules
+import dotenv from 'dotenv';
+dotenv.config();  // You THINK this runs first...
+
+import { payment } from './services/payment.js';
+// BUT payment.js was already FULLY EXECUTED before this line!
+```
+
+The key difference: `require()` is a function that runs synchronously at that point in the code. `import` is a declaration that's hoisted and resolved before any code runs.
+
+---
+
+## Resources
+
+- [MDN: ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
+- [Node.js: ES Modules](https://nodejs.org/api/esm.html)
+- [dotenv with ES Modules](https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import)
+
+---
+
+## Time to Implement
+
+**10-15 minutes** per service - Convert top-level init to lazy getter pattern
+
+## Difficulty Level
+
+⭐⭐⭐⭐ (4/5) - Very hard to diagnose, easy to fix once understood
+
+---
+
+**Author Notes:**
+
+This bug cost 2+ hours of debugging. The symptoms are extremely confusing:
+- `.env` file has the right values
+- Server logs show "Loaded environment from: .env"
+- But services report env vars as undefined
+
+The critical insight: **In ES Modules, ALL imports execute BEFORE your code runs.**
+
+Once you understand this, the fix is obvious. But getting there requires understanding the fundamental difference between CommonJS and ES Modules execution models.
+
+**Key diagnostic:** Look at the LOG ORDER. If service initialization logs appear BEFORE the dotenv loading log, you have this bug.
+
+**Discovery date:** January 2026
+**Project:** MERN Community LMS
+**Symptom:** "Stripe is not configured" despite valid .env file

package/skills-library/patterns-standards/NESTED_BACKDROP_FILTER_CSS_ARTIFACT_FIX.md

@@ -0,0 +1,76 @@
+# Nested CSS backdrop-filter Artifact Fix
+
+## Problem
+
+A white blurry line or haze overlay appears on UI elements when using glassmorphism / frosted glass CSS effects. The artifact is most visible in dark mode and appears as a semi-transparent white strip or blur effect layered on top of content.
+
+## Root Cause
+
+**Nested `backdrop-filter: blur()` declarations** on parent and child elements create compounding blur artifacts. Each `backdrop-filter` creates a new stacking context and compositing layer. When two blur layers overlap, the browser renders an extra semi-transparent white haze at the boundary.
+
+### Example of the Problem
+
+```css
+/* Parent element */
+.panel-container {
+  background-color: rgba(17, 24, 39, 0.85);
+  -webkit-backdrop-filter: blur(20px);
+  backdrop-filter: blur(20px);
+}
+
+/* Child element — REDUNDANT blur causes artifact */
+[data-theme='dark'] .bible-viewer {
+  background-color: rgba(17, 24, 39, 0.5);  /* Semi-transparent */
+  -webkit-backdrop-filter: blur(20px);
+  backdrop-filter: blur(20px);
+}
+```
+
+The child's blur composites on top of the parent's blur, creating a visible white line at the boundary.
+
+## Solution
+
+Remove `backdrop-filter` from the **inner/child** element and use an opaque or semi-opaque background instead:
+
+```css
+/* Parent keeps the glass effect */
+.panel-container {
+  background-color: rgba(17, 24, 39, 0.85);
+  -webkit-backdrop-filter: blur(20px);
+  backdrop-filter: blur(20px);
+}
+
+/* Child uses opaque background — NO blur */
+[data-theme='dark'] .bible-viewer {
+  background-color: var(--bg-secondary);  /* Opaque, no blur */
+}
+```
+
+### Rule of Thumb
+
+**Only ONE element in any ancestor chain should have `backdrop-filter`.** If the parent already blurs, children should use:
+- Opaque backgrounds (`var(--bg-secondary)`)
+- Semi-transparent backgrounds without blur (`rgba(...)` alone)
+- `background: inherit` to match the parent
+
+## Debugging Tips
+
+1. **Inspect with DevTools** — Toggle `backdrop-filter` off on each element to find which one is redundant
+2. **Check dark mode specifically** — Artifacts are most visible when backgrounds are semi-transparent dark colors
+3. **Search for all blur declarations**: `grep -r "backdrop-filter" src/` to find all instances
+4. **Test across browsers** — Chrome, Firefox, and Safari handle compositing differently
+
+## When This Happens
+
+- Glassmorphism / frosted glass UI designs
+- Dark mode implementations with semi-transparent panels
+- Nested panel layouts (sidebar → content → sub-panel)
+- CSS frameworks that apply blur at multiple levels
+
+## Tech Stack
+- CSS (any framework)
+- Tailwind CSS (when using `backdrop-blur-*` utilities)
+- Dark mode / theme switching
+
+## Tags
+`css` `backdrop-filter` `blur` `glassmorphism` `dark-mode` `visual-artifact` `stacking-context`

package/skills-library/patterns-standards/ORDERED_DETECTOR_PIPELINE_GRACEFUL_FALLBACK.md

@@ -0,0 +1,333 @@
+---
+name: ordered-detector-pipeline-graceful-fallback
+category: patterns-standards
+version: 1.0.0
+contributed: 2026-02-17
+contributor: my-other-project
+last_updated: 2026-02-17
+contributors:
+  - my-other-project
+tags: [detection, pipeline, graceful-degradation, postgresql, try-catch, incremental-rollout, milestone, feature-flags]
+difficulty: medium
+usage_count: 1
+success_rate: 100
+---
+
+# Ordered Detector Pipeline with Graceful Fallback
+
+## Problem
+
+You need to detect multiple conditions (milestones, achievements, alerts, etc.) by querying **different database tables** — but some tables may not exist yet because they belong to future phases that haven't shipped. A single missing table would crash the entire detection system.
+
+### Why It Was Hard
+
+- Standard approaches (one big JOIN, CTE chain) fail if **any** table is missing
+- Feature-flag systems add complexity and state management overhead
+- Incremental rollouts mean tables arrive over time (Phase 18 ships before Phase 19)
+- Detectors have **different priorities** — the most impressive milestone should surface first
+- Need cooldown, deduplication, and conversion tracking alongside detection
+- Must work with zero configuration changes when new tables appear later
+
+### Impact
+
+Without this pattern, adding a milestone detector that references a not-yet-created table (`user_progress`) would crash the entire `/api/milestones/check` endpoint, preventing all milestone celebrations — even for tables that DO exist.
+
+---
+
+## Solution Pattern
+
+**Ordered Detector Array** — define detectors as an array of `{ type, detect }` objects sorted by priority. Each `detect` function runs its own SQL query inside its own `try/catch`. If the table doesn't exist or the query fails, it returns `null` gracefully. The pipeline iterates until it finds a match.
+
+### Root Cause
+
+The problem occurs because:
+1. SQL JOINs across non-existent tables throw fatal errors
+2. A single `try/catch` around multiple queries loses granularity
+3. Priority ordering requires sequential evaluation (can't parallelize)
+
+### Architecture
+
+```
+                    checkMilestones(userId)
+                           │
+                    ┌──────▼──────┐
+                    │ canShow?     │  ← 24h cooldown check
+                    │ (cooldown)   │
+                    └──────┬──────┘
+                           │ yes
+              ┌────────────▼────────────────┐
+              │  MILESTONE_DETECTORS array   │
+              │  (ordered by impressiveness) │
+              └────────────┬────────────────┘
+                           │
+        ┌──────────────────┼──────────────────┐
+        ▼                  ▼                   ▼
+  ┌───────────┐    ┌───────────┐      ┌───────────┐
+  │ Detector 1│    │ Detector 2│ ...  │ Detector N│
+  │ try/catch │    │ try/catch │      │ try/catch │
+  │ → null ok │    │ → null ok │      │ → null ok │
+  └─────┬─────┘    └─────┬─────┘      └─────┬─────┘
+        │                │                    │
+        ▼                ▼                    ▼
+   {data,context}     null              {data,context}
+        │                                     │
+        ▼                                     │
+  alreadyCelebrated? ─── yes ─── skip ────────┘
+        │ no                                  │
+        ▼                                     ▼
+  getCelebrationConfig ──── inactive ─── continue
+        │ active
+        ▼
+  recordCelebration → return milestone
+```
+
+### How to Fix / Implement
+
+**Step 1: Define the detector array with priority ordering**
+
+```javascript
+// Ordered by "impressiveness" — most meaningful surfaces first
+const MILESTONE_DETECTORS = [
+  { type: 'learning_path_complete', detect: detectLearningPathComplete },
+  { type: 'lesson_100',            detect: detectLesson100 },
+  { type: 'certificate_earned',    detect: detectCertificateEarned },
+  { type: 'first_course_complete', detect: detectFirstCourseComplete },
+  { type: 'streak_7_days',         detect: detectStreak7 },  // table from Phase 19
+];
+```
+
+**Step 2: Each detector is an independent function with its own try/catch**
+
+```javascript
+// This table exists now (Phase 15) — works immediately
+async function detectFirstCourseComplete(userId) {
+  try {
+    const [row] = await sql`
+      SELECT ep.course_id, c.title AS course_title
+      FROM enrollment_progress ep
+      JOIN courses c ON c.id = ep.course_id
+      WHERE ep.user_id = ${userId}
+        AND (ep.progress_percentage >= 100 OR ep.status = 'completed')
+      ORDER BY ep.updated_at ASC
+      LIMIT 1
+    `;
+    if (!row) return null;
+    return {
+      data: { course_id: row.course_id },      // for deduplication
+      context: row.course_title,                 // human-readable
+    };
+  } catch { return null; }  // table missing or query error → skip
+}
+
+// This table doesn't exist yet (Phase 19) — gracefully returns null
+async function detectStreak7(userId) {
+  try {
+    const [row] = await sql`
+      SELECT current_streak FROM user_progress
+      WHERE user_id = ${userId} AND current_streak >= 7
+    `;
+    if (!row) return null;
+    return {
+      data: { streak: row.current_streak },
+      context: `${row.current_streak}-day streak`,
+    };
+  } catch {
+    // user_progress table may not exist yet (Phase 19 creates it)
+    return null;
+  }
+}
+```
+
+**Step 3: Pipeline iterates, deduplicates, and respects cooldown**
+
+```javascript
+static async checkMilestones(userId) {
+  // Cooldown: max 1 celebration per 24 hours
+  const canShow = await canShowCelebration(userId);
+  if (!canShow) return null;
+
+  for (const { type, detect } of MILESTONE_DETECTORS) {
+    const result = await detect(userId);
+    if (result) {
+      // Check if already celebrated this exact achievement
+      const alreadyShown = await alreadyCelebrated(userId, type, result.data);
+      if (!alreadyShown) {
+        // Check if this milestone type is active (admin toggle)
+        const config = await getCelebrationConfig(type);
+        if (!config || !config.is_active) continue;
+
+        // Record and return
+        const celebration = await recordCelebration(userId, type, result.data);
+        return {
+          id: celebration.id,
+          milestoneType: type,
+          config,
+          context: result.context,
+        };
+      }
+    }
+  }
+  return null;
+}
+```
+
+**Step 4: Deduplication via JSONB comparison**
+
+```sql
+-- Each detector returns { data } which becomes milestone_data
+-- UNIQUE constraint prevents duplicate celebrations
+UNIQUE(user_id, milestone_type, milestone_data)
+
+-- Check uses JSONB cast for exact comparison
+SELECT 1 FROM milestone_celebrations
+WHERE user_id = $1
+  AND milestone_type = $2
+  AND milestone_data = $3::jsonb
+LIMIT 1
+```
+
+**Step 5: Cooldown via SQL interval**
+
+```sql
+-- No celebration shown in last 24 hours
+SELECT 1 FROM milestone_celebrations
+WHERE user_id = $1
+  AND shown_at > now() - interval '24 hours'
+LIMIT 1
+```
+
+---
+
+## Key Design Decisions
+
+| Decision | Why |
+|----------|-----|
+| Per-detector try/catch (not global) | Missing table X doesn't block table Y detection |
+| Priority ordering (array, not parallel) | Most impressive milestone surfaces first |
+| Each detector returns `{ data, context }` | `data` for dedup, `context` for UI display |
+| Cooldown at pipeline level (not detector) | One celebration per 24h regardless of type |
+| Config-driven messages | Admin can customize per milestone type without code changes |
+| ON CONFLICT upsert for recording | Idempotent — re-showing updates `shown_at` |
+
+---
+
+## Database Schema (Supporting Infrastructure)
+
+```sql
+-- Admin-configurable celebration messages
+CREATE TABLE milestone_configs (
+  milestone_type VARCHAR(50) PRIMARY KEY,
+  title TEXT NOT NULL,
+  message TEXT NOT NULL,
+  emoji VARCHAR(10) DEFAULT '🎉',
+  suggested_amounts JSONB DEFAULT '[10, 25, 50]',
+  is_active BOOLEAN DEFAULT true,
+  updated_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Tracks shown/dismissed/converted celebrations per user
+CREATE TABLE milestone_celebrations (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES profiles(id),
+  milestone_type VARCHAR(50) REFERENCES milestone_configs(milestone_type),
+  milestone_data JSONB DEFAULT '{}',
+  shown_at TIMESTAMPTZ DEFAULT now(),
+  dismissed_at TIMESTAMPTZ,
+  converted BOOLEAN DEFAULT false,
+  converted_at TIMESTAMPTZ,
+  donation_amount NUMERIC(10,2) DEFAULT 0,
+  UNIQUE(user_id, milestone_type, milestone_data)
+);
+
+-- Partial index for analytics queries
+CREATE INDEX idx_celebrations_converted
+  ON milestone_celebrations(milestone_type) WHERE converted = true;
+```
+
+---
+
+## Testing the Pattern
+
+### Verify Graceful Fallback
+```sql
+-- Drop a table that a detector references
+DROP TABLE IF EXISTS user_progress;
+
+-- Call the endpoint — should NOT crash, just skip that detector
+GET /api/milestones/check
+-- Expected: returns milestone from another detector or null
+```
+
+### Verify Priority Ordering
+```sql
+-- Give user both a completed course AND a certificate
+-- The certificate detector has higher priority
+-- Expected: certificate milestone returned, not course completion
+```
+
+### Verify Cooldown
+```sql
+-- Trigger a celebration, then call check again within 24h
+-- Expected: null (cooldown active)
+```
+
+### Verify Deduplication
+```sql
+-- Complete the same course twice
+-- Expected: celebration shown only once (UNIQUE constraint)
+```
+
+---
+
+## When to Use
+
+- Building achievement/milestone detection across multiple feature phases
+- Any detection pipeline where data sources ship incrementally
+- Multi-table aggregation where some tables are optional
+- Feature rollouts where backend tables appear in different sprints
+- Gamification systems (badges, streaks, levels) built across phases
+- Alert/notification systems checking diverse conditions
+
+## When NOT to Use
+
+- All data sources exist and are guaranteed present (just use a JOIN)
+- Single-table detection (overkill — just write a simple query)
+- Real-time streaming events (use an event bus, not polling)
+- Detection order doesn't matter (use `Promise.allSettled` instead)
+
+## Common Mistakes
+
+- Wrapping ALL detectors in one `try/catch` — defeats the purpose, one failure kills all
+- Running detectors in parallel — breaks priority ordering (highest first matters)
+- Forgetting to return `null` in the catch — undefined bubbles up as truthy
+- Using `SELECT *` in detectors — return only what's needed for dedup and display
+- Skipping cooldown — users get spammed with celebrations on every page load
+- Hardcoding celebration messages — use a config table so admins can customize
+
+---
+
+## Related Skills
+
+- [ERROR_RESILIENCE_IMPLEMENTATION.md](./ERROR_RESILIENCE_IMPLEMENTATION.md) - Database trigger error handling
+- [CONDITIONAL_SQL_MIGRATION_PATTERN.md](../database-solutions/CONDITIONAL_SQL_MIGRATION_PATTERN.md) - Idempotent migrations
+- [GAMIFICATION_SYSTEM.md](../advanced-features/GAMIFICATION_SYSTEM.md) - Points, badges, achievements
+
+## References
+
+- Phase 18 — Milestone Giving (Harvest Offering) implementation
+- postgres.js tagged template literals: https://github.com/porsager/postgres
+- PostgreSQL JSONB comparison: https://www.postgresql.org/docs/current/datatype-json.html
+
+## Time to Implement
+
+**2-3 hours** for full pipeline (detectors + config table + cooldown + deduplication + conversion tracking)
+**30 minutes** to add a new detector to an existing pipeline
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Conceptually simple, but requires discipline: every detector MUST be isolated, return format MUST be consistent, and the pipeline MUST handle all edge cases (missing tables, cooldown, dedup).
+
+---
+
+**Author Notes:**
+The key insight is treating each detector as a **completely independent unit** that can fail without affecting others. This is the database equivalent of microservice isolation — but within a single service. The pattern scales beautifully: adding Phase 19's streak detector required zero changes to existing code, just appending to the array. When the `user_progress` table appears, the detector automatically starts working.