@littlebearapps/create-platform 1.0.0 → 1.1.0

package/templates/shared/workers/lib/control.ts

@@ -0,0 +1,292 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * PID Controller for Intelligent Degradation
+ *
+ * Provides smooth throttle rate calculation (0.0-1.0) instead of binary ON/OFF.
+ * State is stored in KV, making the controller stateless per invocation.
+ *
+ * Key principle: PID provides smooth degradation, circuit breakers remain the emergency stop.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * PID controller gains and configuration.
+ * Tuned for budget-based throttling where:
+ * - setpoint (0.70) = target 70% budget utilisation
+ * - Output range [0, 1] = throttle rate (0=no throttle, 1=full throttle)
+ */
+export interface PIDConfig {
+  /** Proportional gain - responds to current error */
+  kp: number;
+  /** Integral gain - responds to accumulated error */
+  ki: number;
+  /** Derivative gain - responds to rate of change */
+  kd: number;
+  /** Target budget utilisation (0.0-1.0) */
+  setpoint: number;
+  /** Minimum output value (default: 0) */
+  outputMin: number;
+  /** Maximum output value (default: 1) */
+  outputMax: number;
+  /** Maximum integral accumulation to prevent windup */
+  integralMax: number;
+}
+
+/**
+ * Persisted PID state stored in KV.
+ * Key: STATE:PID:{feature_id}
+ */
+export interface PIDState {
+  /** Accumulated error (integral term) */
+  integral: number;
+  /** Previous error for derivative calculation */
+  prevError: number;
+  /** Last update timestamp (ms) */
+  lastUpdate: number;
+  /** Current throttle rate output */
+  throttleRate: number;
+}
+
+/**
+ * Input for PID computation.
+ */
+export interface PIDInput {
+  /** Current budget utilisation (0.0-1.0+, can exceed 1.0 if over budget) */
+  currentUsage: number;
+  /** Time since last update in milliseconds */
+  deltaTimeMs: number;
+}
+
+/**
+ * Output from PID computation.
+ */
+export interface PIDOutput {
+  /** Computed throttle rate (0.0-1.0) */
+  throttleRate: number;
+  /** Updated state to persist */
+  newState: PIDState;
+  /** Debug info for monitoring */
+  debug: {
+    error: number;
+    pTerm: number;
+    iTerm: number;
+    dTerm: number;
+  };
+}
+
+// =============================================================================
+// DEFAULT CONFIGURATION
+// =============================================================================
+
+/**
+ * Default PID configuration tuned for budget-based throttling.
+ *
+ * Rationale:
+ * - kp=0.5: Moderate response to current error (50% of error -> throttle change)
+ * - ki=0.1: Slow integral to avoid oscillation, correct steady-state error
+ * - kd=0.05: Light derivative to dampen sudden changes
+ * - setpoint=0.70: Target 70% budget utilisation, leaving 30% headroom
+ * - integralMax=2.0: Prevent integral windup during sustained over-budget
+ */
+export const DEFAULT_PID_CONFIG: PIDConfig = {
+  kp: 0.5,
+  ki: 0.1,
+  kd: 0.05,
+  setpoint: 0.7,
+  outputMin: 0,
+  outputMax: 1,
+  integralMax: 2.0,
+};
+
+/**
+ * Create a fresh PID state (for new features or reset).
+ */
+export function createPIDState(): PIDState {
+  return {
+    integral: 0,
+    prevError: 0,
+    lastUpdate: Date.now(),
+    throttleRate: 0,
+  };
+}
+
+// =============================================================================
+// PID COMPUTATION
+// =============================================================================
+
+/**
+ * Compute PID output for throttle rate.
+ *
+ * This is a stateless function - pass in current state, get new state back.
+ * The caller is responsible for persisting state to KV.
+ *
+ * @param state - Current PID state from KV (or fresh state for new features)
+ * @param input - Current usage and timing information
+ * @param config - PID configuration (defaults provided)
+ * @returns New throttle rate and updated state
+ *
+ * @example
+ * ```typescript
+ * const state = await getPIDState(featureId, env);
+ * const input = { currentUsage: 0.85, deltaTimeMs: 60000 };
+ * const output = computePID(state, input);
+ * await savePIDState(featureId, output.newState, env);
+ * ```
+ */
+export function computePID(
+  state: PIDState,
+  input: PIDInput,
+  config: PIDConfig = DEFAULT_PID_CONFIG
+): PIDOutput {
+  // Calculate error: positive = over budget, negative = under budget
+  // error > 0 means we need MORE throttling
+  const error = input.currentUsage - config.setpoint;
+
+  // Convert deltaTime to seconds for consistent gains regardless of update frequency
+  const dt = Math.max(input.deltaTimeMs / 1000, 0.001); // Minimum 1ms to avoid division issues
+
+  // Proportional term: immediate response to current error
+  const pTerm = config.kp * error;
+
+  // Integral term: accumulated error over time (with anti-windup)
+  let newIntegral = state.integral + error * dt;
+  // Clamp integral to prevent windup
+  newIntegral = Math.max(-config.integralMax, Math.min(config.integralMax, newIntegral));
+  const iTerm = config.ki * newIntegral;
+
+  // Derivative term: rate of change of error (damping)
+  const derivative = (error - state.prevError) / dt;
+  const dTerm = config.kd * derivative;
+
+  // Sum all terms
+  let output = pTerm + iTerm + dTerm;
+
+  // Clamp output to valid range
+  output = Math.max(config.outputMin, Math.min(config.outputMax, output));
+
+  // Create new state
+  const newState: PIDState = {
+    integral: newIntegral,
+    prevError: error,
+    lastUpdate: Date.now(),
+    throttleRate: output,
+  };
+
+  return {
+    throttleRate: output,
+    newState,
+    debug: {
+      error,
+      pTerm,
+      iTerm,
+      dTerm,
+    },
+  };
+}
+
+// =============================================================================
+// KV PERSISTENCE HELPERS
+// =============================================================================
+
+/**
+ * KV key for PID state.
+ */
+export function pidStateKey(featureId: string): string {
+  return `STATE:PID:${featureId}`;
+}
+
+/**
+ * KV key for throttle rate (read by SDK).
+ */
+export function throttleRateKey(featureId: string): string {
+  return `CONFIG:FEATURE:${featureId}:THROTTLE_RATE`;
+}
+
+/**
+ * Get PID state from KV, returning fresh state if not found.
+ */
+export async function getPIDState(featureId: string, kv: KVNamespace): Promise<PIDState> {
+  const key = pidStateKey(featureId);
+  const data = await kv.get(key, 'json');
+  if (data && typeof data === 'object') {
+    return data as PIDState;
+  }
+  return createPIDState();
+}
+
+/**
+ * Save PID state to KV with 24h TTL.
+ * Also writes throttle rate to separate key with 5min TTL for SDK consumption.
+ */
+export async function savePIDState(
+  featureId: string,
+  state: PIDState,
+  kv: KVNamespace
+): Promise<void> {
+  const stateKey = pidStateKey(featureId);
+  const rateKey = throttleRateKey(featureId);
+
+  // Save state with 24h TTL (for persistence across updates)
+  await kv.put(stateKey, JSON.stringify(state), { expirationTtl: 86400 });
+
+  // Save throttle rate separately with 5min TTL (for SDK quick access)
+  // Only write if throttle rate > 0 to avoid unnecessary KV writes
+  if (state.throttleRate > 0.001) {
+    await kv.put(rateKey, state.throttleRate.toString(), { expirationTtl: 300 });
+  } else {
+    // Delete the key if throttle rate is essentially 0
+    await kv.delete(rateKey);
+  }
+}
+
+/**
+ * Get current throttle rate for SDK consumption.
+ * Returns 0 if no throttle rate is set.
+ */
+export async function getThrottleRate(featureId: string, kv: KVNamespace): Promise<number> {
+  const key = throttleRateKey(featureId);
+  const value = await kv.get(key);
+  if (value) {
+    const rate = parseFloat(value);
+    return isNaN(rate) ? 0 : Math.max(0, Math.min(1, rate));
+  }
+  return 0;
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Calculate budget utilisation from current usage and limit.
+ *
+ * @param currentUsage - Current period usage value
+ * @param budgetLimit - Budget limit for the period
+ * @returns Utilisation ratio (0.0-1.0+, can exceed 1.0 if over budget)
+ */
+export function calculateUtilisation(currentUsage: number, budgetLimit: number): number {
+  if (budgetLimit <= 0) return 0;
+  return currentUsage / budgetLimit;
+}
+
+/**
+ * Determine if PID update is needed based on time since last update.
+ *
+ * @param lastUpdate - Timestamp of last PID update (ms)
+ * @param minIntervalMs - Minimum interval between updates (default: 60s)
+ * @returns True if update is due
+ */
+export function shouldUpdatePID(lastUpdate: number, minIntervalMs: number = 60_000): boolean {
+  return Date.now() - lastUpdate >= minIntervalMs;
+}
+
+/**
+ * Format throttle rate for logging (percentage with 1 decimal).
+ */
+export function formatThrottleRate(rate: number): string {
+  return `${(rate * 100).toFixed(1)}%`;
+}

package/templates/shared/workers/lib/economics.ts

@@ -0,0 +1,368 @@
+/**
+ * BCU (Budget Consumption Unit) Cost Allocator
+ *
+ * Provides scarcity-weighted quota enforcement for intelligent degradation.
+ * BCU normalises different resource types into a single unit for budget comparison.
+ *
+ * Key difference from costs.ts:
+ * - costs.ts: Financial reporting (actual USD costs)
+ * - economics.ts: Scarcity-weighted quota enforcement (relative resource pressure)
+ *
+ * BCU weights reflect scarcity and impact, not just cost:
+ * - AI neurons are expensive AND scarce (weight: 100)
+ * - D1 writes have durability implications (weight: 10)
+ * - KV writes are moderately constrained (weight: 1)
+ * - Requests are abundant but need tracking (weight: 0.001)
+ */
+
+import type { FeatureMetrics } from '@littlebearapps/platform-sdk';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Resource type for BCU calculation.
+ */
+export type ResourceType =
+  | 'aiNeurons'
+  | 'aiRequests'
+  | 'd1Writes'
+  | 'd1Reads'
+  | 'd1RowsWritten'
+  | 'd1RowsRead'
+  | 'kvWrites'
+  | 'kvReads'
+  | 'kvDeletes'
+  | 'kvLists'
+  | 'r2ClassA'
+  | 'r2ClassB'
+  | 'doRequests'
+  | 'doGbSeconds'
+  | 'queueMessages'
+  | 'vectorizeQueries'
+  | 'vectorizeInserts'
+  | 'workflowInvocations'
+  | 'requests'
+  | 'cpuMs';
+
+/**
+ * BCU weights per resource type.
+ */
+export type BCUWeights = Record<ResourceType, number>;
+
+/**
+ * Result of BCU calculation.
+ */
+export interface BCUResult {
+  /** Total BCU value */
+  total: number;
+  /** Breakdown by resource type */
+  breakdown: Partial<Record<ResourceType, number>>;
+  /** Dominant resource (highest BCU contribution) */
+  dominantResource: ResourceType | null;
+  /** Percentage contribution of dominant resource */
+  dominantPercentage: number;
+}
+
+/**
+ * Budget state with BCU tracking.
+ */
+export interface BCUBudgetState {
+  /** Current period BCU consumption */
+  currentBCU: number;
+  /** Budget limit in BCU */
+  limitBCU: number;
+  /** Utilisation ratio (0.0-1.0+) */
+  utilisation: number;
+  /** Whether budget is exceeded */
+  exceeded: boolean;
+}
+
+// =============================================================================
+// SCARCITY WEIGHTS
+// =============================================================================
+
+/**
+ * Default BCU weights reflecting resource scarcity and impact.
+ *
+ * Philosophy:
+ * - Expensive resources that are hard to scale get high weights
+ * - Cheap, abundant resources get low weights
+ * - Writes are weighted higher than reads (durability implications)
+ *
+ * TODO: Adjust these weights based on your specific scarcity constraints.
+ */
+export const DEFAULT_BCU_WEIGHTS: BCUWeights = {
+  // AI Resources - Most expensive and scarce
+  aiNeurons: 100, // $0.011 per 1K neurons, compute-intensive
+  aiRequests: 50, // Each AI call is significant
+
+  // D1 Database - Writes are expensive, reads are cheap
+  d1Writes: 10, // Deprecated field (use d1RowsWritten)
+  d1Reads: 0.01, // Deprecated field (use d1RowsRead)
+  d1RowsWritten: 10, // $1.00 per million, durability critical
+  d1RowsRead: 0.01, // $0.001 per billion, cheap
+
+  // KV - Writes constrained, reads abundant
+  kvWrites: 1, // $5.00 per million
+  kvReads: 0.1, // $0.50 per million
+  kvDeletes: 1, // Same cost as writes
+  kvLists: 1, // Same cost as writes
+
+  // R2 - Operations are relatively cheap
+  r2ClassA: 0.5, // $4.50 per million (PUT, POST, LIST)
+  r2ClassB: 0.05, // $0.36 per million (GET, HEAD)
+
+  // Durable Objects - Request-based pricing
+  doRequests: 0.5, // $0.15 per million
+  doGbSeconds: 5, // $12.50 per million GB-seconds
+
+  // Queues - Moderate pricing
+  queueMessages: 0.5, // $0.40 per million
+
+  // Vectorize - Query-intensive
+  vectorizeQueries: 1, // $0.01 per million dimensions
+  vectorizeInserts: 2, // Writes more expensive
+
+  // Workflows - Still in beta
+  workflowInvocations: 1, // Placeholder
+
+  // General compute
+  requests: 0.001, // Very cheap, 10M included
+  cpuMs: 0.01, // $0.02 per million ms
+};
+
+// =============================================================================
+// BCU CALCULATION
+// =============================================================================
+
+/**
+ * Calculate BCU (Budget Consumption Units) from metrics.
+ *
+ * BCU provides a normalised measure of resource consumption that accounts
+ * for scarcity, not just cost. This enables fair quota allocation across
+ * features with different resource profiles.
+ *
+ * @param metrics - Feature metrics from telemetry
+ * @param weights - BCU weights (defaults provided)
+ * @returns BCU result with total, breakdown, and dominant resource
+ *
+ * @example
+ * ```typescript
+ * const metrics = { aiNeurons: 1000, d1RowsWritten: 100, requests: 50 };
+ * const result = calculateBCU(metrics);
+ * // result.total = 100000 + 1000 + 0.05 = 101000.05
+ * // result.dominantResource = 'aiNeurons'
+ * // result.dominantPercentage = 99.01
+ * ```
+ */
+export function calculateBCU(
+  metrics: FeatureMetrics,
+  weights: BCUWeights = DEFAULT_BCU_WEIGHTS
+): BCUResult {
+  const breakdown: Partial<Record<ResourceType, number>> = {};
+  let total = 0;
+  let maxContribution = 0;
+  let dominantResource: ResourceType | null = null;
+
+  // Calculate BCU for each non-zero metric
+  const metricEntries: [ResourceType, number | undefined][] = [
+    ['aiNeurons', metrics.aiNeurons],
+    ['aiRequests', metrics.aiRequests],
+    ['d1Writes', metrics.d1Writes],
+    ['d1Reads', metrics.d1Reads],
+    ['d1RowsWritten', metrics.d1RowsWritten],
+    ['d1RowsRead', metrics.d1RowsRead],
+    ['kvWrites', metrics.kvWrites],
+    ['kvReads', metrics.kvReads],
+    ['kvDeletes', metrics.kvDeletes],
+    ['kvLists', metrics.kvLists],
+    ['r2ClassA', metrics.r2ClassA],
+    ['r2ClassB', metrics.r2ClassB],
+    ['doRequests', metrics.doRequests],
+    // Note: doGbSeconds not in FeatureMetrics - omitted
+    ['queueMessages', metrics.queueMessages],
+    ['vectorizeQueries', metrics.vectorizeQueries],
+    ['vectorizeInserts', metrics.vectorizeInserts],
+    ['workflowInvocations', metrics.workflowInvocations],
+    ['requests', metrics.requests],
+    ['cpuMs', metrics.cpuMs],
+  ];
+
+  for (const [resource, value] of metricEntries) {
+    if (value && value > 0) {
+      const weight = weights[resource];
+      const contribution = value * weight;
+      breakdown[resource] = contribution;
+      total += contribution;
+
+      if (contribution > maxContribution) {
+        maxContribution = contribution;
+        dominantResource = resource;
+      }
+    }
+  }
+
+  const dominantPercentage = total > 0 ? (maxContribution / total) * 100 : 0;
+
+  return {
+    total,
+    breakdown,
+    dominantResource,
+    dominantPercentage,
+  };
+}
+
+/**
+ * Calculate BCU from raw metric values (not FeatureMetrics object).
+ * Useful when processing individual metric updates.
+ */
+export function calculateBCUForResource(
+  resource: ResourceType,
+  value: number,
+  weights: BCUWeights = DEFAULT_BCU_WEIGHTS
+): number {
+  return value * weights[resource];
+}
+
+// =============================================================================
+// BUDGET ENFORCEMENT
+// =============================================================================
+
+/**
+ * Check BCU budget state for a feature.
+ *
+ * @param currentBCU - Current BCU consumption
+ * @param limitBCU - Budget limit in BCU
+ * @returns Budget state with utilisation info
+ */
+export function checkBCUBudget(currentBCU: number, limitBCU: number): BCUBudgetState {
+  const utilisation = limitBCU > 0 ? currentBCU / limitBCU : 0;
+  return {
+    currentBCU,
+    limitBCU,
+    utilisation,
+    exceeded: currentBCU > limitBCU,
+  };
+}
+
+/**
+ * Convert a USD budget to BCU budget.
+ * Useful for setting feature budgets based on dollar allocations.
+ *
+ * This is an approximation based on the most common resource mix.
+ * For precise conversion, you'd need the expected resource profile.
+ *
+ * @param usdBudget - Budget in USD
+ * @returns Approximate BCU budget
+ */
+export function usdToBCU(usdBudget: number): number {
+  // Approximation: assume average workload is 60% requests, 20% D1, 10% KV, 10% AI
+  // Average BCU per dollar ~= $1 buys approximately 10000 BCU in this mix
+  return usdBudget * 10000;
+}
+
+/**
+ * Convert BCU to approximate USD.
+ * Inverse of usdToBCU for reporting.
+ */
+export function bcuToUSD(bcu: number): number {
+  return bcu / 10000;
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Get human-readable description of dominant resource.
+ */
+export function describeDominantResource(resource: ResourceType | null): string {
+  if (!resource) return 'none';
+
+  const descriptions: Record<ResourceType, string> = {
+    aiNeurons: 'AI compute (neurons)',
+    aiRequests: 'AI API calls',
+    d1Writes: 'D1 writes (legacy)',
+    d1Reads: 'D1 reads (legacy)',
+    d1RowsWritten: 'D1 rows written',
+    d1RowsRead: 'D1 rows read',
+    kvWrites: 'KV writes',
+    kvReads: 'KV reads',
+    kvDeletes: 'KV deletes',
+    kvLists: 'KV list operations',
+    r2ClassA: 'R2 Class A ops',
+    r2ClassB: 'R2 Class B ops',
+    doRequests: 'Durable Object requests',
+    doGbSeconds: 'Durable Object compute',
+    queueMessages: 'Queue messages',
+    vectorizeQueries: 'Vectorize queries',
+    vectorizeInserts: 'Vectorize inserts',
+    workflowInvocations: 'Workflow invocations',
+    requests: 'HTTP requests',
+    cpuMs: 'CPU time',
+  };
+
+  return descriptions[resource] || resource;
+}
+
+/**
+ * Format BCU result for logging.
+ */
+export function formatBCUResult(result: BCUResult): string {
+  const dominant = result.dominantResource
+    ? `${describeDominantResource(result.dominantResource)} (${result.dominantPercentage.toFixed(1)}%)`
+    : 'none';
+  return `BCU: ${result.total.toFixed(2)}, dominant: ${dominant}`;
+}
+
+/**
+ * Get resource-specific BCU breakdown for detailed reporting.
+ */
+export function getTopContributors(
+  result: BCUResult,
+  topN: number = 3
+): { resource: ResourceType; bcu: number; percentage: number }[] {
+  const entries = Object.entries(result.breakdown) as [ResourceType, number][];
+  return entries
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, topN)
+    .map(([resource, bcu]) => ({
+      resource,
+      bcu,
+      percentage: result.total > 0 ? (bcu / result.total) * 100 : 0,
+    }));
+}
+
+/**
+ * Combine BCU results from multiple metrics.
+ */
+export function combineBCUResults(results: BCUResult[]): BCUResult {
+  const combined: Partial<Record<ResourceType, number>> = {};
+  let total = 0;
+
+  for (const result of results) {
+    for (const [resource, value] of Object.entries(result.breakdown) as [ResourceType, number][]) {
+      combined[resource] = (combined[resource] || 0) + value;
+    }
+    total += result.total;
+  }
+
+  // Find dominant resource in combined
+  let maxContribution = 0;
+  let dominantResource: ResourceType | null = null;
+  for (const [resource, value] of Object.entries(combined) as [ResourceType, number][]) {
+    if (value > maxContribution) {
+      maxContribution = value;
+      dominantResource = resource;
+    }
+  }
+
+  return {
+    total,
+    breakdown: combined,
+    dominantResource,
+    dominantPercentage: total > 0 ? (maxContribution / total) * 100 : 0,
+  };
+}