runward 0.6.0

package/templates/rules/routing-smart-complexity.md

@@ -0,0 +1,131 @@
+---
+title: Smart Routing by Complexity
+impact: HIGH
+impactDescription: Order-of-magnitude latency cut on simple requests and a substantial cost reduction through intelligent model selection, measured on a reference system — recalibrate on your traffic
+tags: [routing, llm, cost-optimization]
+---
+
+## Smart Routing by Complexity
+
+Route requests to the appropriate model based on complexity. Not every request needs Deep.
+
+**The Problem:**
+
+Everything goes to the same model, even "Hello" or "OK thanks".
+
+**Routing Pattern:**
+
+```
+User message
+        ↓
+detectWithRegex() → confidence ≥ 0.6?
+    ├─ YES → Use this result (~1ms, $0)
+    └─ NO → detectWithFastModel() (~100ms, ~$0.0003)
+              ↓
+        ComplexityLevel
+              ↓
+    ┌─────────┴─────────┐
+    │   Smart Routing   │
+    └─────────┬─────────┘
+              ↓
+    casual   → Fast      ($0.005/req)   ~25%
+    task     → Balanced     ($0.025/req)   ~45%
+    planning → Balanced     ($0.025/req)   ~20%
+    deep     → Deep       ($0.10/req)    ~10%
+```
+
+**Incorrect:**
+
+```typescript
+// Same model for everything
+const response = await model.complete({
+  model: 'mid-tier-model',  // BAD: Always Balanced
+  messages,
+});
+```
+
+**Correct:**
+
+```typescript
+type ComplexityLevel = 'casual' | 'task' | 'planning' | 'deep';
+
+interface ComplexityResult {
+  level: ComplexityLevel;
+  confidence: number;
+}
+
+// Step 1: Try regex first (free, instant)
+function detectWithRegex(message: string): ComplexityResult | null {
+  // Casual patterns must match the ENTIRE (short) message, anchored on
+  // both ends. A prefix match like /^hey/i would classify
+  // "hey, can you redesign our auth architecture?" as casual and
+  // short-circuit it to the cheapest model.
+  const MAX_CASUAL_LENGTH = 25;
+  const casualPatterns = [
+    /^(hi|hello|hey|thanks|thank you|ok|okay|bye)[\s!.]*$/i,
+    /^(yes|no|sure|got it)[\s!.]*$/i,
+  ];
+
+  const deepPatterns = [
+    /compare.*and.*analyze/i,
+    /design.*architecture/i,
+    /evaluate.*strategy/i,
+  ];
+
+  // Test deep patterns FIRST: misrouting a deep request to a small
+  // model costs far more than misrouting a greeting to a big one.
+  for (const pattern of deepPatterns) {
+    if (pattern.test(message)) {
+      return { level: 'deep', confidence: 0.7 };
+    }
+  }
+
+  const trimmed = message.trim();
+  if (trimmed.length <= MAX_CASUAL_LENGTH) {
+    for (const pattern of casualPatterns) {
+      if (pattern.test(trimmed)) {
+        return { level: 'casual', confidence: 0.8 };
+      }
+    }
+  }
+
+  return null;  // Fallback to LLM classification
+}
+
+// Step 2: Use Fast for uncertain cases
+async function detectComplexity(message: string): Promise<ComplexityResult> {
+  const regexResult = detectWithRegex(message);
+  if (regexResult && regexResult.confidence >= 0.6) {
+    return regexResult;
+  }
+
+  // Use Fast for classification (~$0.0003)
+  return await classifyWithFastModel(message);
+}
+
+// Step 3: Select model. In doubt, upgrade: a small model on a deep
+// question costs more in retries and bad answers than the price gap.
+function selectModel(result: ComplexityResult): string {
+  if (result.confidence < 0.6) {
+    return upgradeModel(result.level);  // Safety upgrade (see Confidence Upgrade rule)
+  }
+
+  switch (result.level) {
+    case 'casual': return 'small-fast-model';
+    case 'task':
+    case 'planning': return 'mid-tier-model';
+    case 'deep': return 'top-tier-model';
+  }
+}
+```
+
+**Expected Distribution:**
+
+| Level | Model | % Traffic | Cost |
+|-------|-------|-----------|------|
+| casual | Fast | 25% | $0.005 |
+| task | Balanced | 45% | $0.025 |
+| planning | Balanced | 20% | $0.025 |
+| deep | Deep | 10% | $0.10 |
+
+**Weighted average: ~$0.028/request** (vs $0.06 if all Balanced)

