runward 0.6.0

package/templates/rules/hexa-typescript-native.md

@@ -0,0 +1,80 @@
+---
+title: A Thin Model Abstraction You Own (Not a Heavy Chain Framework)
+impact: HIGH
+impactDescription: Reduces token overhead, improves debuggability, removes volatile dependencies by keeping a light abstraction you control instead of a heavy framework
+tags: [architecture, typescript, llm, frameworks]
+---
+
+## A Thin Model Abstraction You Own
+
+Heavy chain or agent frameworks add overhead that is rarely justified. Keep a light abstraction you control over the model, and call the provider through a direct SDK behind your own port.
+
+**Why avoid a heavy chain framework as the default:**
+
+1. **Token overhead** - the framework's internal prompts add to your cost.
+2. **Abstraction leaks** - you cannot optimise what you cannot see through.
+3. **Volatile ecosystem** - frequent breaking changes in fast-moving framework code.
+4. **Debug difficulty** - stack traces run through framework internals.
+5. **Unnecessary complexity** - most applications do not need generic chains or agents.
+
+**Incorrect (a heavy framework owns your control flow):**
+
+```typescript
+import { ChatModel } from "@chain-framework/core";
+import { HumanMessage, SystemMessage } from "@chain-framework/core/messages";
+import { StringOutputParser } from "@chain-framework/core/output_parsers";
+
+const model = new ChatModel({ modelName: "mid-tier-model" });
+const chain = model.pipe(new StringOutputParser());
+
+const response = await chain.invoke([
+  new SystemMessage(systemPrompt),
+  new HumanMessage(userMessage),
+]);
+// You no longer control the prompt, the caching, or the cost.
+```
+
+**Correct (a direct SDK behind a thin port you own):**
+
+```typescript
+// The adapter imports one provider SDK; the core sees only the port.
+import { ModelSDK } from "@vendor/model-sdk";   // any provider's official SDK
+
+const client = new ModelSDK();
+
+const response = await client.complete({
+  model: "mid-tier-model",
+  maxTokens: 4096,
+  system: [corePrompt, toolsPrompt, dynamicContext],
+  messages: [{ role: "user", content: userMessage }],
+});
+```
+
+**When a framework might still help:**
+
+- Rapid throwaway prototyping.
+- Genuinely complex multi-agent orchestration that you have measured the need for.
+
+**The abstraction you keep is yours:**
+
+```typescript
+// A thin interface you control, in the core. One adapter per provider implements it.
+interface ModelPort {
+  complete(request: CompletionRequest): Promise<CompletionResponse>;
+}
+
+class PrimaryModelAdapter implements ModelPort {
+  // full control over caching, retries, logging, cost attribution
+}
+
+class SecondaryModelAdapter implements ModelPort {
+  // same interface, a different provider, swapped by configuration
+}
+```
+
+**Benefits of the thin, owned abstraction:**
+
+- Full control of caching and cost attribution.
+- Simple debugging (no framework internals in the trace).
+- No framework learning curve or breaking-change treadmill.
+- The type safety and the contract are yours to define.

package/templates/rules/observability-alert-configuration.md

