@directive-run/knowledge 0.2.0 → 0.5.0

package/examples/provider-routing.ts

@@ -1,9 +1,9 @@
 // Example: provider-routing
-// Source: examples/provider-routing/src/main.ts
-// Extracted for AI rules — DOM wiring stripped
+// Source: examples/provider-routing/src/module.ts
+// Pure module file — no DOM wiring
 
 /**
- * Smart Provider Router — Constraint-Based Provider Routing & Fallback
+ * Smart Provider Router — Module Definition
  *
  * 3 mock providers (OpenAI, Anthropic, Ollama). Constraint router selects based
  * on cost, error rates, circuit state. Provider fallback chain.
@@ -25,7 +25,7 @@ import {
 // Types
 // ============================================================================
 
-interface ProviderStats {
+export interface ProviderStats {
   name: string;
   callCount: number;
   errorCount: number;
@@ -34,7 +34,7 @@ interface ProviderStats {
   circuitState: CircuitState;
 }
 
-interface TimelineEntry {
+export interface TimelineEntry {
   time: number;
   event: string;
   detail: string;
@@ -57,13 +57,14 @@ const providerErrors: Record<string, boolean> = {
   ollama: false,
 };
 
-const circuitBreakers = {
+export const circuitBreakers = {
   openai: createCircuitBreaker({
     name: "openai",
     failureThreshold: 3,
     recoveryTimeMs: 5000,
     halfOpenMaxRequests: 2,
     onStateChange: (from, to) =>
+      addTimeline("circuit", `openai: ${from} → ${to}`, "circuit"),
   }),
   anthropic: createCircuitBreaker({
     name: "anthropic",
@@ -71,6 +72,7 @@ const circuitBreakers = {
     recoveryTimeMs: 5000,
     halfOpenMaxRequests: 2,
     onStateChange: (from, to) =>
+      addTimeline("circuit", `anthropic: ${from} → ${to}`, "circuit"),
   }),
   ollama: createCircuitBreaker({
     name: "ollama",
@@ -78,6 +80,7 @@ const circuitBreakers = {
     recoveryTimeMs: 5000,
     halfOpenMaxRequests: 2,
     onStateChange: (from, to) =>
+      addTimeline("circuit", `ollama: ${from} → ${to}`, "circuit"),
   }),
 };
 
@@ -85,9 +88,9 @@ const circuitBreakers = {
 // Timeline
 // ============================================================================
 
-const timeline: TimelineEntry[] = [];
+export const timeline: TimelineEntry[] = [];
 
-function addTimeline(
+export function addTimeline(
   event: string,
   detail: string,
   type: TimelineEntry["type"],
@@ -102,7 +105,7 @@ function addTimeline(
 // Schema
 // ============================================================================
 
-const schema = {
+export const schema = {
   facts: {
     openaiStats: t.object<ProviderStats>(),
     anthropicStats: t.object<ProviderStats>(),
@@ -216,20 +219,19 @@ const routerModule = createModule("router", {
 // System
 // ============================================================================
 
-const system = createSystem({
+export 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;
+  const budget = system.facts.budgetRemaining;
+  const preferCheapest = system.facts.preferCheapest;
 
   // Collect available providers (circuit breaker allows + within budget)
   const available: { id: string; cost: number }[] = [];
@@ -280,7 +282,7 @@ async function executeProvider(providerId: string): Promise<boolean> {
       }
     });
 
-    const stats = system.facts[statsKey] as ProviderStats;
+    const stats = system.facts[statsKey];
     const cost = config.costPer1k;
     const latency = config.baseLatency + Math.random() * 100;
     system.facts[statsKey] = {
@@ -294,35 +296,38 @@ async function executeProvider(providerId: string): Promise<boolean> {
       circuitState: breaker.getState(),
     };
     system.facts.budgetRemaining =
-      Math.round(((system.facts.budgetRemaining as number) - cost) * 1000) /
-      1000;
+      Math.round((system.facts.budgetRemaining - cost) * 1000) / 1000;
     system.facts.lastError = "";
+    addTimeline("success", `${config.name}: ok ($${cost})`, "success");
 
     return true;
   } catch (err) {
-    const stats = system.facts[statsKey] as ProviderStats;
+    const stats = system.facts[statsKey];
     system.facts[statsKey] = {
       ...stats,
       errorCount: stats.errorCount + 1,
       circuitState: breaker.getState(),
     };
     system.facts.lastError = err instanceof Error ? err.message : String(err);
+    addTimeline("error", `${config.name}: ${system.facts.lastError}`, "error");
 
     return false;
   }
 }
 
-async function sendRequest() {
-  system.facts.totalRequests = (system.facts.totalRequests as number) + 1;
+export async function sendRequest(): Promise<void> {
+  system.facts.totalRequests = system.facts.totalRequests + 1;
 
   const providerId = selectProvider();
   if (!providerId) {
     system.facts.lastError = "All providers unavailable or over budget";
+    addTimeline("error", "no available providers", "error");
 
     return;
   }
 
   system.facts.lastProvider = providerId;
+  addTimeline("route", `→ ${providerId}`, "route");
 
   const success = await executeProvider(providerId);
   if (success) {
@@ -332,72 +337,10 @@ async function sendRequest() {
   // Primary failed — try fallback
   const fallbackId = selectProvider();
   if (fallbackId && fallbackId !== providerId) {
+    addTimeline("fallback", `falling back to ${fallbackId}`, "fallback");
     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();
+export { providerErrors };

package/examples/shopping-cart.ts

@@ -187,23 +187,23 @@ export const cartModule = createModule("cart", {
       return facts.self.items.length === 0;
     },
 
-    discount: (facts, derive) => {
-      const sub = derive.subtotal as number;
+    discount: (facts, derived) => {
+      const sub = derived.subtotal;
 
       return sub * (facts.self.couponDiscount / 100);
     },
 
-    tax: (facts, derive) => {
-      const sub = derive.subtotal as number;
-      const disc = derive.discount as number;
+    tax: (facts, derived) => {
+      const sub = derived.subtotal;
+      const disc = derived.discount;
 
       return (sub - disc) * 0.08;
     },
 
-    total: (_facts, derive) => {
-      const sub = derive.subtotal as number;
-      const disc = derive.discount as number;
-      const tx = derive.tax as number;
+    total: (_facts, derived) => {
+      const sub = derived.subtotal;
+      const disc = derived.discount;
+      const tx = derived.tax;
 
       return sub - disc + tx;
     },
@@ -214,8 +214,8 @@ export const cartModule = createModule("cart", {
       );
     },
 
-    freeShipping: (_facts, derive) => {
-      const sub = derive.subtotal as number;
+    freeShipping: (_facts, derived) => {
+      const sub = derived.subtotal;
 
       return sub >= 75;
     },
@@ -317,7 +317,7 @@ export const cartModule = createModule("cart", {
       priority: 60,
       after: ["quantityLimit", "couponValidation"],
       when: (facts) => {
-        const items = facts.self.items as CartItem[];
+        const items = facts.self.items;
         const notEmpty = items.length > 0;
         const noOverstock = !items.some(
           (item: CartItem) => item.quantity > item.maxStock,

package/examples/sudoku.ts

@@ -52,23 +52,23 @@ export const sudokuSchema = {
     won: t.boolean(),
     message: t.string(),
     notesMode: t.boolean(),
-    notes: t.object<Set<number>[]>(),
+    notes: t.array<Set<number>>(),
     hintsUsed: t.number(),
     errorsCount: t.number(),
     hintRequested: t.boolean(),
   },
   derivations: {
-    conflicts: t.object<Conflict[]>(),
+    conflicts: t.array<Conflict>(),
     conflictIndices: t.object<Set<number>>(),
     hasConflicts: t.boolean(),
     filledCount: t.number(),
     progress: t.number(),
     isComplete: t.boolean(),
     isSolved: t.boolean(),
-    selectedPeers: t.object<number[]>(),
+    selectedPeers: t.array<number>(),
     highlightValue: t.number(),
     sameValueIndices: t.object<Set<number>>(),
-    candidates: t.object<number[]>(),
+    candidates: t.array<number>(),
     timerDisplay: t.string(),
     timerUrgency: t.object<"normal" | "warning" | "critical">(),
   },
@@ -144,13 +144,13 @@ export const sudokuGame = createModule("sudoku", {
 
   derive: {
     conflicts: (facts) => {
-      return findConflicts(facts.grid as Grid);
+      return findConflicts(facts.grid);
     },
 
-    conflictIndices: (facts, derive) => {
+    conflictIndices: (facts, derived) => {
       const indices = new Set<number>();
-      const givens = facts.givens as Set<number>;
-      for (const c of derive.conflicts as Conflict[]) {
+      const givens = facts.givens;
+      for (const c of derived.conflicts) {
         // Only highlight player-placed cells, not givens
         if (!givens.has(c.index)) {
           indices.add(c.index);
@@ -160,13 +160,13 @@ export const sudokuGame = createModule("sudoku", {
       return indices;
     },
 
-    hasConflicts: (_facts, derive) => {
-      return (derive.conflicts as Conflict[]).length > 0;
+    hasConflicts: (_facts, derived) => {
+      return derived.conflicts.length > 0;
     },
 
     filledCount: (facts) => {
       let count = 0;
-      const grid = facts.grid as Grid;
+      const grid = facts.grid;
       for (let i = 0; i < 81; i++) {
         if (grid[i] !== 0) {
           count++;
@@ -176,22 +176,20 @@ export const sudokuGame = createModule("sudoku", {
       return count;
     },
 
-    progress: (_facts, derive) => {
-      return Math.round(((derive.filledCount as number) / 81) * 100);
+    progress: (_facts, derived) => {
+      return Math.round((derived.filledCount / 81) * 100);
     },
 
     isComplete: (facts) => {
-      return isBoardComplete(facts.grid as Grid);
+      return isBoardComplete(facts.grid);
     },
 
-    isSolved: (_facts, derive) => {
-      return (
-        (derive.isComplete as boolean) && !(derive.hasConflicts as boolean)
-      );
+    isSolved: (_facts, derived) => {
+      return derived.isComplete && !derived.hasConflicts;
     },
 
     selectedPeers: (facts) => {
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         return [];
       }
@@ -200,22 +198,22 @@ export const sudokuGame = createModule("sudoku", {
     },
 
     highlightValue: (facts) => {
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         return 0;
       }
 
-      return (facts.grid as Grid)[sel];
+      return facts.grid[sel];
     },
 
-    sameValueIndices: (facts, derive) => {
-      const val = derive.highlightValue as number;
+    sameValueIndices: (facts, derived) => {
+      const val = derived.highlightValue;
       if (val === 0) {
         return new Set<number>();
       }
 
       const indices = new Set<number>();
-      const grid = facts.grid as Grid;
+      const grid = facts.grid;
       for (let i = 0; i < 81; i++) {
         if (grid[i] === val) {
           indices.add(i);
@@ -226,16 +224,16 @@ export const sudokuGame = createModule("sudoku", {
     },
 
     candidates: (facts) => {
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         return [];
       }
 
-      return getCandidates(facts.grid as Grid, sel);
+      return getCandidates(facts.grid, sel);
     },
 
     timerDisplay: (facts) => {
-      const remaining = facts.timerRemaining as number;
+      const remaining = facts.timerRemaining;
       const mins = Math.max(0, Math.floor(remaining / 60));
       const secs = Math.max(0, remaining % 60);
 
@@ -243,7 +241,7 @@ export const sudokuGame = createModule("sudoku", {
     },
 
     timerUrgency: (facts) => {
-      const remaining = facts.timerRemaining as number;
+      const remaining = facts.timerRemaining;
       if (remaining <= TIMER_CRITICAL_THRESHOLD) {
         return "critical";
       }
@@ -299,12 +297,12 @@ export const sudokuGame = createModule("sudoku", {
         return;
       }
 
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         return;
       }
 
-      const givens = facts.givens as Set<number>;
+      const givens = facts.givens;
       if (givens.has(sel)) {
         facts.message = "That cell is locked.";
 
@@ -313,7 +311,7 @@ export const sudokuGame = createModule("sudoku", {
 
       if (facts.notesMode && value !== 0) {
         // In notes mode, toggle the pencil mark instead
-        const notes = [...(facts.notes as Set<number>[])];
+        const notes = [...facts.notes];
         notes[sel] = new Set(notes[sel]);
         if (notes[sel].has(value)) {
           notes[sel].delete(value);
@@ -327,13 +325,13 @@ export const sudokuGame = createModule("sudoku", {
       }
 
       // Place or clear a number
-      const grid = [...(facts.grid as Grid)];
+      const grid = [...facts.grid];
       grid[sel] = value;
       facts.grid = grid;
 
       // Clear notes for this cell when placing a number
       if (value !== 0) {
-        const notes = [...(facts.notes as Set<number>[])];
+        const notes = [...facts.notes];
         notes[sel] = new Set();
         // Also clear this value from peer notes
         for (const peer of getPeers(sel)) {
@@ -353,22 +351,22 @@ export const sudokuGame = createModule("sudoku", {
         return;
       }
 
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         return;
       }
 
-      const givens = facts.givens as Set<number>;
+      const givens = facts.givens;
       if (givens.has(sel)) {
         return;
       }
 
       // Only allow notes on empty cells
-      if ((facts.grid as Grid)[sel] !== 0) {
+      if (facts.grid[sel] !== 0) {
         return;
       }
 
-      const notes = [...(facts.notes as Set<number>[])];
+      const notes = [...facts.notes];
       notes[sel] = new Set(notes[sel]);
       if (notes[sel].has(value)) {
         notes[sel].delete(value);
@@ -379,7 +377,7 @@ export const sudokuGame = createModule("sudoku", {
     },
 
     toggleNotesMode: (facts) => {
-      facts.notesMode = !(facts.notesMode as boolean);
+      facts.notesMode = !facts.notesMode;
     },
 
     requestHint: (facts) => {
@@ -392,21 +390,21 @@ export const sudokuGame = createModule("sudoku", {
         return;
       }
 
-      const sel = facts.selectedIndex as number | null;
+      const sel = facts.selectedIndex;
       if (sel === null) {
         facts.message = "Select a cell first.";
 
         return;
       }
 
-      const givens = facts.givens as Set<number>;
+      const givens = facts.givens;
       if (givens.has(sel)) {
         facts.message = "That cell is already filled.";
 
         return;
       }
 
-      if ((facts.grid as Grid)[sel] !== 0) {
+      if (facts.grid[sel] !== 0) {
         facts.message = "Clear the cell first, or select an empty cell.";
 
         return;
@@ -420,7 +418,7 @@ export const sudokuGame = createModule("sudoku", {
       if (!facts.timerRunning || facts.gameOver) {
         return;
       }
-      facts.timerRemaining = Math.max(0, (facts.timerRemaining as number) - 1);
+      facts.timerRemaining = Math.max(0, facts.timerRemaining - 1);
     },
   },
 
@@ -437,7 +435,7 @@ export const sudokuGame = createModule("sudoku", {
           return false;
         }
 
-        return (facts.timerRemaining as number) <= 0;
+        return facts.timerRemaining <= 0;
       },
       require: () => ({
         type: "GAME_OVER",
@@ -452,14 +450,14 @@ export const sudokuGame = createModule("sudoku", {
         if (facts.gameOver) {
           return false;
         }
-        const conflicts = findConflicts(facts.grid as Grid);
-        const givens = facts.givens as Set<number>;
+        const conflicts = findConflicts(facts.grid);
+        const givens = facts.givens;
 
         return conflicts.some((c) => !givens.has(c.index));
       },
       require: (facts) => {
-        const conflicts = findConflicts(facts.grid as Grid);
-        const givens = facts.givens as Set<number>;
+        const conflicts = findConflicts(facts.grid);
+        const givens = facts.givens;
         const playerConflict = conflicts.find((c) => !givens.has(c.index));
         const idx = playerConflict?.index ?? 0;
         const { row, col } = toRowCol(idx);
@@ -483,15 +481,14 @@ export const sudokuGame = createModule("sudoku", {
         }
 
         return (
-          isBoardComplete(facts.grid as Grid) &&
-          findConflicts(facts.grid as Grid).length === 0
+          isBoardComplete(facts.grid) && findConflicts(facts.grid).length === 0
         );
       },
       require: (facts) => ({
         type: "GAME_WON",
-        timeLeft: facts.timerRemaining as number,
-        hintsUsed: facts.hintsUsed as number,
-        errors: facts.errorsCount as number,
+        timeLeft: facts.timerRemaining,
+        hintsUsed: facts.hintsUsed,
+        errors: facts.errorsCount,
       }),
     },
 
@@ -506,16 +503,16 @@ export const sudokuGame = createModule("sudoku", {
           return false;
         }
 
-        const sel = facts.selectedIndex as number | null;
+        const sel = facts.selectedIndex;
         if (sel === null) {
           return false;
         }
 
-        return (facts.grid as Grid)[sel] === 0;
+        return facts.grid[sel] === 0;
       },
       require: (facts) => {
         const sel = facts.selectedIndex as number;
-        const solution = facts.solution as Grid;
+        const solution = facts.solution;
 
         return {
           type: "REVEAL_HINT",
@@ -534,7 +531,7 @@ export const sudokuGame = createModule("sudoku", {
     showConflict: {
       requirement: "SHOW_CONFLICT",
       resolve: async (req, context) => {
-        context.facts.errorsCount = (context.facts.errorsCount as number) + 1;
+        context.facts.errorsCount = context.facts.errorsCount + 1;
         context.facts.message = `Conflict at row ${req.row}, column ${req.col} – duplicate ${req.value}.`;
       },
     },
@@ -547,14 +544,10 @@ export const sudokuGame = createModule("sudoku", {
         context.facts.won = true;
 
         const mins = Math.floor(
-          (TIMER_DURATIONS[context.facts.difficulty as Difficulty] -
-            req.timeLeft) /
-            60,
+          (TIMER_DURATIONS[context.facts.difficulty] - req.timeLeft) / 60,
         );
         const secs =
-          (TIMER_DURATIONS[context.facts.difficulty as Difficulty] -
-            req.timeLeft) %
-          60;
+          (TIMER_DURATIONS[context.facts.difficulty] - req.timeLeft) % 60;
         context.facts.message = `Solved in ${mins}m ${secs}s! Hints: ${req.hintsUsed}, Errors: ${req.errors}`;
       },
     },
@@ -572,12 +565,12 @@ export const sudokuGame = createModule("sudoku", {
     revealHint: {
       requirement: "REVEAL_HINT",
       resolve: async (req, context) => {
-        const grid = [...(context.facts.grid as Grid)];
+        const grid = [...context.facts.grid];
         grid[req.index] = req.value;
         context.facts.grid = grid;
 
         // Clear notes for the hinted cell and remove value from peer notes
-        const notes = [...(context.facts.notes as Set<number>[])];
+        const notes = [...context.facts.notes];
         notes[req.index] = new Set();
         for (const peer of getPeers(req.index)) {
           if (notes[peer].has(req.value)) {
@@ -588,8 +581,8 @@ export const sudokuGame = createModule("sudoku", {
         context.facts.notes = notes;
 
         context.facts.hintRequested = false;
-        context.facts.hintsUsed = (context.facts.hintsUsed as number) + 1;
-        context.facts.message = `Hint revealed! ${MAX_HINTS - (context.facts.hintsUsed as number)} remaining.`;
+        context.facts.hintsUsed = context.facts.hintsUsed + 1;
+        context.facts.message = `Hint revealed! ${MAX_HINTS - context.facts.hintsUsed} remaining.`;
       },
     },
   },
@@ -602,7 +595,7 @@ export const sudokuGame = createModule("sudoku", {
     timerWarning: {
       deps: ["timerRemaining"],
       run: (facts) => {
-        const remaining = facts.timerRemaining as number;
+        const remaining = facts.timerRemaining;
         if (remaining === TIMER_EFFECT_WARNING) {
           console.log("[Sudoku] 1 minute remaining!");
         }