package/templates/rules/scaling-db-connection-pooling.md

@@ -0,0 +1,121 @@
+---
+title: Database Connection Pooling
+impact: MEDIUM
+impactDescription: Prevents connection exhaustion under load
+tags: [scaling, database, performance, configuration]
+---
+
+## Database Connection Pooling
+
+Configure connection pools to prevent exhaustion under load. Each instance needs its own pool.
+
+**The Problem:**
+
+Without pooling:
+- Each request opens a new connection
+- Connections are slow to establish
+- Database has limited connections
+- Under load: "too many connections" errors
+
+**Incorrect:**
+
+```typescript
+// New connection per request
+async function query(sql: string) {
+  const client = new Client(process.env.DATABASE_URL);
+  await client.connect();  // BAD: Slow, wasteful
+  const result = await client.query(sql);
+  await client.end();
+  return result;
+}
+```
+
+**Correct:**
+
+```typescript
+// PostgreSQL with pg-pool
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,                    // Max connections per instance
+  idleTimeoutMillis: 30000,   // Close idle connections after 30s
+  connectionTimeoutMillis: 5000, // Fail if can't connect in 5s
+});
+
+// Reuse connections from pool
+async function query<T>(sql: string, params?: unknown[]): Promise<T[]> {
+  const client = await pool.connect();
+  try {
+    const result = await client.query(sql, params);
+    return result.rows;
+  } finally {
+    client.release();  // Return to pool, don't close
+  }
+}
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await pool.end();
+});
+```
+
+**Pool Sizing Formula:**
+
+```
+connections_per_instance = (db_max_connections - reserved) / num_instances
+
+Example:
+- PostgreSQL max_connections: 100
+- Reserved for admin: 5
+- Instances: 4
+- Pool size per instance: (100 - 5) / 4 = ~23
+```
+
+**Prisma Configuration:**
+
+```typescript
+// prisma/schema.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// Connection pool via URL
+// DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=20&pool_timeout=10"
+```
+
+**Drizzle Configuration:**
+
+```typescript
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+});
+
+export const db = drizzle(pool);
+```
+
+**Monitoring:**
+
+```typescript
+// Log pool stats periodically
+setInterval(() => {
+  console.info('[DB] Pool stats', {
+    total: pool.totalCount,
+    idle: pool.idleCount,
+    waiting: pool.waitingCount,
+  });
+}, 60000);
+```
+
+**Common Issues:**
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "too many connections" | Pool too large | Reduce max per instance |
+| Slow queries | Pool exhausted | Increase max or optimize queries |
+| Connection timeout | Pool full, queries slow | Add connection_timeout, optimize |

package/templates/rules/scaling-distributed-rate-limiting.md

