@directive-run/knowledge 0.5.0 → 0.7.0

package/core/anti-patterns.md

@@ -1,6 +1,6 @@
 # Anti-Patterns
 
-20 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
 
 ## 1. Unnecessary Type Casting on Facts/Derivations
 
@@ -155,23 +155,7 @@ const status = facts.auth.status;
 const token = facts.auth.token;
 ```
 
-## 11. Builder/Chaining API
-
-```typescript
-// WRONG – there is no builder pattern
-const mod = module("counter")
-  .schema({ count: t.number() })
-  .build();
-
-// CORRECT – use createModule with object syntax
-const mod = createModule("counter", {
-  schema: {
-    facts: { count: t.number() },
-  },
-});
-```
-
-## 12. Returning Data from Resolvers
+## 11. Returning Data from Resolvers
 
 ```typescript
 // WRONG – resolvers return void, not data
@@ -188,7 +172,7 @@ resolve: async (req, context) => {
 },
 ```
 
-## 13. Async Logic in `init`
+## 12. Async Logic in `init`
 
 ```typescript
 // WRONG – init is synchronous, facts assignment only
@@ -211,7 +195,7 @@ constraints: {
 },
 ```
 
-## 14. Missing `settle()` After `start()`
+## 13. Missing `settle()` After `start()`
 
 ```typescript
 // WRONG – constraints fire on start, resolvers are async
@@ -224,7 +208,7 @@ await system.settle();
 console.log(system.facts.data); // Resolved
 ```
 
-## 15. Missing `crossModuleDeps` Declaration
+## 14. Missing `crossModuleDeps` Declaration
 
 ```typescript
 // WRONG – accessing auth facts without declaring dependency
@@ -251,7 +235,7 @@ const dataModule = createModule("data", {
 });
 ```
 
-## 16. String Literal for `require`
+## 15. String Literal for `require`
 
 ```typescript
 // WRONG – require must be an object with type property
@@ -271,7 +255,7 @@ constraints: {
 },
 ```
 
-## 17. Passthrough Derivations
+## 16. Passthrough Derivations
 
 ```typescript
 // WRONG – derivation just returns a fact value unchanged