@@ -0,0 +1,160 @@
+---
+title: Alert Configuration
+impact: MEDIUM
+impactDescription: Ensures timely notification of production issues
+tags: [observability, alerting, production]
+---
+
+## Alert Configuration
+
+Configure alerts to catch issues before they impact users.
+
+**Alert Tiers:**
+
+| Tier | Response Time | Examples |
+|------|---------------|----------|
+| P0 - Critical | <15 min | Service down, data loss |
+| P1 - High | <1 hour | Error rate spike, degraded performance |
+| P2 - Medium | <4 hours | Elevated latency, cache degradation |
+| P3 - Low | Next business day | Cost anomaly, capacity warning |
+
+**Recommended Alerts:**
+
+```yaml
+# alerts.yaml
+alerts:
+  # P0 - Critical
+  - name: service_down
+    condition: healthcheck_failures > 3
+    window: 5m
+    severity: critical
+    notify: [pagerduty, slack-critical]
+
+  - name: error_rate_critical
+    condition: error_rate > 10%
+    window: 5m
+    severity: critical
+    notify: [pagerduty, slack-critical]
+
+  # P1 - High
+  - name: error_rate_elevated
+    condition: error_rate > 5%
+    window: 5m
+    severity: high
+    notify: [slack-alerts]
+
+  - name: llm_provider_failing
+    condition: llm_error_rate > 5%
+    window: 5m
+    severity: high
+    notify: [slack-alerts]
+
+  - name: latency_degraded
+    condition: p95_latency > 5000ms
+    window: 10m
+    severity: high
+    notify: [slack-alerts]
+
+  # P2 - Medium
+  - name: cache_hit_low
+    condition: cache_hit_rate < 50%
+    window: 30m
+    severity: medium
+    notify: [slack-engineering]
+
+  - name: db_connections_high
+    condition: db_pool_usage > 80%
+    window: 15m
+    severity: medium
+    notify: [slack-engineering]
+
+  # P3 - Low
+  - name: daily_cost_anomaly
+    condition: daily_cost > 2x avg_daily_cost
+    window: 24h
+    severity: low
+    notify: [email-team]
+
+  - name: disk_space_warning
+    condition: disk_usage > 70%
+    window: 1h
+    severity: low
+    notify: [slack-engineering]
+```
+
+**Implementation with the telemetry sink:**
+
+```typescript
+// Alert configuration in code
+const alertRules = [
+  {
+    name: 'High Error Rate',
+    query: `
+      SELECT count(*) as errors
+      FROM logs
+      WHERE level = 'error'
+      AND timestamp > now() - 5m
+    `,
+    threshold: { errors: 100 },
+    severity: 'high',
+    channels: ['slack-alerts'],
+  },
+  {
+    name: 'LLM Cost Spike',
+    query: `
+      SELECT sum(estimatedCost) as cost
+      FROM llm_metrics
+      WHERE timestamp > now() - 1h
+    `,
+    threshold: { cost: 50 },
+    severity: 'medium',
+    channels: ['slack-engineering'],
+  },
+];
+
+// Alert evaluation
+async function evaluateAlerts() {
+  for (const rule of alertRules) {
+    const result = await telemetry.query(rule.query);
+
+    if (exceedsThreshold(result, rule.threshold)) {
+      await sendAlert({
+        name: rule.name,
+        severity: rule.severity,
+        channels: rule.channels,
+        data: result,
+      });
+    }
+  }
+}
+
+// Run every minute
+cron.schedule('* * * * *', evaluateAlerts);
+```
+
+**Alert Message Format:**
+
+```typescript
+interface AlertMessage {
+  title: string;
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  summary: string;
+  metrics: Record<string, number>;
+  runbook?: string;
+  dashboardUrl?: string;
+}
+
+// Example Slack message
+const message = {
+  title: 'High Error Rate Detected',
+  severity: 'high',
+  summary: 'Error rate exceeded 5% threshold for 5 minutes',
+  metrics: {
+    errorRate: 7.2,
+    errorCount: 156,
+    affectedEndpoints: 3,
+  },
+  runbook: 'https://wiki/runbooks/high-error-rate',
+  dashboardUrl: 'https://grafana/d/errors',
+};
+```

package/templates/rules/observability-llm-metrics.md

