@directive-run/knowledge 0.2.0

package/core/plugins.md

@@ -0,0 +1,344 @@
+# Plugins
+
+Plugins extend Directive systems with cross-cutting functionality like logging, persistence, devtools, and resilience patterns.
+
+## Decision Tree: "Which plugin do I need?"
+
+```
+What do you want?
+├── See state changes in console → loggingPlugin()
+├── Connect to browser DevTools → devtoolsPlugin()
+├── Persist state across reloads → persistencePlugin(config)
+├── Protect resolvers from cascading failures → createCircuitBreaker(config)
+├── Track metrics, traces, alerts → createObservability(config)
+└── Custom cross-cutting behavior → Write a custom plugin
+```
+
+## Using Built-In Plugins
+
+```typescript
+import { createSystem } from "@directive-run/core";
+import {
+  devtoolsPlugin,
+  loggingPlugin,
+  persistencePlugin,
+} from "@directive-run/core/plugins";
+
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    devtoolsPlugin(),
+    loggingPlugin({ verbose: true }),
+    persistencePlugin({
+      key: "my-app-state",
+      storage: localStorage,
+    }),
+  ],
+});
+```
+
+Plugins are applied in order. Place logging first to capture all events including those from other plugins.
+
+## loggingPlugin
+
+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
+loggingPlugin()
+
+// Verbose — logs everything including derivation recomputation and constraint evaluation
+loggingPlugin({ verbose: true })
+
+// Custom filter — only log specific events
+loggingPlugin({
+  filter: (event) => {
+    // Only log resolver events
+    if (event.type === "resolution:start" || event.type === "resolution:complete") {
+      return true;
+    }
+
+    return false;
+  },
+})
+```
+
+## devtoolsPlugin
+
+Connects to the Directive DevTools browser extension for visual state inspection.
+
+```typescript
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// Default
+devtoolsPlugin()
+
+// With options
+devtoolsPlugin({
+  name: "My App",        // Name shown in DevTools
+  maxAge: 50,            // Max actions to keep in history
+})
+```
+
+Only enable in development. The plugin is a no-op if the DevTools extension is not installed.
+
+## persistencePlugin
+
+Persists fact state to storage. Restores on system creation.
+
+```typescript
+import { persistencePlugin } from "@directive-run/core/plugins";
+
+// localStorage (default)
+persistencePlugin({
+  key: "my-app-state",
+  storage: localStorage,
+})
+
+// sessionStorage — cleared when tab closes
+persistencePlugin({
+  key: "session-state",
+  storage: sessionStorage,
+})
+
+// Custom storage adapter
+persistencePlugin({
+  key: "my-app",
+  storage: {
+    getItem: (key) => myCustomStore.get(key),
+    setItem: (key, value) => myCustomStore.set(key, value),
+    removeItem: (key) => myCustomStore.delete(key),
+  },
+})
+
+// Selective persistence — only persist certain facts
+persistencePlugin({
+  key: "my-app",
+  storage: localStorage,
+  include: ["user", "preferences"],  // Only these facts
+  // OR
+  exclude: ["tempData", "sessionId"], // Everything except these
+})
+
+// Versioning — handle schema changes
+persistencePlugin({
+  key: "my-app",
+  storage: localStorage,
+  version: 2,
+  migrate: (oldState, oldVersion) => {
+    if (oldVersion === 1) {
+      return {
+        ...oldState,
+        newField: "default",
+      };
+    }
+
+    return oldState;
+  },
+})
+```
+
+## createCircuitBreaker
+
+Wraps resolvers with circuit breaker pattern for resilience.
+
+```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"],
+
+      // Optional: callback when circuit opens
+      onOpen: (resolverType) => {
+        console.warn(`Circuit opened for ${resolverType}`);
+      },
+
+      // Optional: callback when circuit closes
+      onClose: (resolverType) => {
+        console.log(`Circuit closed for ${resolverType}`);
+      },
+    }),
+  ],
+});
+```
+
+Circuit breaker states: **Closed** (normal) -> **Open** (failing, rejects immediately) -> **Half-Open** (testing one request).
+
+## createObservability
+
+Metrics, tracing, and alerting for production systems.
+
+```typescript
+import { createObservability } from "@directive-run/core/plugins";
+
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    createObservability({
+      metrics: {
+        enabled: true,
+        // Track resolver duration, constraint evaluation count, etc.
+      },
+      tracing: {
+        enabled: true,
+        // Trace resolver execution with spans
+      },
+      alerts: {
+        enabled: true,
+        onAlert: (alert) => {
+          // Send to monitoring service
+          sendToDatadog(alert);
+        },
+      },
+    }),
+  ],
+});
+```
+
+## Plugin Lifecycle Hooks
+
+Plugins hook into the system lifecycle. Use these to build custom plugins.
+
+```typescript
+import type { DirectivePlugin } from "@directive-run/core";
+
+const myPlugin: DirectivePlugin = {
+  name: "my-custom-plugin",
+
+  // System lifecycle
+  onInit: (system) => {
+    // Called when system is created
+  },
+  onStart: (system) => {
+    // Called when system.start() is invoked
+  },
+  onStop: (system) => {
+    // Called when system.stop() is invoked
+  },
+
+  // State tracking
+  onSnapshot: (snapshot) => {
+    // Called after every fact mutation
+    // snapshot.facts contains current state
+    // snapshot.changedKeys lists what changed
+  },
+
+  // Requirement pipeline
+  onRequirementEmitted: (requirement) => {
+    // Called when a constraint emits a requirement
+    // requirement.type, requirement.id, payload
+  },
+  onResolutionStart: (resolution) => {
+    // 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?
+  },
+
+  // Error handling
+  onError: (error, context) => {
+    // Called on any error in the system
+    // context.source: "resolver" | "constraint" | "effect" | "derivation"
+  },
+};
+
+const system = createSystem({
+  module: myModule,
+  plugins: [myPlugin],
+});
+```
+
+## Common Mistakes
+
+### Enabling devtools in production
+
+```typescript
+// WRONG — devtools overhead in production
+const system = createSystem({
+  module: myModule,
+  plugins: [devtoolsPlugin()],
+});
+
+// CORRECT — conditional on environment
+const plugins = [];
+if (process.env.NODE_ENV === "development") {
+  plugins.push(devtoolsPlugin());
+  plugins.push(loggingPlugin({ verbose: true }));
+}
+
+const system = createSystem({
+  module: myModule,
+  plugins,
+});
+```
+
+### Persistence without versioning
+
+```typescript
+// WRONG — schema changes break existing users
+persistencePlugin({
+  key: "app-state",
+  storage: localStorage,
+})
+
+// CORRECT — version and migrate
+persistencePlugin({
+  key: "app-state",
+  storage: localStorage,
+  version: 1,
+  migrate: (old, version) => old,
+})
+```
+
+### Plugin order matters
+
+```typescript
+// WRONG — logging misses events from persistence restore
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    persistencePlugin({ key: "app", storage: localStorage }),
+    loggingPlugin(), // Misses restore events
+  ],
+});
+
+// CORRECT — logging first to capture everything
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    loggingPlugin(),
+    persistencePlugin({ key: "app", storage: localStorage }),
+  ],
+});
+```
+
+### Persisting sensitive or transient data
+
+```typescript
+// WRONG — persists auth tokens and loading state
+persistencePlugin({
+  key: "app",
+  storage: localStorage,
+})
+
+// CORRECT — exclude sensitive and transient facts
+persistencePlugin({
+  key: "app",
+  storage: localStorage,
+  exclude: ["authToken", "isLoading", "error"],
+})
+```

package/core/react-adapter.md

@@ -0,0 +1,262 @@
+# React Adapter
+
+The React adapter connects Directive systems to React components. Import from `@directive-run/react`.
+
+## Decision Tree: "How do I use Directive in React?"
+
+```
+What are you building?
+├── Read system state in a component → useSelector(system, selector)
+├── Dispatch events from a component → useEvent(system)
+├── Create a system scoped to a component → useSystem(config)
+├── Share a system across components → DirectiveProvider + useDirectiveContext()
+└── Global system shared by entire app → Create outside React, use useSelector
+```
+
+## Setup: System Outside React (Recommended)
+
+Create the system outside of React. Components subscribe to it.
+
+```typescript
+// system.ts — created once, imported anywhere
+import { createSystem } from "@directive-run/core";
+import { counterModule } from "./counter-module";
+
+export const system = createSystem({ module: counterModule });
+```
+
+```typescript
+// Counter.tsx
+import { useSelector, useEvent } from "@directive-run/react";
+import { system } from "./system";
+
+function Counter() {
+  // Subscribe to derived state — re-renders only when value changes
+  const count = useSelector(system, (s) => s.facts.count);
+  const doubled = useSelector(system, (s) => s.derive.doubled);
+
+  // Get event dispatcher
+  const events = useEvent(system);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <p>Doubled: {doubled}</p>
+      <button onClick={() => events.increment()}>+1</button>
+      <button onClick={() => events.reset()}>Reset</button>
+    </div>
+  );
+}
+```
+
+## useSelector
+
+Subscribes to system state. Re-renders the component only when the selected value changes (shallow comparison).
+
+```typescript
+import { useSelector } from "@directive-run/react";
+
+function UserProfile() {
+  // Select a single fact
+  const name = useSelector(system, (s) => s.facts.userName);
+
+  // Select a derivation
+  const isAdmin = useSelector(system, (s) => s.derive.isAdmin);
+
+  // Select a computed value from multiple facts
+  const summary = useSelector(system, (s) => ({
+    name: s.facts.userName,
+    role: s.facts.role,
+    isAdmin: s.derive.isAdmin,
+  }));
+
+  return <div>{summary.name} ({summary.role})</div>;
+}
+```
+
+### Multi-Module System
+
+```typescript
+const system = createSystem({
+  modules: { auth: authModule, cart: cartModule },
+});
+
+function Header() {
+  const token = useSelector(system, (s) => s.facts.auth.token);
+  const itemCount = useSelector(system, (s) => s.derive.cart.itemCount);
+
+  return <header>Items: {itemCount}</header>;
+}
+```
+
+## useEvent
+
+Returns the system's event dispatcher. Stable reference (does not cause re-renders).
+
+```typescript
+import { useEvent } from "@directive-run/react";
+
+function LoginForm() {
+  const events = useEvent(system);
+
+  const handleSubmit = (email: string, password: string) => {
+    events.login({ email, password });
+  };
+
+  return <form onSubmit={() => handleSubmit("a@b.com", "pass")}>...</form>;
+}
+
+// Multi-module
+function CartActions() {
+  const events = useEvent(system);
+
+  return (
+    <button onClick={() => events.cart.addItem({ productId: "p1" })}>
+      Add to Cart
+    </button>
+  );
+}
+```
+
+## useSystem
+
+Creates and manages a system's lifecycle within a React component. The system is created on mount and destroyed on unmount.
+
+```typescript
+import { useSystem, useSelector, useEvent } from "@directive-run/react";
+
+function GameBoard() {
+  // System created on mount, destroyed on unmount
+  const gameSystem = useSystem({
+    module: gameModule,
+    debug: { timeTravel: true },
+  });
+
+  const score = useSelector(gameSystem, (s) => s.facts.score);
+  const events = useEvent(gameSystem);
+
+  return (
+    <div>
+      <p>Score: {score}</p>
+      <button onClick={() => events.move({ direction: "up" })}>Up</button>
+    </div>
+  );
+}
+```
+
+Use `useSystem` when the system's lifecycle matches a component's lifecycle (e.g., a game board, a wizard, a modal form). For app-wide state, create the system outside React.
+
+## DirectiveProvider and useDirectiveContext
+
+Share a system through React context.
+
+```typescript
+import { DirectiveProvider, useDirectiveContext, useSelector, useEvent } from "@directive-run/react";
+
+// Provide the system at the top of your tree
+function App() {
+  return (
+    <DirectiveProvider system={system}>
+      <Dashboard />
+    </DirectiveProvider>
+  );
+}
+
+// Consume the system anywhere below
+function Dashboard() {
+  const system = useDirectiveContext();
+  const stats = useSelector(system, (s) => s.derive.dashboardStats);
+
+  return <div>{stats.totalUsers} users</div>;
+}
+```
+
+## CRITICAL: Hooks That DO NOT Exist
+
+```typescript
+// WRONG — useDirective() does not exist. This is a common hallucination.
+const { facts, derive, events } = useDirective(system);
+
+// CORRECT — use useSelector for state, useEvent for actions
+const count = useSelector(system, (s) => s.facts.count);
+const events = useEvent(system);
+```
+
+## Common Mistakes
+
+### Creating the system inside a component without useSystem
+
+```typescript
+// WRONG — creates a new system on every render
+function Counter() {
+  const system = createSystem({ module: counterModule }); // New system each render!
+  const count = useSelector(system, (s) => s.facts.count);
+
+  return <div>{count}</div>;
+}
+
+// CORRECT — create outside the component
+const system = createSystem({ module: counterModule });
+
+function Counter() {
+  const count = useSelector(system, (s) => s.facts.count);
+
+  return <div>{count}</div>;
+}
+
+// ALSO CORRECT — useSystem manages lifecycle
+function Counter() {
+  const system = useSystem({ module: counterModule });
+  const count = useSelector(system, (s) => s.facts.count);
+
+  return <div>{count}</div>;
+}
+```
+
+### Selecting too much state (causes unnecessary re-renders)
+
+```typescript
+// WRONG — re-renders on ANY fact change
+const allFacts = useSelector(system, (s) => s.facts);
+
+// CORRECT — select only what you need
+const name = useSelector(system, (s) => s.facts.userName);
+const count = useSelector(system, (s) => s.facts.count);
+```
+
+### Mutating facts directly in event handlers
+
+```typescript
+// WRONG — bypass the event system
+function Counter() {
+  const count = useSelector(system, (s) => s.facts.count);
+
+  return (
+    <button onClick={() => { system.facts.count += 1; }}>
+      {count}
+    </button>
+  );
+}
+
+// CORRECT — use events for intent-driven mutations
+function Counter() {
+  const count = useSelector(system, (s) => s.facts.count);
+  const events = useEvent(system);
+
+  return (
+    <button onClick={() => events.increment()}>
+      {count}
+    </button>
+  );
+}
+```
+
+### Casting values from useSelector
+
+```typescript
+// WRONG — unnecessary type casting
+const profile = useSelector(system, (s) => s.facts.profile as UserProfile);
+
+// CORRECT — types are inferred from the module schema
+const profile = useSelector(system, (s) => s.facts.profile);
+```