@directive-run/knowledge 0.2.0

package/examples/provider-routing.ts

@@ -0,0 +1,403 @@
+// Example: provider-routing
+// Source: examples/provider-routing/src/main.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * Smart Provider Router — Constraint-Based Provider Routing & Fallback
+ *
+ * 3 mock providers (OpenAI, Anthropic, Ollama). Constraint router selects based
+ * on cost, error rates, circuit state. Provider fallback chain.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import {
+  type CircuitState,
+  createCircuitBreaker,
+  devtoolsPlugin,
+} from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ProviderStats {
+  name: string;
+  callCount: number;
+  errorCount: number;
+  totalCost: number;
+  avgLatencyMs: number;
+  circuitState: CircuitState;
+}
+
+interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type: "route" | "error" | "fallback" | "circuit" | "info" | "success";
+}
+
+// ============================================================================
+// Mock Providers
+// ============================================================================
+
+const PROVIDERS = {
+  openai: { name: "OpenAI", costPer1k: 0.03, baseLatency: 200 },
+  anthropic: { name: "Anthropic", costPer1k: 0.025, baseLatency: 250 },
+  ollama: { name: "Ollama", costPer1k: 0.001, baseLatency: 400 },
+};
+
+const providerErrors: Record<string, boolean> = {
+  openai: false,
+  anthropic: false,
+  ollama: false,
+};
+
+const circuitBreakers = {
+  openai: createCircuitBreaker({
+    name: "openai",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) =>
+  }),
+  anthropic: createCircuitBreaker({
+    name: "anthropic",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) =>
+  }),
+  ollama: createCircuitBreaker({
+    name: "ollama",
+    failureThreshold: 3,
+    recoveryTimeMs: 5000,
+    halfOpenMaxRequests: 2,
+    onStateChange: (from, to) =>
+  }),
+};
+
+// ============================================================================
+// Timeline
+// ============================================================================
+
+const timeline: TimelineEntry[] = [];
+
+function addTimeline(
+  event: string,
+  detail: string,
+  type: TimelineEntry["type"],
+) {
+  timeline.unshift({ time: Date.now(), event, detail, type });
+  if (timeline.length > 50) {
+    timeline.length = 50;
+  }
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const schema = {
+  facts: {
+    openaiStats: t.object<ProviderStats>(),
+    anthropicStats: t.object<ProviderStats>(),
+    ollamaStats: t.object<ProviderStats>(),
+    budgetRemaining: t.number(),
+    budgetTotal: t.number(),
+    preferCheapest: t.boolean(),
+    lastProvider: t.string(),
+    totalRequests: t.number(),
+    lastError: t.string(),
+  },
+  derivations: {
+    openaiCircuit: t.string<CircuitState>(),
+    anthropicCircuit: t.string<CircuitState>(),
+    ollamaCircuit: t.string<CircuitState>(),
+    cheapestAvailable: t.string(),
+    allDown: t.boolean(),
+  },
+  events: {
+    toggleProviderError: { provider: t.string() },
+    setBudget: { value: t.number() },
+    togglePreferCheapest: {},
+    resetStats: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+function defaultStats(name: string): ProviderStats {
+  return {
+    name,
+    callCount: 0,
+    errorCount: 0,
+    totalCost: 0,
+    avgLatencyMs: 0,
+    circuitState: "CLOSED",
+  };
+}
+
+const routerModule = createModule("router", {
+  schema,
+
+  init: (facts) => {
+    facts.openaiStats = defaultStats("OpenAI");
+    facts.anthropicStats = defaultStats("Anthropic");
+    facts.ollamaStats = defaultStats("Ollama");
+    facts.budgetRemaining = 1.0;
+    facts.budgetTotal = 1.0;
+    facts.preferCheapest = false;
+    facts.lastProvider = "";
+    facts.totalRequests = 0;
+    facts.lastError = "";
+  },
+
+  derive: {
+    openaiCircuit: () => circuitBreakers.openai.getState(),
+    anthropicCircuit: () => circuitBreakers.anthropic.getState(),
+    ollamaCircuit: () => circuitBreakers.ollama.getState(),
+    cheapestAvailable: () => {
+      const available: { name: string; cost: number }[] = [];
+      for (const [id, config] of Object.entries(PROVIDERS)) {
+        const breaker = circuitBreakers[id as keyof typeof circuitBreakers];
+        if (breaker.isAllowed()) {
+          available.push({ name: id, cost: config.costPer1k });
+        }
+      }
+      available.sort((a, b) => a.cost - b.cost);
+
+      return available.length > 0 ? available[0]!.name : "none";
+    },
+    allDown: () =>
+      !circuitBreakers.openai.isAllowed() &&
+      !circuitBreakers.anthropic.isAllowed() &&
+      !circuitBreakers.ollama.isAllowed(),
+  },
+
+  events: {
+    toggleProviderError: (_facts, { provider }) => {
+      providerErrors[provider] = !providerErrors[provider];
+    },
+    setBudget: (facts, { value }) => {
+      facts.budgetRemaining = value;
+      facts.budgetTotal = value;
+    },
+    togglePreferCheapest: (facts) => {
+      facts.preferCheapest = !facts.preferCheapest;
+    },
+    resetStats: (facts) => {
+      facts.openaiStats = defaultStats("OpenAI");
+      facts.anthropicStats = defaultStats("Anthropic");
+      facts.ollamaStats = defaultStats("Ollama");
+      facts.budgetRemaining = facts.budgetTotal;
+      facts.lastProvider = "";
+      facts.totalRequests = 0;
+      facts.lastError = "";
+      providerErrors.openai = false;
+      providerErrors.anthropic = false;
+      providerErrors.ollama = false;
+      circuitBreakers.openai.reset();
+      circuitBreakers.anthropic.reset();
+      circuitBreakers.ollama.reset();
+      timeline.length = 0;
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+const system = createSystem({
+  module: routerModule,
+  debug: { runHistory: true },
+  plugins: [devtoolsPlugin({ name: "provider-routing" })],
+});
+system.start();
+
+// ============================================================================
+// Routing Logic
+// ============================================================================
+
+function selectProvider(): string | null {
+  const budget = system.facts.budgetRemaining as number;
+  const preferCheapest = system.facts.preferCheapest as boolean;
+
+  // Collect available providers (circuit breaker allows + within budget)
+  const available: { id: string; cost: number }[] = [];
+  for (const [id, config] of Object.entries(PROVIDERS)) {
+    const breaker = circuitBreakers[id as keyof typeof circuitBreakers];
+    if (breaker.isAllowed() && budget >= config.costPer1k) {
+      available.push({ id, cost: config.costPer1k });
+    }
+  }
+
+  if (available.length === 0) {
+    return null;
+  }
+
+  if (preferCheapest) {
+    available.sort((a, b) => a.cost - b.cost);
+
+    return available[0]!.id;
+  }
+
+  // Default: prefer openai > anthropic > ollama
+  const priority = ["openai", "anthropic", "ollama"];
+  for (const id of priority) {
+    if (available.find((a) => a.id === id)) {
+      return id;
+    }
+  }
+
+  return available[0]!.id;
+}
+
+async function executeProvider(providerId: string): Promise<boolean> {
+  const breaker = circuitBreakers[providerId as keyof typeof circuitBreakers];
+  const config = PROVIDERS[providerId as keyof typeof PROVIDERS]!;
+  const statsKey = `${providerId}Stats` as
+    | "openaiStats"
+    | "anthropicStats"
+    | "ollamaStats";
+
+  try {
+    await breaker.execute(async () => {
+      await new Promise((resolve) =>
+        setTimeout(resolve, config.baseLatency + Math.random() * 100),
+      );
+
+      if (providerErrors[providerId]) {
+        throw new Error(`${config.name}: simulated error`);
+      }
+    });
+
+    const stats = system.facts[statsKey] as ProviderStats;
+    const cost = config.costPer1k;
+    const latency = config.baseLatency + Math.random() * 100;
+    system.facts[statsKey] = {
+      ...stats,
+      callCount: stats.callCount + 1,
+      totalCost: Math.round((stats.totalCost + cost) * 1000) / 1000,
+      avgLatencyMs: Math.round(
+        (stats.avgLatencyMs * stats.callCount + latency) /
+          (stats.callCount + 1),
+      ),
+      circuitState: breaker.getState(),
+    };
+    system.facts.budgetRemaining =
+      Math.round(((system.facts.budgetRemaining as number) - cost) * 1000) /
+      1000;
+    system.facts.lastError = "";
+
+    return true;
+  } catch (err) {
+    const stats = system.facts[statsKey] as ProviderStats;
+    system.facts[statsKey] = {
+      ...stats,
+      errorCount: stats.errorCount + 1,
+      circuitState: breaker.getState(),
+    };
+    system.facts.lastError = err instanceof Error ? err.message : String(err);
+
+    return false;
+  }
+}
+
+async function sendRequest() {
+  system.facts.totalRequests = (system.facts.totalRequests as number) + 1;
+
+  const providerId = selectProvider();
+  if (!providerId) {
+    system.facts.lastError = "All providers unavailable or over budget";
+
+    return;
+  }
+
+  system.facts.lastProvider = providerId;
+
+  const success = await executeProvider(providerId);
+  if (success) {
+    return;
+  }
+
+  // Primary failed — try fallback
+  const fallbackId = selectProvider();
+  if (fallbackId && fallbackId !== providerId) {
+    system.facts.lastProvider = fallbackId;
+    await executeProvider(fallbackId);
+  }
+}
+
+// ============================================================================
+// DOM References
+// ============================================================================
+
+
+// ============================================================================
+// Render
+// ============================================================================
+
+function escapeHtml(text: string): string {
+
+  return div.innerHTML;
+}
+
+function circuitBadge(state: CircuitState): string {
+  const cls =
+    state === "CLOSED" ? "closed" : state === "OPEN" ? "open" : "half-open";
+
+  return `<span class="pr-circuit-badge ${cls}">${state}</span>`;
+}
+
+  stats: ProviderStats,
+  state: CircuitState,
+): void {
+    ${circuitBadge(state)}
+    <span style="font-size:0.55rem;color:var(--brand-text-dim)">${stats.callCount} calls, ${stats.errorCount} err, $${stats.totalCost}</span>
+  `;
+}
+
+
+// ============================================================================
+// Subscribe
+// ============================================================================
+
+const allKeys = [
+  ...Object.keys(schema.facts),
+  ...Object.keys(schema.derivations),
+];
+system.subscribe(allKeys, render);
+
+setInterval(render, 1000);
+
+// ============================================================================
+// Controls
+// ============================================================================
+
+
+for (const id of ["openai", "anthropic", "ollama"]) {
+    system.events.toggleProviderError({ provider: id });
+  });
+}
+
+  "input",
+  (e) => {
+    system.events.setBudget({ value });
+  },
+);
+
+
+// ============================================================================
+// Initial Render
+// ============================================================================
+
+render();

package/examples/server.ts

@@ -0,0 +1,316 @@
+// Example: server
+// Source: examples/server/src/server.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Directive Server Example
+ *
+ * An Express API demonstrating Directive's server-side features:
+ * - Distributable snapshots with TTL
+ * - Signed snapshot verification (HMAC-SHA256)
+ * - Cryptographic audit trail
+ * - GDPR/CCPA compliance tooling
+ *
+ * Run: npx tsx --watch src/server.ts
+ */
+
+import {
+  createAuditTrail,
+  createCompliance,
+  createInMemoryComplianceStorage,
+} from "@directive-run/ai";
+import {
+  createSystem,
+  isSnapshotExpired,
+  signSnapshot,
+  verifySnapshotSignature,
+} from "@directive-run/core";
+import express from "express";
+import { userProfile } from "./module.js";
+
+const app = express();
+app.use(express.json());
+
+// ============================================================================
+// Shared Infrastructure
+// ============================================================================
+
+const SIGNING_SECRET =
+  process.env.SIGNING_SECRET ?? "dev-secret-change-in-production";
+
+// Audit trail – shared across requests, acts as a Directive plugin
+const audit = createAuditTrail({
+  maxEntries: 10_000,
+  retentionMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+  piiMasking: {
+    enabled: true,
+    types: ["email", "name"],
+    redactionStyle: "masked",
+  },
+});
+
+// Compliance – in-memory storage for this example (use a DB adapter in production)
+const compliance = createCompliance({
+  storage: createInMemoryComplianceStorage(),
+  consentPurposes: ["analytics", "marketing", "personalization"],
+});
+
+// In-memory snapshot cache (use Redis in production)
+const snapshotCache = new Map<
+  string,
+  { snapshot: unknown; cachedAt: number }
+>();
+const CACHE_TTL_MS = 60_000; // 1 minute
+
+// ============================================================================
+// Helper: Per-Request System Factory
+// ============================================================================
+
+function createUserSystem(userId: string) {
+  const system = createSystem({
+    module: userProfile,
+    plugins: [audit.createPlugin()],
+  });
+
+  system.start();
+  system.events.loadUser({ userId });
+
+  return system;
+}
+
+// ============================================================================
+// GET /snapshot/:userId
+// Distributable Snapshots with TTL
+// ============================================================================
+
+app.get("/snapshot/:userId", async (req, res) => {
+  const { userId } = req.params;
+
+  // Check cache first
+  const cached = snapshotCache.get(userId);
+  if (cached && Date.now() - cached.cachedAt < CACHE_TTL_MS) {
+    res.json({ source: "cache", snapshot: cached.snapshot });
+
+    return;
+  }
+
+  // Create a per-request system, settle it, then export a distributable snapshot
+  const system = createUserSystem(userId);
+
+  try {
+    await system.settle(5000);
+
+    const snapshot = system.getDistributableSnapshot({
+      includeDerivations: ["effectivePlan", "canUseFeature", "isReady"],
+      ttlSeconds: 3600,
+    });
+
+    // Cache it
+    snapshotCache.set(userId, { snapshot, cachedAt: Date.now() });
+
+    res.json({ source: "fresh", snapshot });
+  } catch (error) {
+    res.status(500).json({ error: "Failed to settle system" });
+  } finally {
+    system.destroy();
+  }
+});
+
+// ============================================================================
+// POST /snapshot/:userId/verify
+// Signed Snapshot Verification
+// ============================================================================
+
+app.post("/snapshot/:userId/verify", async (req, res) => {
+  const { snapshot } = req.body;
+
+  if (!snapshot) {
+    res.status(400).json({ error: "Missing snapshot in request body" });
+
+    return;
+  }
+
+  // Sign a fresh snapshot for this user
+  const system = createUserSystem(req.params.userId);
+
+  try {
+    await system.settle(5000);
+
+    const freshSnapshot = system.getDistributableSnapshot({
+      includeDerivations: ["effectivePlan", "canUseFeature", "isReady"],
+      ttlSeconds: 3600,
+    });
+
+    // Sign the snapshot with HMAC-SHA256
+    const signed = await signSnapshot(freshSnapshot, SIGNING_SECRET);
+
+    // Verify the provided snapshot's signature
+    if (snapshot.signature) {
+      const isValid = await verifySnapshotSignature(snapshot, SIGNING_SECRET);
+      const isExpired = isSnapshotExpired(snapshot);
+
+      res.json({
+        signatureValid: isValid,
+        expired: isExpired,
+        signedSnapshot: signed,
+      });
+    } else {
+      // No signature on the incoming snapshot – just return a signed version
+      res.json({
+        signatureValid: null,
+        expired: false,
+        signedSnapshot: signed,
+      });
+    }
+  } catch (error) {
+    res.status(500).json({ error: "Verification failed" });
+  } finally {
+    system.destroy();
+  }
+});
+
+// ============================================================================
+// GET /audit
+// Query Audit Entries
+// ============================================================================
+
+app.get("/audit", (req, res) => {
+  const { eventType, since, actorId, limit } = req.query;
+
+  // biome-ignore lint/suspicious/noExplicitAny: eventType comes from query string
+  const entries = audit.getEntries({
+    eventTypes: eventType ? [eventType as any] : undefined,
+    since: since ? Number(since) : undefined,
+    actorId: actorId as string | undefined,
+    limit: limit ? Number(limit) : 50,
+  });
+
+  res.json({
+    count: entries.length,
+    entries,
+  });
+});
+
+// ============================================================================
+// GET /audit/verify
+// Verify Audit Hash Chain Integrity
+// ============================================================================
+
+app.get("/audit/verify", async (_req, res) => {
+  const result = await audit.verifyChain();
+
+  res.json({
+    chainValid: result.valid,
+    entriesVerified: result.entriesVerified,
+    brokenAt: result.brokenAt ?? null,
+    verifiedAt: new Date(result.verifiedAt).toISOString(),
+  });
+});
+
+// ============================================================================
+// POST /compliance/:subjectId/export
+// GDPR Article 20 – Data Export
+// ============================================================================
+
+app.post("/compliance/:subjectId/export", async (req, res) => {
+  const { subjectId } = req.params;
+
+  // Record consent for analytics before exporting
+  await compliance.consent.grant(subjectId, "analytics", {
+    source: "api-request",
+  });
+
+  const result = await compliance.exportData({
+    subjectId,
+    format: "json",
+    includeAudit: true,
+  });
+
+  if (result.success) {
+    res.json({
+      subjectId,
+      exportedAt: new Date(result.exportedAt).toISOString(),
+      expiresAt: result.expiresAt
+        ? new Date(result.expiresAt).toISOString()
+        : null,
+      recordCount: result.recordCount,
+      checksum: result.checksum,
+      data: JSON.parse(result.data),
+    });
+  } else {
+    res.status(500).json({ error: "Export failed" });
+  }
+});
+
+// ============================================================================
+// POST /compliance/:subjectId/delete
+// GDPR Article 17 – Right to Erasure
+// ============================================================================
+
+app.post("/compliance/:subjectId/delete", async (req, res) => {
+  const { subjectId } = req.params;
+  const { reason } = req.body;
+
+  const result = await compliance.deleteData({
+    subjectId,
+    scope: "all",
+    reason: reason ?? "GDPR Article 17 request",
+  });
+
+  if (result.success) {
+    res.json({
+      subjectId,
+      deletedAt: new Date(result.deletedAt).toISOString(),
+      recordsAffected: result.recordsAffected,
+      certificate: result.certificate,
+    });
+  } else {
+    res.status(500).json({ error: "Deletion failed" });
+  }
+});
+
+// ============================================================================
+// GET /health
+// Health Check
+// ============================================================================
+
+app.get("/health", (_req, res) => {
+  const auditStats = audit.getStats();
+
+  res.json({
+    status: "ok",
+    audit: {
+      totalEntries: auditStats.totalEntries,
+      oldestEntry: auditStats.oldestEntry
+        ? new Date(auditStats.oldestEntry).toISOString()
+        : null,
+      newestEntry: auditStats.newestEntry
+        ? new Date(auditStats.newestEntry).toISOString()
+        : null,
+      chainIntegrity: auditStats.chainIntegrity,
+    },
+  });
+});
+
+// ============================================================================
+// Start
+// ============================================================================
+
+const PORT = Number(process.env.PORT ?? 3000);
+
+app.listen(PORT, () => {
+  console.log(`Directive server example running on http://localhost:${PORT}`);
+  console.log();
+  console.log("Endpoints:");
+  console.log(
+    "  GET  /snapshot/:userId           Distributable snapshot with TTL",
+  );
+  console.log("  POST /snapshot/:userId/verify     Sign and verify snapshots");
+  console.log("  GET  /audit                      Query audit entries");
+  console.log("  GET  /audit/verify               Verify hash chain integrity");
+  console.log("  POST /compliance/:subjectId/export  GDPR data export");
+  console.log("  POST /compliance/:subjectId/delete  GDPR right to erasure");
+  console.log("  GET  /health                     Health check");
+  console.log();
+  console.log("Try: curl http://localhost:3000/snapshot/user-1");
+});