@@ -0,0 +1,150 @@
+---
+title: LLM Metrics Tracking
+impact: MEDIUM
+impactDescription: Enables cost monitoring, performance optimization, and anomaly detection
+tags: [observability, llm, metrics, cost]
+---
+
+## LLM Metrics Tracking
+
+Track comprehensive metrics for every LLM call to enable cost control and optimization.
+
+**Essential Metrics:**
+
+```typescript
+interface LLMMetrics {
+  // Request metadata
+  requestId: string;
+  userId: string;
+  model: string;
+  provider: string;
+
+  // Token usage
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+
+  // Performance
+  latencyMs: number;
+  timeToFirstToken?: number;
+
+  // Cost
+  estimatedCost: number;
+
+  // Context
+  complexity: string;
+  cached: boolean;
+  retries: number;
+
+  // Timestamp
+  timestamp: Date;
+}
+```
+
+**Implementation:**
+
+```typescript
+// LLM wrapper with metrics
+async function completeLLM(request: LLMRequest): Promise<LLMResponse> {
+  const start = Date.now();
+  const metrics: Partial<LLMMetrics> = {
+    requestId: request.requestId,
+    userId: request.userId,
+    model: request.model,
+    provider: llmConfig.provider,
+    complexity: request.complexity,
+    timestamp: new Date(),
+    retries: 0,
+  };
+
+  try {
+    const response = await withLLMRetry(
+      () => llmClient.complete(request),
+      { onRetry: () => metrics.retries!++ }
+    );
+
+    // Extract usage
+    metrics.inputTokens = response.usage.input_tokens;
+    metrics.outputTokens = response.usage.output_tokens;
+    metrics.cacheReadTokens = response.usage.cache_read_input_tokens || 0;
+    metrics.cacheWriteTokens = response.usage.cache_creation_input_tokens || 0;
+    metrics.latencyMs = Date.now() - start;
+    metrics.cached = metrics.cacheReadTokens > 0;
+    metrics.estimatedCost = calculateCost(metrics as LLMMetrics);
+
+    // Log metrics
+    logger.info('LLM request completed', metrics);
+
+    // Send to metrics service
+    telemetry.record('llm_request', metrics);
+
+    return response;
+  } catch (error) {
+    logger.error('LLM request failed', {
+      ...metrics,
+      error: error.message,
+      latencyMs: Date.now() - start,
+    });
+    throw error;
+  }
+}
+
+// Cost calculation.
+// Typical cache pricing: reads at ~10% of the input price, writes at
+// ~125% (verify against your provider's price sheet).
+// CAUTION: usage field semantics vary by provider — some exclude cache
+// read/write tokens from input_tokens, others include them. This formula
+// assumes input_tokens EXCLUDES cache tokens; check your provider's
+// usage schema before trusting the numbers, or you will double-count.
+function calculateCost(metrics: LLMMetrics): number {
+  const pricing = MODEL_PRICING[metrics.model];
+
+  return (
+    (metrics.inputTokens * pricing.input +
+      metrics.cacheReadTokens * pricing.input * 0.1 +
+      metrics.cacheWriteTokens * pricing.input * 1.25 +
+      metrics.outputTokens * pricing.output) / 1_000_000
+  );
+}
+```
+
+**Aggregated Metrics:**
+
+```typescript
+// Daily cost aggregation
+interface DailyMetrics {
+  date: string;
+  totalRequests: number;
+  totalCost: number;
+  avgLatency: number;
+  cacheHitRate: number;
+  modelBreakdown: Record<string, { requests: number; cost: number }>;
+  errorRate: number;
+}
+
+async function aggregateDailyMetrics(date: string): Promise<DailyMetrics> {
+  const metrics = await db.llmMetrics.findMany({
+    where: { date: startOfDay(date) },
+  });
+
+  return {
+    date,
+    totalRequests: metrics.length,
+    totalCost: sum(metrics.map(m => m.estimatedCost)),
+    avgLatency: avg(metrics.map(m => m.latencyMs)),
+    cacheHitRate: metrics.filter(m => m.cached).length / metrics.length,
+    modelBreakdown: groupByModel(metrics),
+    errorRate: metrics.filter(m => m.error).length / metrics.length,
+  };
+}
+```
+
+**Alert Thresholds:**
+
+| Metric | Warning | Critical |
+|--------|---------|----------|
+| Cost/day | >$50 | >$100 |
+| Error rate | >2% | >5% |
+| P95 latency | >5s | >10s |
+| Cache hit rate | <50% | <30% |