@@ -283,7 +267,7 @@ derive: {
 // system.facts.count instead of system.derive.count
 ```
 
-## 18. Deep Import Paths
+## 17. Deep Import Paths
 
 ```typescript
 // WRONG – internal module paths are not public API
@@ -297,7 +281,7 @@ import { createModule, createSystem } from "@directive-run/core";
 import { loggingPlugin } from "@directive-run/core/plugins";
 ```
 
-## 19. Async `when()` Without `deps`
+## 18. Async `when()` Without `deps`
 
 ```typescript
 // WRONG – async constraints need explicit deps for tracking
@@ -328,7 +312,7 @@ constraints: {
 },
 ```
 
-## 20. No Error Handling on Failing Resolvers
+## 19. No Error Handling on Failing Resolvers
 
 ```typescript
 // WRONG – unhandled errors crash the system

package/core/core-patterns.md

@@ -108,7 +108,7 @@ import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
 const system = createSystem({
   module: myModule,
   plugins: [loggingPlugin(), devtoolsPlugin()],
-  debug: { timeTravel: true, maxSnapshots: 100 },
+  history: { maxSnapshots: 100 },
 });
 
 // Multi-module – namespaced access: system.facts.auth.token

package/core/history.md

@@ -0,0 +1,344 @@
+# History & Snapshots
+
+Directive records fact changes as snapshots, enabling undo/redo, replay, export/import, and changeset grouping.
+
+## Decision Tree: "Should I enable history?"
+
+```
+What's the use case?
+├── Debugging during development → Yes, enable with maxSnapshots cap
+├── Production app → No, disable for performance
+├── Bug reproduction → Enable, use export() to share
+├── Testing → Usually no – use assertFact/assertDerivation instead
+└── Demo / presentation → Yes, great for showing state changes
+```
+
+## Enabling History
+
+```typescript
+import { createSystem } from "@directive-run/core";
+
+const system = createSystem({
+  module: myModule,
+  history: {
+    maxSnapshots: 100, // Cap memory usage (default: 100)
+  },
+});
+```
+
+History is disabled by default. When disabled, `system.history` is `null`. When enabled, snapshots are recorded automatically after every fact mutation.
+
+## Filtering Snapshot Events
+
+By default every event that changes facts creates a snapshot. Use `history.snapshotEvents` on your module to limit which events create snapshots — keeps undo/redo clean by excluding UI-only events like selection or timer ticks.
+
+```typescript
+const game = createModule("game", {
+  schema: gameSchema,
+
+  // Only these events appear in undo/redo history.
+  // Omit to snapshot ALL events (the default).
+  history: {
+    snapshotEvents: [
+      "inputNumber",
+      "requestHint",
+      "newGame",
+    ],
+  },
+
+  events: {
+    tick: (facts) => { /* no snapshot */ },
+    selectCell: (facts, { index }) => { /* no snapshot */ },
+    inputNumber: (facts, { value }) => { /* creates snapshot */ },
+    requestHint: (facts) => { /* creates snapshot */ },
+    newGame: (facts, { difficulty }) => { /* creates snapshot */ },
+  },
+});
+```
+
+### Filtering by Module
+
+In a multi-module system, control which modules create snapshots at the system level:
+
+```typescript
+const system = createSystem({
+  modules: { ui: uiModule, game: gameModule },
+  history: {
+    maxSnapshots: 100,
+    snapshotModules: ["game"], // Only game events create snapshots
+  },
+});
+```
+
+**Rules:**
+- `snapshotEvents` omitted → all events snapshot (per module)
+- `snapshotModules` omitted → all modules snapshot (per system)
+- Both provided → they intersect (module must be in `snapshotModules` AND event in `snapshotEvents`)
+- Direct fact mutations (`system.facts.x = 5`) always snapshot regardless of filtering
+- `snapshotEvents` entries are type-checked against schema events
+
+## Core API: `system.history` (`HistoryAPI`)
+
+```typescript
+const history = system.history; // HistoryAPI | null
+
+if (history) {
+  // Read-only state
+  history.snapshots;      // Snapshot[] — all recorded snapshots
+  history.currentIndex;   // number — position in the snapshot array
+  history.isPaused;       // boolean — whether recording is paused
+
+  // Navigation
+  history.goBack();       // Step backward one snapshot (changeset-aware)
+  history.goBack(3);      // Step backward 3 snapshots
+  history.goForward();    // Step forward one snapshot (changeset-aware)
+  history.goForward(3);   // Step forward 3 snapshots
+  history.goTo(snapshotId); // Jump to a specific snapshot by its ID
+  history.replay();       // Jump to the first snapshot
+
+  // Export / Import (JSON strings)
+  history.export();       // Serialize entire history to JSON string
+  history.import(json);   // Restore history from JSON string
+
+  // Changesets — group multiple snapshots into one undo/redo unit
+  history.beginChangeset("Move piece");
+  // ... mutations happen ...
+  history.endChangeset();
+
+  // Recording control
+  history.pause();        // Temporarily stop recording snapshots
+  history.resume();       // Resume recording
+}
+```
+
+### Snapshot Structure
+
+```typescript
+interface Snapshot {
+  id: number;                     // Auto-incrementing identifier
+  timestamp: number;              // When captured (Date.now())
+  facts: Record<string, unknown>; // Complete copy of all fact values
+  trigger: string;                // What caused this snapshot (e.g., "fact:count")
+}
+```
+
+## Framework Hook: `useHistory` (`HistoryState`)
+
+Each framework adapter provides a reactive `useHistory` hook that re-renders on snapshot changes. Returns `null` when history is disabled, otherwise a `HistoryState` object that wraps the core API with convenience properties.
+
+```typescript
+interface SnapshotMeta {
+  id: number;          // Snapshot identifier
+  timestamp: number;   // When captured
+  trigger: string;     // What caused this snapshot
+}
+
+interface HistoryState {
+  // Convenience booleans (not on core API)
+  canGoBack: boolean;    // True when currentIndex > 0
+  canGoForward: boolean; // True when currentIndex < totalSnapshots - 1
+  currentIndex: number;
+  totalSnapshots: number;
+
+  // Snapshot access (metadata only — keeps re-renders cheap)
+  snapshots: SnapshotMeta[];
+  getSnapshotFacts: (id: number) => Record<string, unknown> | null;
+
+  // Navigation
+  goTo: (snapshotId: number) => void;
+  goBack: (steps: number) => void;
+  goForward: (steps: number) => void;
+  replay: () => void;
+
+  // Session persistence
+  exportSession: () => string;     // Wraps history.export()
+  importSession: (json: string) => void; // Wraps history.import()
+
+  // Changesets
+  beginChangeset: (label: string) => void;
+  endChangeset: () => void;
+
+  // Recording control
+  isPaused: boolean;
+  pause: () => void;
+  resume: () => void;
+}
+```
+
+### React Example
+
+```tsx
+import { useHistory } from "@directive-run/react";
+
+function HistoryToolbar() {
+  const history = useHistory(system);
+  if (!history) return null;
+
+  return (
+    <div>
+      <button onClick={() => history.goBack()} disabled={!history.canGoBack}>Undo</button>
+      <button onClick={() => history.goForward()} disabled={!history.canGoForward}>Redo</button>
+      <span>{history.currentIndex + 1} / {history.totalSnapshots}</span>
+    </div>
+  );
+}
+```
+
+## Undo/Redo Pattern
+
+```typescript
+const system = createSystem({
+  module: editorModule,
+  history: { maxSnapshots: 200 },
+});
+
+system.start();
+
+// User makes changes
+system.facts.text = "Hello";
+system.facts.text = "Hello, world";
+system.facts.text = "Hello, world!";
+
+const history = system.history!;
+
+// Undo (one step back)
+history.goBack();
+console.log(system.facts.text); // "Hello, world"
+
+history.goBack();
+console.log(system.facts.text); // "Hello"
+
+// Redo (one step forward)
+history.goForward();
+console.log(system.facts.text); // "Hello, world"
+```
+
+## How Snapshots Work
+
+Snapshots are taken **once per reconciliation cycle**, not per individual fact change. All synchronous fact mutations within the same event handler batch into a single snapshot. One `goBack()` reverts all changes from that event.
+
+## Changesets: Grouping Multiple Events
+
+Changesets group snapshots from **multiple separate events** into one undo/redo unit. Useful when a single user action triggers a sequence of events.
+
+```typescript
+const history = system.history!;
+
+// Two separate events = two snapshots
+system.events.pickUp({ index: 0 });      // → snapshot 1
+system.events.place({ from: 0, to: 1 }); // → snapshot 2
+// goBack() only reverts the place — need two goBack() calls
+
+// With changeset — grouped into one undo unit
+history.beginChangeset("Move piece");
+system.events.pickUp({ index: 0 });      // → snapshot 1 ─┐
+system.events.place({ from: 0, to: 1 }); // → snapshot 2 ─┘ grouped
+history.endChangeset();
+// One goBack() reverts both events
+```
+
+Also works for direct fact mutations across separate synchronous blocks:
+
+```typescript
+history.beginChangeset("Update user");
+system.facts.firstName = "Alice";
+system.facts.lastName = "Smith";
+// These batch into one snapshot synchronously, but changeset
+// still works if an async gap separates them
+history.endChangeset();
+```
+
+Always close your changesets. If you forget `endChangeset()`, all subsequent mutations get grouped into the same changeset.
+
+## Exporting and Importing History
+
+Serialize the full snapshot history for bug reports or debugging.
+
+```typescript
+const history = system.history!;
+
+// Export — returns a JSON string
+const exported = history.export();
+localStorage.setItem("debug-session", exported);
+
+// Import — restore from a JSON string
+const saved = localStorage.getItem("debug-session");
+if (saved) {
+  history.import(saved);
+
+  // Step through the user's exact state sequence
+  history.goTo(0); // First snapshot
+  history.goTo(5); // When the bug occurred
+}
+```
+
+## Performance: maxSnapshots
+
+Every fact mutation creates a snapshot. Cap the number to control memory:
+
+```typescript
+// Low memory — keeps last 20 snapshots, discards oldest
+history: { maxSnapshots: 20 },
+
+// Development — generous cap for deep debugging
+history: { maxSnapshots: 500 },
+
+// Default if not specified
+history: true, // maxSnapshots defaults to 100
+```
+
+When the cap is reached, the oldest snapshot is discarded (ring buffer / FIFO).
+
+## Common Mistakes
+
+### Enabling history in production
+
+```typescript
+// WRONG — snapshots consume memory on every mutation
+const system = createSystem({
+  module: myModule,
+  history: true,
+});
+
+// CORRECT — gate on environment
+const system = createSystem({
+  module: myModule,
+  history: process.env.NODE_ENV === "development"
+    ? { maxSnapshots: 100 }
+    : false,
+});
+```
+
+### Forgetting to end a changeset
+
+```typescript
+// WRONG — changeset never closed, all subsequent mutations are grouped
+history.beginChangeset("update");
+system.facts.name = "Alice";
+// ... forgot endChangeset()
+system.facts.unrelated = true; // Still part of the changeset!
+
+// CORRECT — always close changesets
+history.beginChangeset("update");
+system.facts.name = "Alice";
+history.endChangeset();
+```
+
+### Accessing history when disabled
+
+```typescript
+// WRONG — history not enabled, system.history is null
+const system = createSystem({ module: myModule });
+system.history.goBack(); // TypeError!
+
+// CORRECT — check before using
+if (system.history) {
+  system.history.goBack();
+}
+
+// Or enable it
+const system = createSystem({
+  module: myModule,
+  history: true,
+});
+```

package/core/multi-module.md

@@ -277,7 +277,7 @@ const system = createSystem({
   // initOrder: ["auth", "data", "cart"], // Explicit order
 
   plugins: [loggingPlugin()],
-  debug: { timeTravel: true },
+  history: true,
 });
 
 // Hydrate from async source (call before start)

package/core/react-adapter.md

@@ -129,7 +129,7 @@ function GameBoard() {
   // System created on mount, destroyed on unmount
   const gameSystem = useSystem({
     module: gameModule,
-    debug: { timeTravel: true },
+    history: true,
   });
 
   const score = useSelector(gameSystem, (s) => s.facts.score);

package/core/system-api.md

@@ -27,7 +27,7 @@ import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
 const system = createSystem({
   module: myModule,
   plugins: [loggingPlugin(), devtoolsPlugin()],
-  debug: { timeTravel: true, maxSnapshots: 100 },
+  history: { maxSnapshots: 100 },
 });
 
 // Multi-module – namespaced access
@@ -212,6 +212,120 @@ system.constraints.isDisabled("fetchWhenReady"); // true
 system.constraints.enable("fetchWhenReady");
 ```
 
+## SSR and Hydration
+
+Four mechanisms for populating a system with external state:
+
+```typescript
+// 1. initialFacts – simplest, at construction time
+const system = createSystem({
+  module: myModule,
+  initialFacts: { userId: "user-1", name: "Alice" },
+});
+system.start();
+
+// 2. system.hydrate() – async, before start()
+const system = createSystem({ module: myModule });
+await system.hydrate(async () => {
+  const res = await fetch('/api/state');
+
+  return res.json();
+});
+system.start();
+
+// 3. system.restore() – sync, applies facts from a snapshot
+const system = createSystem({ module: myModule });
+system.restore(serverSnapshot);
+system.start();
+
+// 4. DirectiveHydrator + useHydratedSystem (React only)
+// Server: getDistributableSnapshot() → serialize
+// Client: <DirectiveHydrator snapshot={s}><App /></DirectiveHydrator>
+//         useHydratedSystem(module) inside App
+```
+
+### SSR Lifecycle
+
+```typescript
+// Server: create → start → settle → snapshot → destroy
+const system = createSystem({
+  module: pageModule,
+  initialFacts: { userId: req.user.id },
+});
+system.start();
+await system.settle(5000); // Throws on timeout
+const snapshot = system.getSnapshot();
+system.stop();
+system.destroy();
+```
+
+### Snapshot Types
+
+- `SystemSnapshot` – facts only, used with `getSnapshot()` / `restore()`
+- `DistributableSnapshot` – facts + derivations + metadata + TTL, used with `getDistributableSnapshot()` and `DirectiveHydrator`
+
+### Avoiding Singletons
+
+Never use module-level systems in SSR – they share state across concurrent requests. Always create a fresh system per request and destroy it when done.
+
+## Runtime Dynamics
+
+All four subsystems (constraints, resolvers, derivations, effects) share a uniform dynamic definition interface:
+
+### Enable / Disable (Constraints & Effects only)
+
+```typescript
+system.constraints.disable("id");
+system.constraints.enable("id");
+system.constraints.isDisabled("id");
+
+system.effects.disable("id");
+system.effects.enable("id");
+system.effects.isEnabled("id");
+```
+
+### Register / Assign / Unregister (All 4 subsystems)
+
+```typescript
+// Register a new definition at runtime
+system.constraints.register("id", { when: ..., require: ... });
+system.resolvers.register("id", { requirement: "TYPE", resolve: ... });
+system.derive.register("id", (facts) => facts.count * 3);
+system.effects.register("id", { run: (facts) => { ... } });
+
+// Override an existing definition
+system.constraints.assign("id", { when: ..., require: ... });
+
+// Remove a dynamically registered definition (static = no-op + dev warning)
+system.constraints.unregister("id");
+```
+
+Semantics: `register` throws if ID exists. `assign` throws if ID doesn't exist. `unregister` on static ID = dev warning, no-op. All three are deferred if called during reconciliation.
+
+### Introspection
+
+```typescript
+system.constraints.isDynamic("id");  // true if registered at runtime
+system.constraints.listDynamic();    // all dynamic constraint IDs
+```
+
+### getOriginal / restoreOriginal
+
+When `assign()` overrides a static definition, the original is saved:
+
+```typescript
+system.getOriginal("constraint", "id");    // returns original definition
+system.restoreOriginal("constraint", "id"); // restores it, returns true/false
+```
+
+### Dynamic Module Registration
+
+```typescript
+system.registerModule("chat", chatModule); // adds module to running system
+```
+
+See docs: https://directive.run/docs/advanced/runtime
+
 ## Common Mistakes
 
 ### Reading facts before settling

package/examples/ab-testing.ts

@@ -308,6 +308,6 @@ const abTesting = createModule("ab-testing", {
 
 export const system = createSystem({
   module: abTesting,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "ab-testing" })],
 });

package/examples/ai-checkpoint.ts

@@ -238,7 +238,7 @@ const pipelineModule = createModule("pipeline", {
 
 export const system = createSystem({
   module: pipelineModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "ai-checkpoint" })],
 });
 

package/examples/ai-guardrails.ts

@@ -161,7 +161,7 @@ const guardrailModule = createModule("guardrails", {
 
 export const system = createSystem({
   module: guardrailModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "ai-guardrails" })],
 });
 

package/examples/batch-resolver.ts

@@ -296,6 +296,6 @@ const batchModule = createModule("batch-loader", {
 
 export const system = createSystem({
   module: batchModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "batch-resolver" })],
 });

package/examples/checkers.ts

@@ -43,11 +43,14 @@ import {
 import type { CacheStats } from "@directive-run/ai";
 import {
   type CircuitState,
-  createAgentMetrics,
   createCircuitBreaker,
   createOTLPExporter,
-  createObservability,
 } from "@directive-run/core/plugins";
+// createObservability is alpha (not in bundle) — direct source import
+import {
+  createObservability,
+  createAgentMetrics,
+} from "../../../packages/core/src/plugins/observability.lab.js";
 import {
   analysisAgent,
   chatAgent,

package/examples/contact-form.ts

@@ -322,6 +322,6 @@ const contactForm = createModule("contact-form", {
 
 export const system = createSystem({
   module: contactForm,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "contact-form" })],
 });

package/examples/counter.ts

@@ -371,5 +371,6 @@ const numberMatch = createModule("number-match", {
 export const system = createSystem({
   module: numberMatch,
   plugins: [devtoolsPlugin({ name: "number-match" })],
-  debug: { timeTravel: true, runHistory: true },
+  history: true,
+  trace: true,
 });

package/examples/debounce-constraints.ts

@@ -13,6 +13,7 @@
 
 import { createSystem } from "@directive-run/core";
 import { devtoolsPlugin } from "@directive-run/core/plugins";
+import { el } from "@directive-run/el";
 import {
   debounceSearchModule,
   debounceSearchSchema,
@@ -24,7 +25,7 @@ import {
 
 const system = createSystem({
   module: debounceSearchModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "debounce-constraints" })],
 });
 system.start();
@@ -85,15 +86,6 @@ const tickInterval = setInterval(() => {
 // Sliders
 
 
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function escapeHtml(text: string): string {
-
-  return div.innerHTML;
-}
-
 // ============================================================================
 // Initial Render
 // ============================================================================

package/examples/error-boundaries.ts

@@ -344,7 +344,7 @@ let currentStrategy: RecoveryStrategy = "retry-later";
 
 export const system = createSystem({
   module: dashboardModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [perf, devtoolsPlugin({ name: "error-boundaries" })],
   errorBoundary: {
     onResolverError: (_error, resolver) => {

package/examples/form-wizard.ts

@@ -329,7 +329,7 @@ export const system = createSystem({
     wizard: wizardModule,
     validation: validationModule,
   },
-  debug: { runHistory: true },
+  trace: true,
   plugins: [
     devtoolsPlugin({ name: "form-wizard" }),
     persistencePlugin({

package/examples/fraud-analysis.ts

@@ -646,12 +646,8 @@ export const fraudAnalysisModule = createModule("fraud", {
 export const system = createSystem({
   module: fraudAnalysisModule,
   plugins: [devtoolsPlugin({ name: "fraud-analysis", panel: true })],
-  debug: {
-    timeTravel: true,
-    maxSnapshots: 50,
-    runHistory: true,
-    maxRuns: 100,
-  },
+  history: { maxSnapshots: 50 },
+  trace: { maxRuns: 100 },
 });
 
 // ============================================================================

package/examples/multi-module.ts

@@ -15,6 +15,7 @@
  * - No asCombined() helper needed
  */
 
+import { el } from "@directive-run/el";
 import { getFacts, system } from "./system";
 
 // DOM Elements

package/examples/newsletter.ts

@@ -209,6 +209,6 @@ const newsletter = createModule("newsletter", {
 
 export const system = createSystem({
   module: newsletter,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "newsletter" })],
 });

package/examples/pagination.ts

@@ -255,6 +255,6 @@ export const listModule = createModule("list", {
 
 export const system = createSystem({
   modules: { filters: filtersModule, list: listModule },
-  debug: { runHistory: true },
+  trace: true,
   plugins: [loggingPlugin(), devtoolsPlugin({ name: "pagination" })],
 });

package/examples/permissions.ts

@@ -322,6 +322,6 @@ export const system = createSystem({
     permissions: permissionsModule,
     content: contentModule,
   },
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "permissions" })],
 });

package/examples/provider-routing.ts

@@ -221,7 +221,7 @@ const routerModule = createModule("router", {
 
 export const system = createSystem({
   module: routerModule,
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "provider-routing" })],
 });
 

package/examples/shopping-cart.ts

@@ -414,9 +414,6 @@ export const system = createSystem({
     auth: authModule,
   },
   plugins: [devtoolsPlugin({ name: "shopping-cart", panel: true })],
-  debug: {
-    timeTravel: true,
-    maxSnapshots: 50,
-    runHistory: true,
-  },
+  history: { maxSnapshots: 50 },
+  trace: true,
 });

package/examples/sudoku.ts

@@ -109,7 +109,14 @@ export const sudokuSchema = {
 
 export const sudokuGame = createModule("sudoku", {
   schema: sudokuSchema,
-  snapshotEvents: ["inputNumber", "toggleNote", "requestHint", "newGame"],
+  history: {
+    snapshotEvents: [
+      "inputNumber",
+      "toggleNote",
+      "requestHint",
+      "newGame",
+    ],
+  },
 
   init: (facts) => {
     const { puzzle, solution } = generatePuzzle("easy");

package/examples/time-machine.ts

@@ -142,6 +142,7 @@ const canvasModule = createModule("canvas", {
 
 export const system = createSystem({
   module: canvasModule,
-  debug: { timeTravel: true, maxSnapshots: 200, runHistory: true },
+  history: { maxSnapshots: 200 },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "time-machine" })],
 });

package/examples/url-sync.ts

@@ -328,6 +328,6 @@ export const system = createSystem({
     url: urlModule,
     products: productsModule,
   },
-  debug: { runHistory: true },
+  trace: true,
   plugins: [devtoolsPlugin({ name: "url-sync" })],
 });

package/package.json

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

package/core/time-travel.md

@@ -1,238 +0,0 @@
-# Time-Travel Debugging
-
-Directive can record every fact change as a snapshot, enabling undo/redo, replay, and state export for bug reports.
-
-## Decision Tree: "Should I enable time-travel?"
-
-```
-What's the use case?
-├── Debugging during development → Yes, enable with maxSnapshots cap
-├── Production app → No, disable for performance
-├── Bug reproduction → Enable, use exportHistory() to share
-├── Testing → Usually no – use assertFact/assertDerivation instead
-└── Demo / presentation → Yes, great for showing state changes
-```
-
-## Enabling Time-Travel
-
-```typescript
-import { createSystem } from "@directive-run/core";
-
-const system = createSystem({
-  module: myModule,
-  debug: {
-    timeTravel: true,       // Enable snapshot recording
-    maxSnapshots: 100,      // Cap memory usage (default: 50)
-  },
-});
-```
-
-Time-travel is disabled by default. Snapshots are recorded automatically on every fact mutation.
-
-## The TimeTravelAPI
-
-Access via `system.debug.timeTravel`:
-
-```typescript
-const tt = system.debug.timeTravel;
-
-// Navigation
-tt.canUndo();           // boolean – is there a previous snapshot?
-tt.canRedo();           // boolean – is there a next snapshot?
-tt.undo();              // Restore previous snapshot
-tt.redo();              // Restore next snapshot
-
-// Direct access
-tt.getSnapshots();      // Array of all snapshots
-tt.goToSnapshot(index); // Jump to a specific snapshot by index
-
-// Each snapshot contains:
-// {
-//   facts: { ... },        – full fact state at that point
-//   timestamp: number,     – when the snapshot was taken
-//   label?: string,        – optional label from changeset
-//   changedKeys: string[], – which facts changed
-// }
-```
-
-## Undo/Redo Pattern
-
-```typescript
-const system = createSystem({
-  module: editorModule,
-  debug: { timeTravel: true, maxSnapshots: 200 },
-});
-
-system.start();
-
-// User makes changes
-system.facts.text = "Hello";
-system.facts.text = "Hello, world";
-system.facts.text = "Hello, world!";
-
-// Undo last change
-const tt = system.debug.timeTravel;
-tt.undo();
-console.log(system.facts.text); // "Hello, world"
-
-tt.undo();
-console.log(system.facts.text); // "Hello"
-
-// Redo
-tt.redo();
-console.log(system.facts.text); // "Hello, world"
-
-// Check navigation state
-tt.canUndo(); // true
-tt.canRedo(); // true
-```
-
-## Changesets: Grouping Related Changes
-
-Multiple fact mutations can be grouped into a single undoable unit.
-
-```typescript
-const tt = system.debug.timeTravel;
-
-// Without changeset – each mutation is a separate snapshot
-system.facts.firstName = "Alice";
-system.facts.lastName = "Smith";
-// Two snapshots, two undos needed
-
-// With changeset – grouped into one snapshot
-tt.beginChangeset("Update user name");
-system.facts.firstName = "Alice";
-system.facts.lastName = "Smith";
-tt.endChangeset();
-// One snapshot, one undo restores both
-
-// Undo reverts the entire changeset
-tt.undo();
-// Both firstName and lastName are restored
-```
-
-Use changesets for logically related mutations: form submissions, multi-field updates, resolver results.
-
-## Exporting and Importing History
-
-Serialize the full snapshot history for bug reports or debugging.
-
-```typescript
-const tt = system.debug.timeTravel;
-
-// Export – returns a serializable object
-const historyData = tt.exportHistory();
-// Send to server, save to file, attach to bug report
-console.log(JSON.stringify(historyData));
-
-// Import – restore history from exported data
-tt.importHistory(historyData);
-
-// Now you can step through the user's exact state sequence
-tt.goToSnapshot(0); // Start
-tt.goToSnapshot(5); // When the bug occurred
-```
-
-## Snapshot Inspection
-
-```typescript
-const tt = system.debug.timeTravel;
-const snapshots = tt.getSnapshots();
-
-// Walk through all snapshots
-for (const snap of snapshots) {
-  console.log(`[${new Date(snap.timestamp).toISOString()}]`);
-  console.log(`  Changed: ${snap.changedKeys.join(", ")}`);
-  if (snap.label) {
-    console.log(`  Label: ${snap.label}`);
-  }
-  console.log(`  Facts:`, snap.facts);
-}
-
-// Jump to a specific point
-tt.goToSnapshot(3);
-console.log(system.facts); // State as of snapshot 3
-```
-
-## Performance: maxSnapshots
-
-Every fact mutation creates a snapshot. Cap the number to control memory:
-
-```typescript
-// Low memory – keeps last 20 snapshots, discards oldest
-debug: { timeTravel: true, maxSnapshots: 20 },
-
-// Development – generous cap for deep debugging
-debug: { timeTravel: true, maxSnapshots: 500 },
-
-// Default if not specified
-debug: { timeTravel: true }, // maxSnapshots defaults to 50
-```
-
-When the cap is reached, the oldest snapshot is discarded (FIFO). Redo history beyond the cap is lost.
-
-## Common Mistakes
-
-### Enabling time-travel in production
-
-```typescript
-// WRONG – snapshots consume memory on every mutation
-const system = createSystem({
-  module: myModule,
-  debug: { timeTravel: true },
-});
-
-// CORRECT – gate on environment
-const system = createSystem({
-  module: myModule,
-  debug: {
-    timeTravel: process.env.NODE_ENV === "development",
-    maxSnapshots: 100,
-  },
-});
-```
-
-### Forgetting to end a changeset
-
-```typescript
-// WRONG – changeset never closed, all subsequent mutations are grouped
-tt.beginChangeset("update");
-system.facts.name = "Alice";
-// ... forgot endChangeset()
-system.facts.unrelated = true; // Still part of the changeset!
-
-// CORRECT – always close changesets
-tt.beginChangeset("update");
-system.facts.name = "Alice";
-tt.endChangeset();
-```
-
-### Accessing time-travel when disabled
-
-```typescript
-// WRONG – timeTravel not enabled, system.debug.timeTravel is null
-const system = createSystem({ module: myModule });
-system.debug.timeTravel.undo(); // TypeError!
-
-// CORRECT – check before using
-const tt = system.debug.timeTravel;
-if (tt) {
-  tt.undo();
-}
-
-// Or enable it
-const system = createSystem({
-  module: myModule,
-  debug: { timeTravel: true },
-});
-```
-
-### No maxSnapshots cap with frequent mutations
-
-```typescript
-// WRONG – unbounded snapshots in a high-frequency update loop
-debug: { timeTravel: true }, // Default cap is 50, which is fine
-
-// Be explicit when mutation rate is high
-debug: { timeTravel: true, maxSnapshots: 30 },
-```