@directive-run/knowledge 0.8.2 → 0.8.4

package/LICENSE

@@ -2,6 +2,11 @@ MIT License
 
 Copyright (c) 2026 Sizls LLC
 
+This project is dual-licensed under MIT OR Apache-2.0. You may choose
+either license. See LICENSE-APACHE for the Apache License, Version 2.0.
+
+---
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/core/plugins.md

@@ -28,7 +28,7 @@ const system = createSystem({
   module: myModule,
   plugins: [
     devtoolsPlugin(),
-    loggingPlugin({ verbose: true }),
+    loggingPlugin({ level: "debug" }),
     persistencePlugin({
       key: "my-app-state",
       storage: localStorage,
@@ -46,25 +46,27 @@ Logs state changes, requirements, and resolutions to the console.
 ```typescript
 import { loggingPlugin } from "@directive-run/core/plugins";
 
-// Default – logs facts changes and resolver start/complete
+// Default – logs facts changes and resolver start/complete at "info" level
 loggingPlugin()
 
-// Verbose – logs everything including derivation recomputation and constraint evaluation
-loggingPlugin({ verbose: true })
+// Debug level – logs everything including derivation recomputation and constraint evaluation
+loggingPlugin({ level: "debug" })
 
 // Custom filter – only log specific events
 loggingPlugin({
-  filter: (event) => {
-    // Only log resolver events
-    if (event.type === "resolution:start" || event.type === "resolution:complete") {
-      return true;
-    }
+  filter: (event) => event.startsWith("resolver."),
+})
 
-    return false;
-  },
+// Custom logger and prefix
+loggingPlugin({
+  level: "warn",
+  prefix: "[MyApp]",
+  logger: customLogger,
 })
 ```
 
+Options: `level` ("debug" | "info" | "warn" | "error"), `filter` (predicate on event name string), `logger` (Console-compatible object), `prefix` (string, default "[Directive]").
+
 ## devtoolsPlugin
 
 Connects to the Directive DevTools browser extension for visual state inspection.
@@ -78,7 +80,9 @@ devtoolsPlugin()
 // With options
 devtoolsPlugin({
   name: "My App",        // Name shown in DevTools
-  maxAge: 50,            // Max actions to keep in history
+  maxEvents: 1000,       // Max trace events to retain (default: 1000)
+  trace: true,           // Enable trace logging
+  panel: true,           // Show floating debug panel (dev mode only)
 })
 ```
 
@@ -122,59 +126,56 @@ persistencePlugin({
   exclude: ["tempData", "sessionId"], // Everything except these
 })
 
-// Versioning – handle schema changes
+// With callbacks
 persistencePlugin({
   key: "my-app",
   storage: localStorage,
-  version: 2,
-  migrate: (oldState, oldVersion) => {
-    if (oldVersion === 1) {
-      return {
-        ...oldState,
-        newField: "default",
-      };
-    }
-
-    return oldState;
-  },
+  debounce: 200,                       // Debounce saves (default: 100ms)
+  onRestore: (data) => console.log("Restored:", data),
+  onSave: (data) => console.log("Saved:", data),
+  onError: (err) => console.error("Persistence error:", err),
 })
 ```
 
 ## createCircuitBreaker
 
-Wraps resolvers with circuit breaker pattern for resilience.
+Standalone utility (not a Plugin) that implements the circuit breaker pattern for resilience. Use it inside resolvers to protect against cascading failures from external services.
 
 ```typescript
 import { createCircuitBreaker } from "@directive-run/core/plugins";
 
-const system = createSystem({
-  module: myModule,
-  plugins: [
-    createCircuitBreaker({
-      // How many failures before opening the circuit
-      failureThreshold: 5,
-
-      // How long to wait before trying again (ms)
-      resetTimeout: 30000,
-
-      // Optional: only apply to specific resolver types
-      include: ["FETCH_DATA", "SYNC_REMOTE"],
+const breaker = createCircuitBreaker({
+  failureThreshold: 5,         // Failures before opening (default: 5)
+  recoveryTimeMs: 30000,       // Time before HALF_OPEN (default: 30000)
+  halfOpenMaxRequests: 3,      // Requests allowed in HALF_OPEN (default: 3)
+  failureWindowMs: 60000,      // Window for counting failures (default: 60000)
+  name: "api-breaker",         // Name for metrics/errors
+  onStateChange: (from, to) => console.log(`Circuit: ${from} -> ${to}`),
+});
 
-      // Optional: callback when circuit opens
-      onOpen: (resolverType) => {
-        console.warn(`Circuit opened for ${resolverType}`);
-      },
+// Use inside a resolver
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const result = await breaker.execute(async () => {
+        return await callExternalAPI();
+      });
+      context.facts.data = result;
+    },
+  },
+},
 
-      // Optional: callback when circuit closes
-      onClose: (resolverType) => {
-        console.log(`Circuit closed for ${resolverType}`);
-      },
-    }),
-  ],
-});
+// Wire circuit state into constraints
+constraints: {
+  apiDown: {
+    when: () => breaker.getState() === "OPEN",
+    require: { type: "FALLBACK_RESPONSE" },
+  },
+},
 ```
 
-Circuit breaker states: **Closed** (normal) -> **Open** (failing, rejects immediately) -> **Half-Open** (testing one request).
+Circuit breaker states: **Closed** (normal) -> **Open** (failing, rejects immediately) -> **Half-Open** (testing limited requests).
 
 ## createObservability
 
@@ -212,14 +213,14 @@ const system = createSystem({
 Plugins hook into the system lifecycle. Use these to build custom plugins.
 
 ```typescript
-import type { DirectivePlugin } from "@directive-run/core";
+import type { Plugin, ModuleSchema } from "@directive-run/core";
 
-const myPlugin: DirectivePlugin = {
+const myPlugin: Plugin<ModuleSchema> = {
   name: "my-custom-plugin",
 
   // System lifecycle
   onInit: (system) => {
-    // Called when system is created
+    // Called when system is created (only async hook)
   },
   onStart: (system) => {
     // Called when system.start() is invoked
@@ -227,32 +228,42 @@ const myPlugin: DirectivePlugin = {
   onStop: (system) => {
     // Called when system.stop() is invoked
   },
+  onDestroy: (system) => {
+    // Called when system.destroy() is invoked
+  },
 
-  // State tracking
-  onSnapshot: (snapshot) => {
-    // Called after every fact mutation
-    // snapshot.facts contains current state
-    // snapshot.changedKeys lists what changed
+  // Fact tracking
+  onFactSet: (key, value, prev) => {
+    // Called when a single fact is set
+  },
+  onFactsBatch: (changes) => {
+    // Called after a batch of fact changes completes
   },
 
   // Requirement pipeline
-  onRequirementEmitted: (requirement) => {
+  onRequirementCreated: (requirement) => {
     // Called when a constraint emits a requirement
-    // requirement.type, requirement.id, payload
+    // requirement.type, requirement.id
+  },
+  onRequirementMet: (requirement, byResolver) => {
+    // Called when a requirement is fulfilled
   },
-  onResolutionStart: (resolution) => {
+
+  // Resolver pipeline
+  onResolverStart: (resolverId, requirement) => {
     // Called when a resolver begins executing
-    // resolution.resolverId, resolution.requirement
   },
-  onResolutionComplete: (resolution) => {
-    // Called when a resolver finishes (success or failure)
-    // resolution.resolverId, resolution.duration, resolution.error?
+  onResolverComplete: (resolverId, requirement, duration) => {
+    // Called when a resolver finishes successfully
+  },
+  onResolverError: (resolverId, requirement, error) => {
+    // Called when a resolver fails (after all retries)
   },
 
   // Error handling
-  onError: (error, context) => {
-    // Called on any error in the system
-    // context.source: "resolver" | "constraint" | "effect" | "derivation"
+  onError: (error) => {
+    // Called on any DirectiveError in the system
+    // error.source, error.message, error.context
   },
 };
 
@@ -277,7 +288,7 @@ const system = createSystem({
 const plugins = [];
 if (process.env.NODE_ENV === "development") {
   plugins.push(devtoolsPlugin());
-  plugins.push(loggingPlugin({ verbose: true }));
+  plugins.push(loggingPlugin({ level: "debug" }));
 }
 
 const system = createSystem({
@@ -286,21 +297,20 @@ const system = createSystem({
 });
 ```
 
-### Persistence without versioning
+### Persistence without filtering
 
 ```typescript
-// WRONG – schema changes break existing users
+// WRONG – persists everything including transient state
 persistencePlugin({
   key: "app-state",
   storage: localStorage,
 })
 
-// CORRECT – version and migrate
+// CORRECT – use include/exclude to control what's persisted
 persistencePlugin({
   key: "app-state",
   storage: localStorage,
-  version: 1,
-  migrate: (old, version) => old,
+  include: ["user", "preferences", "settings"],
 })
 ```
 

package/examples/counter-react.ts

@@ -0,0 +1,44 @@
+// Example: counter-react
+// Source: examples/counter-react/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Shared counter module — same file used by all framework examples.
+ */
+
+import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+
+const schema = {
+  facts: { count: t.number() },
+  derivations: { doubled: t.number(), isPositive: t.boolean() },
+  events: { increment: {}, decrement: {}, reset: {} },
+  requirements: { CLAMP_TO_ZERO: {} },
+} satisfies ModuleSchema;
+
+export const counterModule = createModule("counter", {
+  schema,
+  init: (facts) => { facts.count = 0; },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+    isPositive: (facts) => facts.count > 0,
+  },
+  events: {
+    increment: (facts) => { facts.count += 1; },
+    decrement: (facts) => { facts.count -= 1; },
+    reset: (facts) => { facts.count = 0; },
+  },
+  constraints: {
+    noNegative: {
+      when: (facts) => facts.count < 0,
+      require: { type: "CLAMP_TO_ZERO" },
+    },
+  },
+  resolvers: {
+    clamp: {
+      requirement: "CLAMP_TO_ZERO",
+      resolve: async (req, context) => { context.facts.count = 0; },
+    },
+  },
+});
+
+export const system = createSystem({ module: counterModule });

package/examples/counter-svelte.ts

@@ -0,0 +1,44 @@
+// Example: counter-svelte
+// Source: examples/counter-svelte/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Shared counter module — same file used by all framework examples.
+ */
+
+import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+
+const schema = {
+  facts: { count: t.number() },
+  derivations: { doubled: t.number(), isPositive: t.boolean() },
+  events: { increment: {}, decrement: {}, reset: {} },
+  requirements: { CLAMP_TO_ZERO: {} },
+} satisfies ModuleSchema;
+
+export const counterModule = createModule("counter", {
+  schema,
+  init: (facts) => { facts.count = 0; },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+    isPositive: (facts) => facts.count > 0,
+  },
+  events: {
+    increment: (facts) => { facts.count += 1; },
+    decrement: (facts) => { facts.count -= 1; },
+    reset: (facts) => { facts.count = 0; },
+  },
+  constraints: {
+    noNegative: {
+      when: (facts) => facts.count < 0,
+      require: { type: "CLAMP_TO_ZERO" },
+    },
+  },
+  resolvers: {
+    clamp: {
+      requirement: "CLAMP_TO_ZERO",
+      resolve: async (req, context) => { context.facts.count = 0; },
+    },
+  },
+});
+
+export const system = createSystem({ module: counterModule });

package/examples/counter-vue.ts

@@ -0,0 +1,44 @@
+// Example: counter-vue
+// Source: examples/counter-vue/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Shared counter module — same file used by all framework examples.
+ */
+
+import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+
+const schema = {
+  facts: { count: t.number() },
+  derivations: { doubled: t.number(), isPositive: t.boolean() },
+  events: { increment: {}, decrement: {}, reset: {} },
+  requirements: { CLAMP_TO_ZERO: {} },
+} satisfies ModuleSchema;
+
+export const counterModule = createModule("counter", {
+  schema,
+  init: (facts) => { facts.count = 0; },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+    isPositive: (facts) => facts.count > 0,
+  },
+  events: {
+    increment: (facts) => { facts.count += 1; },
+    decrement: (facts) => { facts.count -= 1; },
+    reset: (facts) => { facts.count = 0; },
+  },
+  constraints: {
+    noNegative: {
+      when: (facts) => facts.count < 0,
+      require: { type: "CLAMP_TO_ZERO" },
+    },
+  },
+  resolvers: {
+    clamp: {
+      requirement: "CLAMP_TO_ZERO",
+      resolve: async (req, context) => { context.facts.count = 0; },
+    },
+  },
+});
+
+export const system = createSystem({ module: counterModule });

package/examples/counter.ts

@@ -3,374 +3,66 @@
 // Pure module file — no DOM wiring
 
 /**
- * Number Match — Directive Module
+ * Counter — The simplest Directive module.
  *
- * Types, schema, helpers, module definition, timeline, and system creation
- * for a tile-matching game where pairs must add to 10.
+ * Demonstrates: facts, events, derivations, one constraint, one resolver.
+ * Total: ~40 lines.
  */
 
-import {
-  type ModuleSchema,
-  createModule,
-  createSystem,
-  t,
-} from "@directive-run/core";
-import { devtoolsPlugin } from "@directive-run/core/plugins";
+import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
 
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface Tile {
-  id: string;
-  value: number;
-}
-
-export interface TimelineEntry {
-  time: number;
-  event: string;
-  detail: string;
-  type: string;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-// Create a pool of numbered tiles (1-9, four of each = 36 tiles)
-function createPool(): Tile[] {
-  const tiles: Tile[] = [];
-  let id = 0;
-  for (let copy = 0; copy < 4; copy++) {
-    for (let value = 1; value <= 9; value++) {
-      tiles.push({ id: `t${id++}`, value });
-    }
-  }
-  // Shuffle
-  for (let i = tiles.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [tiles[i], tiles[j]] = [tiles[j], tiles[i]];
-  }
-
-  return tiles;
-}
-
-// ============================================================================
-// Timeline
-// ============================================================================
-
-export const timeline: TimelineEntry[] = [];
-
-export function addLog(msg: string) {
-  console.log(`[NumberMatch] ${msg}`);
-
-  // Classify and add significant events to the timeline
-  let event = "";
-  let detail = "";
-  let type = "info";
-
-  if (msg.startsWith("EVENT selectTile")) {
-    event = "tile selected";
-    const match = msg.match(/selectTile: (t\d+)/);
-    detail = match ? match[1] : "";
-    type = "selection";
-  } else if (msg.includes("pairAddsTen: TRUE")) {
-    event = "match found";
-    const match = msg.match(/\((.+)\)/);
-    detail = match ? match[1] : "";
-    type = "match";
-  } else if (msg === "RESOLVER removeTiles: DONE") {
-    event = "tiles removed";
-    detail = "";
-    type = "match";
-  } else if (msg.includes("refillTable: DONE")) {
-    event = "refill";
-    const match = msg.match(/table now: (\d+)/);
-    detail = match ? `table: ${match[1]} tiles` : "";
-    type = "refill";
-  } else if (msg.startsWith("RESOLVER endGame:")) {
-    event = "game over";
-    detail = msg.replace("RESOLVER endGame: ", "");
-    type = "gameover";
-  } else if (msg.includes("New game") || msg.includes("Game started")) {
-    event = "new game";
-    detail = msg;
-    type = "newgame";
-  } else {
-    // Skip verbose intermediate messages (RESOLVER steps, CONSTRAINT produce)
-    return;
-  }
-
-  timeline.unshift({ time: Date.now(), event, detail, type });
-}
-
-// ============================================================================
-// Schema
-// ============================================================================
-
-export const schema = {
+const schema = {
   facts: {
-    pool: t.array<Tile>(),
-    table: t.array<Tile>(),
-    removed: t.array<Tile>(),
-    selected: t.array<string>(),
-    message: t.string(),
-    moveCount: t.number(),
-    gameOver: t.boolean(),
+    count: t.number(),
   },
   derivations: {
-    poolCount: t.number(),
-    removedCount: t.number(),
-    selectedTiles: t.array<Tile>(),
-    hasValidMoves: t.boolean(),
+    doubled: t.number(),
+    isPositive: t.boolean(),
   },
   events: {
-    newGame: {},
-    selectTile: { tileId: t.string() },
-    deselectTile: { tileId: t.string() },
-    clearSelection: {},
+    increment: {},
+    decrement: {},
+    reset: {},
   },
   requirements: {
-    REMOVE_TILES: { tileIds: t.array<string>() },
-    REFILL_TABLE: { count: t.number() },
-    END_GAME: { reason: t.string() },
+    CLAMP_TO_ZERO: {},
   },
 } satisfies ModuleSchema;
 
-// ============================================================================
-// Module
-// ============================================================================
-
-const numberMatch = createModule("number-match", {
+export const counterModule = createModule("counter", {
   schema,
 
   init: (facts) => {
-    const pool = createPool();
-    facts.pool = pool.slice(9);
-    facts.table = pool.slice(0, 9);
-    facts.removed = [];
-    facts.selected = [];
-    facts.message = "Select two numbers that add to 10";
-    facts.moveCount = 0;
-    facts.gameOver = false;
+    facts.count = 0;
   },
 
   derive: {
-    poolCount: (facts) => facts.pool.length,
-    removedCount: (facts) => facts.removed.length,
-    selectedTiles: (facts) =>
-      facts.table.filter((tile: Tile) => facts.selected.includes(tile.id)),
-    hasValidMoves: (facts) => {
-      const nums = facts.table.map((t: Tile) => t.value);
-      for (let i = 0; i < nums.length; i++) {
-        for (let j = i + 1; j < nums.length; j++) {
-          if (nums[i] + nums[j] === 10) {
-            return true;
-          }
-        }
-      }
-
-      return false;
-    },
+    doubled: (facts) => facts.count * 2,
+    isPositive: (facts) => facts.count > 0,
   },
 
   events: {
-    newGame: (facts) => {
-      const pool = createPool();
-      facts.pool = pool.slice(9);
-      facts.table = pool.slice(0, 9);
-      facts.removed = [];
-      facts.selected = [];
-      facts.message = "New game! Select two numbers that add to 10";
-      facts.moveCount = 0;
-      facts.gameOver = false;
-    },
-    selectTile: (facts, { tileId }) => {
-      if (!facts.selected.includes(tileId) && !facts.gameOver) {
-        facts.selected = [...facts.selected, tileId];
-        addLog(
-          `EVENT selectTile: ${tileId}, selected now: [${facts.selected}]`,
-        );
-      }
-    },
-    deselectTile: (facts, { tileId }) => {
-      facts.selected = facts.selected.filter((id: string) => id !== tileId);
-    },
-    clearSelection: (facts) => {
-      facts.selected = [];
-    },
+    increment: (facts) => { facts.count += 1; },
+    decrement: (facts) => { facts.count -= 1; },
+    reset: (facts) => { facts.count = 0; },
   },
 
-  // ============================================================================
-  // Constraints
-  // ============================================================================
+  // When count goes negative, automatically fix it
   constraints: {
-    // When two selected tiles add to 10 -> remove them
-    pairAddsTen: {
-      priority: 100,
-      when: (facts) => {
-        if (facts.gameOver) {
-          return false;
-        }
-        const selected = facts.table.filter((tile: Tile) =>
-          facts.selected.includes(tile.id),
-        );
-        if (selected.length !== 2) {
-          return false;
-        }
-        const result = selected[0].value + selected[1].value === 10;
-        if (result) {
-          addLog(
-            `CONSTRAINT pairAddsTen: TRUE (${selected[0].value} + ${selected[1].value})`,
-          );
-        }
-
-        return result;
-      },
-      require: (facts) => {
-        addLog("CONSTRAINT pairAddsTen: producing REMOVE_TILES");
-
-        return {
-          type: "REMOVE_TILES",
-          tileIds: [...facts.selected],
-        };
-      },
-    },
-
-    // Refill table when tiles are removed
-    refillTable: {
-      priority: 50,
-      when: (facts) => {
-        const result =
-          !facts.gameOver && facts.table.length < 9 && facts.pool.length > 0;
-        if (result) {
-          addLog(
-            `CONSTRAINT refillTable: TRUE (table: ${facts.table.length}, pool: ${facts.pool.length})`,
-          );
-        }
-
-        return result;
-      },
-      require: (facts) => {
-        const count = Math.min(9 - facts.table.length, facts.pool.length);
-        addLog(`CONSTRAINT refillTable: producing REFILL_TABLE count=${count}`);
-
-        return { type: "REFILL_TABLE", count };
-      },
-    },
-
-    // No moves left -> game over
-    noMovesLeft: {
-      priority: 190,
-      when: (facts) => {
-        if (facts.gameOver) {
-          return false;
-        }
-        if (facts.table.length === 0) {
-          return false;
-        }
-        if (facts.pool.length > 0) {
-          return false;
-        }
-        const nums = facts.table.map((t: Tile) => t.value);
-        for (let i = 0; i < nums.length; i++) {
-          for (let j = i + 1; j < nums.length; j++) {
-            if (nums[i] + nums[j] === 10) {
-              return false;
-            }
-          }
-        }
-        addLog("CONSTRAINT noMovesLeft: TRUE");
-
-        return true;
-      },
-      require: (facts) => ({
-        type: "END_GAME",
-        reason: `Game over! Removed ${facts.removed.length} of 36 tiles.`,
-      }),
-    },
-
-    // Win condition
-    allCleared: {
-      priority: 200,
-      when: (facts) => {
-        const result =
-          !facts.gameOver &&
-          facts.table.length === 0 &&
-          facts.pool.length === 0;
-        if (result) {
-          addLog("CONSTRAINT allCleared: TRUE");
-        }
-
-        return result;
-      },
-      require: (facts) => ({
-        type: "END_GAME",
-        reason: `You win! Cleared all tiles in ${facts.moveCount} moves!`,
-      }),
+    noNegative: {
+      when: (facts) => facts.count < 0,
+      require: { type: "CLAMP_TO_ZERO" },
     },
   },
 
-  // ============================================================================
-  // Resolvers
-  // ============================================================================
   resolvers: {
-    removeTiles: {
-      requirement: "REMOVE_TILES",
-      resolve: async (req, context) => {
-        addLog("RESOLVER removeTiles: START");
-        const tilesToRemove = context.facts.table.filter((tile: Tile) =>
-          req.tileIds.includes(tile.id),
-        );
-
-        // Multiple fact mutations
-        addLog("RESOLVER removeTiles: setting table");
-        context.facts.table = context.facts.table.filter(
-          (tile: Tile) => !req.tileIds.includes(tile.id),
-        );
-        addLog("RESOLVER removeTiles: setting removed");
-        context.facts.removed = [...context.facts.removed, ...tilesToRemove];
-        addLog("RESOLVER removeTiles: clearing selected");
-        context.facts.selected = [];
-        addLog("RESOLVER removeTiles: incrementing moveCount");
-        context.facts.moveCount++;
-        addLog("RESOLVER removeTiles: setting message");
-        context.facts.message = `Removed ${tilesToRemove[0].value} + ${tilesToRemove[1].value} = 10!`;
-        addLog("RESOLVER removeTiles: DONE");
-      },
-    },
-
-    refillTable: {
-      requirement: "REFILL_TABLE",
+    clamp: {
+      requirement: "CLAMP_TO_ZERO",
       resolve: async (req, context) => {
-        addLog(`RESOLVER refillTable: START (count: ${req.count})`);
-        const newTiles = context.facts.pool.slice(0, req.count);
-        context.facts.pool = context.facts.pool.slice(req.count);
-        context.facts.table = [...context.facts.table, ...newTiles];
-        addLog(
-          `RESOLVER refillTable: DONE (table now: ${context.facts.table.length})`,
-        );
-      },
-    },
-
-    endGame: {
-      requirement: "END_GAME",
-      resolve: async (req, context) => {
-        addLog(`RESOLVER endGame: ${req.reason}`);
-        context.facts.gameOver = true;
-        context.facts.message = req.reason;
+        context.facts.count = 0;
       },
     },
   },
 });
 
-// ============================================================================
-// System
-// ============================================================================
-
-export const system = createSystem({
-  module: numberMatch,
-  plugins: [devtoolsPlugin({ name: "number-match" })],
-  history: true,
-  trace: true,
-});
+export const system = createSystem({ module: counterModule });

package/examples/number-match.ts

@@ -0,0 +1,376 @@
+// Example: number-match
+// Source: examples/number-match/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Number Match — Directive Module
+ *
+ * Types, schema, helpers, module definition, timeline, and system creation
+ * for a tile-matching game where pairs must add to 10.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Tile {
+  id: string;
+  value: number;
+}
+
+export interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type: string;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+// Create a pool of numbered tiles (1-9, four of each = 36 tiles)
+function createPool(): Tile[] {
+  const tiles: Tile[] = [];
+  let id = 0;
+  for (let copy = 0; copy < 4; copy++) {
+    for (let value = 1; value <= 9; value++) {
+      tiles.push({ id: `t${id++}`, value });
+    }
+  }
+  // Shuffle
+  for (let i = tiles.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [tiles[i], tiles[j]] = [tiles[j], tiles[i]];
+  }
+
+  return tiles;
+}
+
+// ============================================================================
+// Timeline
+// ============================================================================
+
+export const timeline: TimelineEntry[] = [];
+
+export function addLog(msg: string) {
+  console.log(`[NumberMatch] ${msg}`);
+
+  // Classify and add significant events to the timeline
+  let event = "";
+  let detail = "";
+  let type = "info";
+
+  if (msg.startsWith("EVENT selectTile")) {
+    event = "tile selected";
+    const match = msg.match(/selectTile: (t\d+)/);
+    detail = match ? match[1] : "";
+    type = "selection";
+  } else if (msg.includes("pairAddsTen: TRUE")) {
+    event = "match found";
+    const match = msg.match(/\((.+)\)/);
+    detail = match ? match[1] : "";
+    type = "match";
+  } else if (msg === "RESOLVER removeTiles: DONE") {
+    event = "tiles removed";
+    detail = "";
+    type = "match";
+  } else if (msg.includes("refillTable: DONE")) {
+    event = "refill";
+    const match = msg.match(/table now: (\d+)/);
+    detail = match ? `table: ${match[1]} tiles` : "";
+    type = "refill";
+  } else if (msg.startsWith("RESOLVER endGame:")) {
+    event = "game over";
+    detail = msg.replace("RESOLVER endGame: ", "");
+    type = "gameover";
+  } else if (msg.includes("New game") || msg.includes("Game started")) {
+    event = "new game";
+    detail = msg;
+    type = "newgame";
+  } else {
+    // Skip verbose intermediate messages (RESOLVER steps, CONSTRAINT produce)
+    return;
+  }
+
+  timeline.unshift({ time: Date.now(), event, detail, type });
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const schema = {
+  facts: {
+    pool: t.array<Tile>(),
+    table: t.array<Tile>(),
+    removed: t.array<Tile>(),
+    selected: t.array<string>(),
+    message: t.string(),
+    moveCount: t.number(),
+    gameOver: t.boolean(),
+  },
+  derivations: {
+    poolCount: t.number(),
+    removedCount: t.number(),
+    selectedTiles: t.array<Tile>(),
+    hasValidMoves: t.boolean(),
+  },
+  events: {
+    newGame: {},
+    selectTile: { tileId: t.string() },
+    deselectTile: { tileId: t.string() },
+    clearSelection: {},
+  },
+  requirements: {
+    REMOVE_TILES: { tileIds: t.array<string>() },
+    REFILL_TABLE: { count: t.number() },
+    END_GAME: { reason: t.string() },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+const numberMatch = createModule("number-match", {
+  schema,
+
+  init: (facts) => {
+    const pool = createPool();
+    facts.pool = pool.slice(9);
+    facts.table = pool.slice(0, 9);
+    facts.removed = [];
+    facts.selected = [];
+    facts.message = "Select two numbers that add to 10";
+    facts.moveCount = 0;
+    facts.gameOver = false;
+  },
+
+  derive: {
+    poolCount: (facts) => facts.pool.length,
+    removedCount: (facts) => facts.removed.length,
+    selectedTiles: (facts) =>
+      facts.table.filter((tile: Tile) => facts.selected.includes(tile.id)),
+    hasValidMoves: (facts) => {
+      const nums = facts.table.map((t: Tile) => t.value);
+      for (let i = 0; i < nums.length; i++) {
+        for (let j = i + 1; j < nums.length; j++) {
+          if (nums[i] + nums[j] === 10) {
+            return true;
+          }
+        }
+      }
+
+      return false;
+    },
+  },
+
+  events: {
+    newGame: (facts) => {
+      const pool = createPool();
+      facts.pool = pool.slice(9);
+      facts.table = pool.slice(0, 9);
+      facts.removed = [];
+      facts.selected = [];
+      facts.message = "New game! Select two numbers that add to 10";
+      facts.moveCount = 0;
+      facts.gameOver = false;
+    },
+    selectTile: (facts, { tileId }) => {
+      if (!facts.selected.includes(tileId) && !facts.gameOver) {
+        facts.selected = [...facts.selected, tileId];
+        addLog(
+          `EVENT selectTile: ${tileId}, selected now: [${facts.selected}]`,
+        );
+      }
+    },
+    deselectTile: (facts, { tileId }) => {
+      facts.selected = facts.selected.filter((id: string) => id !== tileId);
+    },
+    clearSelection: (facts) => {
+      facts.selected = [];
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+  constraints: {
+    // When two selected tiles add to 10 -> remove them
+    pairAddsTen: {
+      priority: 100,
+      when: (facts) => {
+        if (facts.gameOver) {
+          return false;
+        }
+        const selected = facts.table.filter((tile: Tile) =>
+          facts.selected.includes(tile.id),
+        );
+        if (selected.length !== 2) {
+          return false;
+        }
+        const result = selected[0].value + selected[1].value === 10;
+        if (result) {
+          addLog(
+            `CONSTRAINT pairAddsTen: TRUE (${selected[0].value} + ${selected[1].value})`,
+          );
+        }
+
+        return result;
+      },
+      require: (facts) => {
+        addLog("CONSTRAINT pairAddsTen: producing REMOVE_TILES");
+
+        return {
+          type: "REMOVE_TILES",
+          tileIds: [...facts.selected],
+        };
+      },
+    },
+
+    // Refill table when tiles are removed
+    refillTable: {
+      priority: 50,
+      when: (facts) => {
+        const result =
+          !facts.gameOver && facts.table.length < 9 && facts.pool.length > 0;
+        if (result) {
+          addLog(
+            `CONSTRAINT refillTable: TRUE (table: ${facts.table.length}, pool: ${facts.pool.length})`,
+          );
+        }
+
+        return result;
+      },
+      require: (facts) => {
+        const count = Math.min(9 - facts.table.length, facts.pool.length);
+        addLog(`CONSTRAINT refillTable: producing REFILL_TABLE count=${count}`);
+
+        return { type: "REFILL_TABLE", count };
+      },
+    },
+
+    // No moves left -> game over
+    noMovesLeft: {
+      priority: 190,
+      when: (facts) => {
+        if (facts.gameOver) {
+          return false;
+        }
+        if (facts.table.length === 0) {
+          return false;
+        }
+        if (facts.pool.length > 0) {
+          return false;
+        }
+        const nums = facts.table.map((t: Tile) => t.value);
+        for (let i = 0; i < nums.length; i++) {
+          for (let j = i + 1; j < nums.length; j++) {
+            if (nums[i] + nums[j] === 10) {
+              return false;
+            }
+          }
+        }
+        addLog("CONSTRAINT noMovesLeft: TRUE");
+
+        return true;
+      },
+      require: (facts) => ({
+        type: "END_GAME",
+        reason: `Game over! Removed ${facts.removed.length} of 36 tiles.`,
+      }),
+    },
+
+    // Win condition
+    allCleared: {
+      priority: 200,
+      when: (facts) => {
+        const result =
+          !facts.gameOver &&
+          facts.table.length === 0 &&
+          facts.pool.length === 0;
+        if (result) {
+          addLog("CONSTRAINT allCleared: TRUE");
+        }
+
+        return result;
+      },
+      require: (facts) => ({
+        type: "END_GAME",
+        reason: `You win! Cleared all tiles in ${facts.moveCount} moves!`,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+  resolvers: {
+    removeTiles: {
+      requirement: "REMOVE_TILES",
+      resolve: async (req, context) => {
+        addLog("RESOLVER removeTiles: START");
+        const tilesToRemove = context.facts.table.filter((tile: Tile) =>
+          req.tileIds.includes(tile.id),
+        );
+
+        // Multiple fact mutations
+        addLog("RESOLVER removeTiles: setting table");
+        context.facts.table = context.facts.table.filter(
+          (tile: Tile) => !req.tileIds.includes(tile.id),
+        );
+        addLog("RESOLVER removeTiles: setting removed");
+        context.facts.removed = [...context.facts.removed, ...tilesToRemove];
+        addLog("RESOLVER removeTiles: clearing selected");
+        context.facts.selected = [];
+        addLog("RESOLVER removeTiles: incrementing moveCount");
+        context.facts.moveCount++;
+        addLog("RESOLVER removeTiles: setting message");
+        context.facts.message = `Removed ${tilesToRemove[0].value} + ${tilesToRemove[1].value} = 10!`;
+        addLog("RESOLVER removeTiles: DONE");
+      },
+    },
+
+    refillTable: {
+      requirement: "REFILL_TABLE",
+      resolve: async (req, context) => {
+        addLog(`RESOLVER refillTable: START (count: ${req.count})`);
+        const newTiles = context.facts.pool.slice(0, req.count);
+        context.facts.pool = context.facts.pool.slice(req.count);
+        context.facts.table = [...context.facts.table, ...newTiles];
+        addLog(
+          `RESOLVER refillTable: DONE (table now: ${context.facts.table.length})`,
+        );
+      },
+    },
+
+    endGame: {
+      requirement: "END_GAME",
+      resolve: async (req, context) => {
+        addLog(`RESOLVER endGame: ${req.reason}`);
+        context.facts.gameOver = true;
+        context.facts.message = req.reason;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  module: numberMatch,
+  plugins: [devtoolsPlugin({ name: "number-match" })],
+  history: true,
+  trace: true,
+});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@directive-run/knowledge",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Knowledge files, examples, and validation for Directive — the constraint-driven TypeScript runtime.",
-  "license": "MIT",
+  "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0",
-    "@directive-run/core": "0.8.2",
-    "@directive-run/ai": "0.8.2"
+    "@directive-run/core": "0.8.4",
+    "@directive-run/ai": "0.8.4"
   },
   "scripts": {
     "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/extract-examples.ts && tsup",