package/templates/rules/observability-startup-provider-log.md

@@ -0,0 +1,128 @@
+---
+title: Log Providers at Startup
+impact: LOW
+impactDescription: Simplifies debugging by showing configuration at startup
+tags: [observability, configuration, debugging]
+---
+
+## Log Providers at Startup
+
+Always log the detected configuration at application startup for debugging.
+
+**Implementation:**
+
+```typescript
+// src/lib/startup.ts
+import { features } from './features';
+import { llmConfig } from './providers/llm-provider';
+import { embeddingConfig } from './providers/embedding-provider';
+
+export function logStartupConfig() {
+  console.info('═'.repeat(60));
+  console.info('[STARTUP] Application Configuration');
+  console.info('═'.repeat(60));
+
+  console.info('[CONFIG] Deployment mode:', features.mode);
+
+  console.info('[CONFIG] Providers:', {
+    llm: {
+      provider: llmConfig.provider,
+      model: llmConfig.model,
+      // Don't log API keys
+    },
+    embeddings: {
+      provider: embeddingConfig.provider,
+      model: embeddingConfig.model,
+      dimensions: embeddingConfig.dimensions,
+    },
+  });
+
+  console.info('[CONFIG] Features:', {
+    auth: features.auth.provider,
+    search: features.search.enabled ? features.search.provider : 'disabled',
+    memory: features.memory.enabled ? features.memory.provider : 'disabled',
+    realtime: features.realtime.enabled,
+    presence: features.realtime.presence,
+  });
+
+  console.info('[CONFIG] Database:', {
+    postgres: !!process.env.DATABASE_URL,
+    graph: !!process.env.GRAPH_URI,
+    redis: !!process.env.REDIS_URL,
+  });
+
+  console.info('═'.repeat(60));
+}
+
+// Call at startup
+// app.ts or index.ts
+logStartupConfig();
+```
+
+**Output Example:**
+
+```
+════════════════════════════════════════════════════════════
+[STARTUP] Application Configuration
+════════════════════════════════════════════════════════════
+[CONFIG] Deployment mode: full
+[CONFIG] Providers: {
+  llm: { provider: 'configured-provider', model: 'mid-tier-model' },
+  embeddings: { provider: 'configured-provider', model: 'embedding-model', dimensions: 1536 }
+}
+[CONFIG] Features: {
+  auth: 'configured-provider',
+  search: 'web-search',
+  memory: 'configured-provider',
+  realtime: true,
+  realtime: true
+}
+[CONFIG] Database: { postgres: true, graph: true, redis: true }
+════════════════════════════════════════════════════════════
+```
+
+**Environment Validation:**
+
+```typescript
+function validateEnvironment() {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Required
+  if (!process.env.DATABASE_URL) {
+    errors.push('DATABASE_URL is required');
+  }
+
+  // At least one LLM provider
+  const hasLLM = [
+    'MODEL_GATEWAY_URL',
+    'MODEL_PROVIDER',
+    'AWS_ACCESS_KEY_ID',
+    'MODEL_API_KEY',
+    'EMBEDDING_API_KEY',
+  ].some(key => !!process.env[key]);
+
+  if (!hasLLM) {
+    errors.push('No LLM provider configured');
+  }
+
+  // Warnings for missing optional services
+  if (!process.env.REDIS_URL) {
+    warnings.push('REDIS_URL not set - using in-memory state (not scalable)');
+  }
+
+  // Log results
+  if (warnings.length > 0) {
+    console.warn('[STARTUP] Warnings:', warnings);
+  }
+
+  if (errors.length > 0) {
+    console.error('[STARTUP] Configuration errors:', errors);
+    process.exit(1);
+  }
+}
+
+// Run before startup
+validateEnvironment();
+logStartupConfig();
+```