@@ -0,0 +1,141 @@
+---
+title: Distributed Rate Limiting
+impact: HIGH
+impactDescription: Enables consistent rate limiting across multiple instances
+tags: [scaling, rate-limiting, redis, architecture]
+---
+
+## Distributed Rate Limiting
+
+In-memory rate limiting fails with multiple instances. Use Redis for consistent limits.
+
+**The Problem:**
+
+With 3 instances and 100 req/min limit:
+- User can make 100 requests to each instance
+- Actual rate: 300 req/min (3x limit bypass)
+
+**Incorrect:**
+
+```typescript
+// In-memory - each instance has its own counter
+const rateLimits = new Map<string, { count: number; resetAt: number }>();
+
+function checkRateLimit(userId: string): boolean {
+  const record = rateLimits.get(userId);
+  // BAD: Only counts requests to this instance
+}
+```
+
+**Correct:**
+
+```typescript
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+interface RateLimitConfig {
+  windowMs: number;    // Time window in ms
+  maxRequests: number; // Max requests per window
+}
+
+const defaultConfig: RateLimitConfig = {
+  windowMs: 60_000,    // 1 minute
+  maxRequests: 100,
+};
+
+// INCR and PEXPIRE must be atomic. If the process crashes between the
+// INCR and a separate PEXPIRE call, the key survives with no TTL and the
+// counter never resets: that user is rate-limited forever. A Lua script
+// runs both as one atomic operation. (Alternative without Lua:
+// `SET key 0 PX windowMs NX` to create the key with its TTL, then INCR.)
+const RATE_LIMIT_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+end
+return {count, redis.call('PTTL', KEYS[1])}
+`;
+
+async function checkRateLimit(
+  key: string,
+  config = defaultConfig
+): Promise<{ allowed: boolean; remaining: number; resetIn: number }> {
+  const now = Date.now();
+  const windowKey = `ratelimit:${key}:${Math.floor(now / config.windowMs)}`;
+
+  const [count, ttl] = (await redis.eval(
+    RATE_LIMIT_SCRIPT,
+    1,
+    windowKey,
+    config.windowMs
+  )) as [number, number];
+
+  const remaining = Math.max(0, config.maxRequests - count);
+  const resetIn = ttl > 0 ? ttl : config.windowMs;
+
+  return {
+    allowed: count <= config.maxRequests,
+    remaining,
+    resetIn,
+  };
+}
+
+// Middleware usage
+async function rateLimitMiddleware(req: Request, res: Response, next: NextFunction) {
+  const userId = req.user?.id || req.ip;
+  const result = await checkRateLimit(`user:${userId}`);
+
+  // Set standard rate limit headers
+  res.setHeader('X-RateLimit-Limit', config.maxRequests);
+  res.setHeader('X-RateLimit-Remaining', result.remaining);
+  res.setHeader('X-RateLimit-Reset', Math.ceil(Date.now() / 1000 + result.resetIn / 1000));
+
+  if (!result.allowed) {
+    res.setHeader('Retry-After', Math.ceil(result.resetIn / 1000));
+    return res.status(429).json({ error: 'Too Many Requests' });
+  }
+
+  next();
+}
+```
+
+**Fixed-window caveat — 2x burst at the boundary:**
+
+The fixed-window counter above lets a client burst up to **2x the limit** across a window boundary: 100 requests in the last second of one window plus 100 in the first second of the next is 200 requests in two seconds, all allowed. If your downstream cannot absorb that burst, use the sliding-window variant below.
+
+**Sliding Window Algorithm:**
+
+For more precise rate limiting (no boundary burst), use sliding window:
+
+```typescript
+async function slidingWindowRateLimit(
+  key: string,
+  windowMs: number,
+  maxRequests: number
+): Promise<boolean> {
+  const now = Date.now();
+  const windowStart = now - windowMs;
+
+  // Remove old entries and add new one atomically
+  const multi = redis.multi();
+  multi.zremrangebyscore(key, 0, windowStart);
+  multi.zadd(key, now, `${now}-${Math.random()}`);
+  multi.zcard(key);
+  multi.expire(key, Math.ceil(windowMs / 1000));
+
+  const results = await multi.exec();
+  const count = results![2][1] as number;
+
+  return count <= maxRequests;
+}
+```
+
+**Rate Limit Tiers:**
+
+| Tier | Limit | Use Case |
+|------|-------|----------|
+| Anonymous | 10/min | Public endpoints |
+| Free | 60/min | Authenticated users |
+| Pro | 300/min | Paid users |
+| API | 1000/min | API keys |

package/templates/rules/scaling-state-externalization.md

@@ -0,0 +1,84 @@
+---
+title: Externalize State for Scaling
+impact: CRITICAL
+impactDescription: Enables horizontal scaling by removing in-process state dependencies
+tags: [scaling, architecture, redis, state-management]
+---
+
+## Externalize State for Scaling
+
+> **Scaling ≠ adding instances. Scaling = externalized state.**
+
+In-memory state prevents horizontal scaling. Each instance has its own copy, leading to inconsistencies.
+
+**Incorrect:**
+
+```typescript
+// In-memory state - works for single instance only
+const rateLimitStore = new Map<string, RateLimitData>();
+const sessionStore = new Map<string, SessionData>();
+const idempotencyStore = new Map<string, IdempotencyRecord>();
+
+function rateLimit(userId: string): boolean {
+  const data = rateLimitStore.get(userId);  // BAD: Instance-local
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+// External state - works for any number of instances
+import { Redis } from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+async function rateLimit(userId: string): Promise<boolean> {
+  const key = `ratelimit:${userId}`;
+  const current = await redis.incr(key);
+
+  if (current === 1) {
+    await redis.expire(key, 60);  // 1 minute window
+  }
+
+  return current <= 100;  // 100 requests per minute
+}
+```
+
+**State Migration Table:**
+
+| Component | Single Instance | Multi Instance |
+|-----------|-----------------|----------------|
+| Token cache | `Map<>` OK | Redis with TTL |
+| Rate limiting | In-memory OK | Redis distributed |
+| Session state | In-memory OK | Redis or a shared store |
+| Locks | Not needed | Redis distributed lock |
+| Idempotency | `Map<>` OK | Redis with TTL |
+
+**Files to Audit:**
+
+```typescript
+// Common patterns to find and migrate
+middleware.ts      rateLimitStore: Map<string, RateLimitData>
+middleware.ts      idempotencyStore: Map<string, IdempotencyRecord>
+service.ts         sessionStore: Map<string, SessionData>
+import.ts          importProgress: Map<string, ImportProgressRecord>
+export.ts          exportProgress: Map<string, ExportProgressRecord>
+```
+
+**Scaling Checklist:**
+
+```
+PRE-REQUISITES
+├── [ ] In-memory Maps identified
+├── [ ] Rate limiting ready for Redis
+├── [ ] DB connection pooling configured
+├── [ ] Multi-tenant isolation OK
+└── [ ] Healthcheck + readiness probe
+
+MIGRATION (when multi-instance needed)
+├── [ ] Rate limiting → Redis
+├── [ ] Session state → Redis
+├── [ ] Distributed locks → Redis
+└── [ ] Load tests validated
+```

package/templates/rules/security-prompt-injection.md

@@ -0,0 +1,63 @@
+---
+title: Untrusted Input, Prompt Injection and the Lethal Trifecta
+impact: CRITICAL
+impactDescription: Treats prompt injection as a first-rank, structural threat constrained by architecture rather than detected by heuristics
+tags: [security, llm, injection, trifecta, untrusted-input]
+---
+
+## Untrusted Input, Prompt Injection and the Lethal Trifecta
+
+> **Everything observed through a tool is data, not instructions.** Web pages, documents, retrieved memories, tool results, file contents: none of it carries authority to act.
+
+Prompt injection is the first-rank threat of an agentic system: hostile instructions slipped into the input. The direct form comes from the user; the indirect, more pernicious form hides in retrieved content (a page, a document, a memory) and fires when the model ingests it. It is therefore intrinsic to any memory or retrieval. You do not reliably *detect* it. You *constrain* it by architecture.
+
+**The lethal trifecta.** The worst case is three properties meeting on one unguarded path:
+
+1. access to private data,
+2. ingestion of untrusted content,
+3. a means of communication to the outside.
+
+Remove any one of the three and the path is defused.
+
+**Operational rule, scoped to the context window:** while untrusted content is present in the context, allow only two of those three properties at once. If all three are genuinely needed, the action does not auto-execute: it requires human approval.
+
+**Incorrect:**
+
+```typescript
+// Untrusted page text flows straight into a tool that can exfiltrate.
+const page = await fetch(url);                 // untrusted content
+const data = await db.readPrivate(userId);     // private data
+await sendEmail(extractRecipient(page), data); // BAD: trifecta: page chose the recipient
+```
+
+**Correct:**
+
+```typescript
+// Break the trifecta structurally: the recipient is only ever accepted
+// from the user's request field. There is no code path that extracts a
+// recipient from fetched content, so provenance is established by
+// construction — not by detecting where a value "came from" after the fact.
+const page = await fetch(url);              // untrusted content: data only
+const data = await db.readPrivate(userId);
+await sendEmail(request.recipient, data);   // recipient: user request field, nothing else
+
+// If the workflow genuinely needs a recipient found in observed content,
+// that action does not auto-execute: it is routed to human approval.
+await requestHumanApproval({ action: 'sendEmail', to: candidateFromPage, payload: data });
+```
+
+**Constrain, do not detect:**
+
+- **Least privilege.** Each tool gets the narrowest scope; a third-party connector is untrusted input.
+- **Approval on the action.** Human approval is anchored in the tool's contract and enforced by infrastructure, not by the prompt.
+- **Suspend, do not block.** A sensitive action serialises the agent's state and rehydrates it on the human decision (fail-closed without freezing the process); low-urgency approvals are batched in a prioritised queue.
+- **Separate the untrusted.** Keep untrusted content out of the same path as private data and an outbound channel.
+
+**Why this is structural, not behavioural:** a guard you can argue the model out of is not a guard. Approval anchored in the tool contract, least privilege enforced by infrastructure, and a broken trifecta hold regardless of what the injected text says.
+
+**Checklist:**
+
+- [ ] Observed content is treated as data; it never authorises an action.
+- [ ] No path holds all three trifecta properties while untrusted content is in context.
+- [ ] Sensitive actions require approval anchored in the tool contract.
+- [ ] Approval suspends-and-rehydrates; it does not freeze the process.

package/templates/rules/state-event-sourcing.md

@@ -0,0 +1,66 @@
+---
+title: State as an Immutable Journal (Event Sourcing, Replay, Provenance)
+impact: HIGH
+impactDescription: Makes the agent a stateless reducer over an external, replayable journal, so truth, audit and recovery are structural rather than bolted on
+tags: [state, event-sourcing, replay, provenance, memory]
+---
+
+## State as an Immutable Journal
+
+> **The agent is a stateless reducer. State lives outside, in three layers.**
+
+An agent with hidden in-process state cannot be replayed, audited, or scaled. Keep the agent stateless and externalise state into three distinct layers, each with one job:
+
+1. **Immutable interaction journal** - the source of truth. Append-only, never edited. It is what you audit and what you replay. Every consequential step is an event appended here.
+2. **Derived working view** - the memory that forgets. A projection of the journal, trimmed and scored for relevance, rebuilt from the journal at any time (see *Memory Scoring*). It is a cache, not a source.
+3. **Prompt provenance** - the reconciler. For each inference, the fingerprint of what was actually injected into the model, so you can replay exactly what the model saw even after the working view has moved on.
+
+**Incorrect:**
+
+```typescript
+// Hidden mutable state in the agent. Not replayable, not auditable.
+class Agent {
+  private history: Msg[] = [];          // BAD: in-process truth
+  handle(input: string) {
+    this.history.push({ role: "user", text: input });
+    // ... mutate more fields the journal never sees
+  }
+}
+```
+
+**Correct:**
+
+```typescript
+// Truth is the journal. The agent folds events into a view, then appends new ones.
+// Appends carry an expected version (optimistic concurrency control): if another
+// writer appended in the meantime, the append fails and the caller re-reads and
+// retries, instead of two writers silently interleaving into the same run.
+async function handle(runId: string, input: Event): Promise<Result> {
+  const events = await journal.read(runId);
+  const version = events.length;                   // version seen at read time
+  await journal.append(runId, [input], { expectedVersion: version });
+  const view = project([...events, input]);        // derived, rebuildable
+  const result = await reducer(view);              // agent is a pure fold over the view
+  await journal.append(runId, result.events, {     // consequences are events too
+    expectedVersion: version + 1,
+  });
+  return result;
+}
+
+// Replay is just folding the journal again, deterministically.
+const replayed = project(await journal.read(runId));
+```
+
+**Why this matters:**
+
+- **Audit and recovery**: the journal answers "what happened, exactly?" and lets you resume a run from any point (see the recovery runbook).
+- **Provenance under injection**: keeping what was injected lets you investigate a bad output even after the working memory forgot it; it also pairs with the prompt provenance the single middleware records.
+- **Scaling**: because the agent holds no hidden state, externalising the journal and the working view to a shared store is the structural precondition for running many instances — not the whole bill. The real costs come with it: **concurrency control** on appends (expected version, retry on conflict), **idempotence** of event handling (a retried append or redelivered event must not double its effect), and **causal ordering** across writers (events from concurrent instances need an order the projection can trust). Pay these on a trigger, in full knowledge, not by default.
+
+**Checklist:**
+
+- [ ] The agent holds no hidden mutable state; it folds over an external view.
+- [ ] The interaction journal is append-only and is the single source of truth.
+- [ ] Appends carry an expected version; a conflict re-reads and retries, never overwrites.
+- [ ] The working view is a projection, rebuildable from the journal.
+- [ ] Prompt provenance is recorded per inference for replay and audit.