package/templates/rules/observability-structured-json-logs.md

@@ -0,0 +1,138 @@
+---
+title: Structured JSON Logs
+impact: MEDIUM
+impactDescription: Enables log querying, aggregation, and alerting in production
+tags: [observability, logging, production]
+---
+
+## Structured JSON Logs
+
+Use structured JSON logs for queryable, parseable logging in production.
+
+**Incorrect:**
+
+```typescript
+// Unstructured logs - hard to parse and query
+console.log(`User ${userId} created project ${projectId} in ${duration}ms`);
+console.log('Error:', error.message);
+console.log(`Request from ${req.ip} to ${req.path}`);
+```
+
+**Correct:**
+
+```typescript
+// Structured logger
+interface LogEntry {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  timestamp: string;
+  requestId?: string;
+  userId?: string;
+  tenantId?: string;
+  [key: string]: unknown;
+}
+
+class StructuredLogger {
+  private context: Partial<LogEntry> = {};
+
+  child(context: Partial<LogEntry>): StructuredLogger {
+    const child = new StructuredLogger();
+    child.context = { ...this.context, ...context };
+    return child;
+  }
+
+  private log(level: LogEntry['level'], message: string, data: object = {}) {
+    const entry: LogEntry = {
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      ...this.context,
+      ...data,
+    };
+
+    // Redact sensitive fields
+    const redacted = this.redactSensitive(entry);
+
+    console.log(JSON.stringify(redacted));
+  }
+
+  private redactSensitive(entry: LogEntry): LogEntry {
+    const sensitiveKeys = ['password', 'token', 'apiKey', 'secret', 'authorization'];
+    const redacted = { ...entry };
+
+    for (const key of Object.keys(redacted)) {
+      if (sensitiveKeys.some(s => key.toLowerCase().includes(s))) {
+        redacted[key] = '[REDACTED]';
+      }
+    }
+
+    return redacted;
+  }
+
+  debug(message: string, data?: object) { this.log('debug', message, data); }
+  info(message: string, data?: object) { this.log('info', message, data); }
+  warn(message: string, data?: object) { this.log('warn', message, data); }
+  error(message: string, data?: object) { this.log('error', message, data); }
+}
+
+export const logger = new StructuredLogger();
+
+// Usage
+logger.info('Project created', {
+  userId: 'usr_123',
+  projectId: 'prj_456',
+  duration: 45,
+});
+
+// Output:
+// {"level":"info","message":"Project created","timestamp":"2025-01-24T10:30:00.000Z","userId":"usr_123","projectId":"prj_456","duration":45}
+```
+
+**Request Context Logger:**
+
+```typescript
+// Middleware to add request context
+function requestLoggerMiddleware(req: Request, res: Response, next: NextFunction) {
+  const requestId = req.headers['x-request-id'] as string || crypto.randomUUID();
+  const requestLogger = logger.child({
+    requestId,
+    method: req.method,
+    path: req.path,
+    userId: req.user?.id,
+    tenantId: req.user?.tenantId,
+  });
+
+  req.logger = requestLogger;
+
+  // Log request start
+  requestLogger.info('Request started');
+
+  // Log request end
+  const start = Date.now();
+  res.on('finish', () => {
+    requestLogger.info('Request completed', {
+      status: res.statusCode,
+      duration: Date.now() - start,
+    });
+  });
+
+  next();
+}
+```
+
+**Log Query Examples (the telemetry sink/Datadog):**
+
+```sql
+-- Find slow LLM requests
+SELECT * FROM logs
+WHERE message = 'LLM request completed'
+AND duration > 5000
+ORDER BY timestamp DESC
+
+-- Error rate by endpoint
+SELECT path, COUNT(*) as errors
+FROM logs
+WHERE level = 'error'
+GROUP BY path
+ORDER BY errors DESC
+```