@directive-run/knowledge 1.13.0 → 1.15.0

package/core/react-adapter.md

@@ -1,294 +1,370 @@
 # React Adapter
 
+> Covers `@directive-run/react` — `useFact`, `useDerived`, `useEvents`, `useSelector`, `useDirective`, `createDirectiveContext`.
+
 The React adapter connects Directive systems to React components. Import from `@directive-run/react`.
 
-## Decision Tree: "How do I use Directive in React?"
+## Canonical pattern: `createDirectiveContext`
+
+This is the recommended way to use Directive in React. One call returns a typed `Provider` plus bound hooks — no system arg needed at every call site, no `useContext` boilerplate, full type inference from the schema.
+
+```tsx
+// counter-context.ts — create once, import everywhere
+import { createSystem } from "@directive-run/core";
+import { createDirectiveContext } from "@directive-run/react";
+import { counterModule } from "./counter-module";
+
+export const counterSystem = createSystem({ module: counterModule });
+export const Counter = createDirectiveContext(counterSystem);
+```
+
+```tsx
+// App.tsx
+import { Counter } from "./counter-context";
+import { Display } from "./Display";
+
+export function App() {
+  return (
+    <Counter.Provider>
+      <Display />
+    </Counter.Provider>
+  );
+}
+```
+
+```tsx
+// Display.tsx
+import { Counter } from "./counter-context";
 
+export function Display() {
+  const count = Counter.useFact("count");
+  const doubled = Counter.useDerived("doubled");
+  const events = Counter.useEvents();
+
+  return (
+    <div>
+      <p>Count: {count} (doubled: {doubled})</p>
+      <button onClick={() => events.increment()}>+1</button>
+      <button onClick={() => events.reset()}>Reset</button>
+    </div>
+  );
+}
 ```
-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
+
+`createDirectiveContext(system)` returns: `{ Provider, useSystem, useFact, useDerived, useEvents, useDispatch, useSelector, useWatch, useInspect, useExplain, useHistory }`. All bound to the typed system — no system argument needed when calling them.
+
+The Provider accepts an optional `system` prop override for testing:
+
+```tsx
+<Counter.Provider system={testSystem}>
+  <ComponentUnderTest />
+</Counter.Provider>
 ```
 
-## Setup: System Outside React (Recommended)
+## Standalone hooks (without a context)
 
-Create the system outside of React. Components subscribe to it.
+When you don't want a context (e.g. one-off components, prototypes), import the hooks directly and pass the system to each call:
 
-```typescript
-// system.ts – created once, imported anywhere
+```tsx
+// system.ts
 import { createSystem } from "@directive-run/core";
 import { counterModule } from "./counter-module";
 
 export const system = createSystem({ module: counterModule });
 ```
 
-```typescript
+```tsx
 // Counter.tsx
-import { useSelector, useEvent } from "@directive-run/react";
+import { useFact, useDerived, useEvents } 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);
+export function Counter() {
+  const count = useFact(system, "count");
+  const doubled = useDerived(system, "doubled");
+  const events = useEvents(system);
 
   return (
     <div>
-      <p>Count: {count}</p>
-      <p>Doubled: {doubled}</p>
+      <p>Count: {count} (doubled: {doubled})</p>
       <button onClick={() => events.increment()}>+1</button>
-      <button onClick={() => events.reset()}>Reset</button>
     </div>
   );
 }
 ```
 
-## useSelector
+## Hook reference
 
-Subscribes to system state. Re-renders the component only when the selected value changes (shallow comparison).
+### `useFact(system, key)` or `useFact(system, [keys])`
 
-```typescript
-import { useSelector } from "@directive-run/react";
+Reads one fact (single key) or many facts (array of keys). Re-renders only when the selected fact(s) change. Return type is narrowed by the schema.
 
-function UserProfile() {
-  // Select a single fact
-  const name = useSelector(system, (s) => s.facts.userName);
+```tsx
+import { useFact } from "@directive-run/react";
 
-  // Select a derivation
-  const isAdmin = useSelector(system, (s) => s.derive.isAdmin);
+function Profile() {
+  // Single key — typed: name is string | undefined
+  const name = useFact(system, "name");
 
-  // Select a computed value from multiple facts
-  const summary = useSelector(system, (s) => ({
-    name: s.facts.userName,
-    role: s.facts.role,
-    isAdmin: s.derive.isAdmin,
-  }));
+  // Multi-key — typed: { name: string; age: number }
+  const { name, age } = useFact(system, ["name", "age"]);
 
-  return <div>{summary.name} ({summary.role})</div>;
+  return <div>{name} ({age})</div>;
 }
 ```
 
-### Multi-Module System
+### `useDerived(system, id)` or `useDerived(system, [ids])`
 
-```typescript
-const system = createSystem({
-  modules: { auth: authModule, cart: cartModule },
-});
+Same shape as `useFact` but for derivations. Re-renders only when the derivation's value changes.
 
-function Header() {
-  const token = useSelector(system, (s) => s.facts.auth.token);
-  const itemCount = useSelector(system, (s) => s.derive.cart.itemCount);
+```tsx
+import { useDerived } from "@directive-run/react";
+
+function Status() {
+  const isReady = useDerived(system, "isReady");
+  const { isReady, isLoading } = useDerived(system, ["isReady", "isLoading"]);
 
-  return <header>Items: {itemCount}</header>;
+  return <div>{isReady ? "ready" : "loading"}</div>;
 }
 ```
 
-## useEvent
+### `useEvents(system)`
 
-Returns the system's event dispatcher. Stable reference (does not cause re-renders).
+Returns the system's typed events accessor. Stable identity — does not cause re-renders. **This is the primary way to dispatch events from a component** — it carries autocomplete for every event name and payload shape.
 
-```typescript
-import { useEvent } from "@directive-run/react";
+```tsx
+import { useEvents } from "@directive-run/react";
+
+function CartActions() {
+  const events = useEvents(system);
 
-function LoginForm() {
-  const events = useEvent(system);
+  return (
+    <>
+      <button onClick={() => events.addItem({ productId: "p1" })}>Add</button>
+      <button onClick={() => events.checkout()}>Checkout</button>
+    </>
+  );
+}
 
-  const handleSubmit = (email: string, password: string) => {
-    events.login({ email, password });
-  };
+// Namespaced (multi-module) system — events are nested by module name
+function Header() {
+  const events = useEvents(namespacedSystem);
 
-  return <form onSubmit={() => handleSubmit("a@b.com", "pass")}>...</form>;
+  return <button onClick={() => events.cart.addItem({ productId: "p1" })}>Add</button>;
 }
+```
 
-// Multi-module
-function CartActions() {
-  const events = useEvent(system);
+### `useSelector(system, selector, equalityFn?)`
 
-  return (
-    <button onClick={() => events.cart.addItem({ productId: "p1" })}>
-      Add to Cart
-    </button>
-  );
+For computed values across multiple facts and derivations. Auto-tracks accessed keys; re-renders only when the selected result changes (by `Object.is` equality, override with `equalityFn`).
+
+```tsx
+import { useSelector, shallowEqual } from "@directive-run/react";
+
+function CheckoutSummary() {
+  const summary = useSelector(system, (state) => ({
+    itemCount: state.items.length,
+    total: state.cartTotal,
+    isReady: state.canCheckout,
+  }), shallowEqual);
+
+  return <div>{summary.itemCount} items · {summary.total}</div>;
 }
 ```
 
-## useSystem
+`state` carries both facts and derivations in a flat namespace — that's why it's typed `InferSelectorState<S>`, not `InferFacts<S>`.
 
-Creates and manages a system's lifecycle within a React component. The system is created on mount and destroyed on unmount.
+### `useDispatch(system)`
 
-```typescript
-import { useSystem, useSelector, useEvent } from "@directive-run/react";
+Returns a raw `dispatch(event)` function. Useful when you need to forward events programmatically or when the event name is computed at runtime. Prefer `useEvents` for normal dispatch — it carries typing.
+
+```tsx
+import { useDispatch } from "@directive-run/react";
+
+function ToolBar({ actions }: { actions: SystemEvent[] }) {
+  const dispatch = useDispatch(system);
+
+  return actions.map((a) => (
+    <button key={a.type} onClick={() => dispatch(a)}>{a.type}</button>
+  ));
+}
+```
+
+### `useDirective(moduleOrOptions, selections?)`
+
+Convenience hook that **creates a scoped system** AND selects facts/derivations in one call. The system lives for the lifetime of the component (created on mount, destroyed on unmount). Use this when the system's lifecycle should match a component's lifecycle — game boards, wizard flows, modal forms.
+
+```tsx
+import { useDirective } from "@directive-run/react";
+import { gameModule } from "./game-module";
 
 function GameBoard() {
-  // System created on mount, destroyed on unmount
-  const gameSystem = useSystem({
-    module: gameModule,
-    history: true,
+  // Selective subscription — only re-renders when score or isOver change
+  const { facts: { score }, derived: { isOver }, events } = useDirective(gameModule, {
+    facts: ["score"],
+    derived: ["isOver"],
   });
 
-  const score = useSelector(gameSystem, (s) => s.facts.score);
-  const events = useEvent(gameSystem);
-
   return (
     <div>
-      <p>Score: {score}</p>
+      <p>Score: {score}{isOver && " — game over!"}</p>
       <button onClick={() => events.move({ direction: "up" })}>Up</button>
     </div>
   );
 }
+
+// Subscribe to everything (omit keys)
+function Debug() {
+  const { facts, derived, events, dispatch } = useDirective(gameModule);
+
+  return <pre>{JSON.stringify({ facts, derived }, null, 2)}</pre>;
+}
 ```
 
-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.
+For app-wide state, prefer `createDirectiveContext` over `useDirective` — the context pattern creates the system once instead of per-component.
 
-## DirectiveProvider and useDirectiveContext
+### `useDirectiveRef(moduleOrOptions, config?)`
 
-Share a system through React context.
+Just the system-lifecycle half of `useDirective`. Returns the `SingleModuleSystem<S>` instance. Use this when you need a scoped system without consuming its state in this component (e.g., you're going to thread it through props or a context).
 
-```typescript
-import { DirectiveProvider, useDirectiveContext, useSelector, useEvent } from "@directive-run/react";
+### `useWatch(system, factOrDerivationId, callback)`
 
-// Provide the system at the top of your tree
-function App() {
-  return (
-    <DirectiveProvider system={system}>
-      <Dashboard />
-    </DirectiveProvider>
-  );
-}
+Imperative side-effect when a fact or derivation changes. Does NOT cause re-renders — use this for analytics, logging, focus management. For state you want to render, use `useFact` / `useDerived` / `useSelector`.
 
-// Consume the system anywhere below
-function Dashboard() {
-  const system = useDirectiveContext();
-  const stats = useSelector(system, (s) => s.derive.dashboardStats);
+### Status + introspection hooks
 
-  return <div>{stats.totalUsers} users</div>;
-}
-```
+| Hook | Purpose |
+|---|---|
+| `useRequirementStatus(system, type)` | Reactive `idle / running / success / error` status for a requirement type |
+| `useConstraintStatus(system, id)` | Reactive constraint enabled/disabled state |
+| `useSuspenseRequirement(system, type)` | Same as `useRequirementStatus` but suspends until resolved (Suspense boundary required) |
+| `useExplain(system, requirementId)` | Reactive English explanation of a requirement's `when` predicate |
+| `useInspect(system, options?)` | Full system inspection state — constraints, requirements, resolvers, derivations |
+| `useHistory(system)` | Time-travel UI helpers: `goBack`, `goForward`, `canUndo`, `canRedo`, snapshot list |
+| `useAuditLedger(system)` | Subscribe to a configured `createAuditLedger` plugin's entries |
 
-## CRITICAL: Hooks That DO NOT Exist
+### SSR + hydration
 
-```typescript
-// WRONG – useDirective() does not exist. This is a common hallucination.
-const { facts, derive, events } = useDirective(system);
+`DirectiveHydrator` and `useHydratedSystem` close the SSR loop. See `system-api.md` → "Hydration" for the full pattern.
 
-// CORRECT – use useSelector for state, useEvent for actions
-const count = useSelector(system, (s) => s.facts.count);
-const events = useEvent(system);
-```
+### Suspense for data fetching
 
-## createDirectiveContext
+`useQuerySystem` + `useSuspenseQuery` integrate `@directive-run/query`'s subscription/mutation primitives with React's Suspense and Error Boundaries. See the `@directive-run/query` docs.
 
-Eliminates prop-drilling by providing the system via React context:
+## CRITICAL: hooks that DO NOT exist
 
-```typescript
-import { createDirectiveContext } from "@directive-run/react";
+LLMs frequently hallucinate these names because they sound plausible. None of them are exported from `@directive-run/react`.
 
-const Counter = createDirectiveContext(counterSystem);
+| Hallucination | Use instead |
+|---|---|
+| `useEvent(system)` (singular) | `useEvents(system)` (plural) |
+| `useSystem(config)` as a top-level import | `useDirective(module)` or `createDirectiveContext().useSystem` |
+| `DirectiveProvider` as a top-level import | `createDirectiveContext(system).Provider` |
+| `useDirectiveContext()` | `createDirectiveContext(system).useSystem()` |
+| `useState`-style writes like `setCount(5)` | Dispatch events: `events.setCount(5)` (or whatever your module defines) |
 
-function App() {
-  return (
-    <Counter.Provider>
-      <Display />
-    </Counter.Provider>
-  );
-}
+```tsx
+// WRONG — useEvent does not exist
+import { useEvent } from "@directive-run/react";
+const events = useEvent(system);
 
-function Display() {
-  const count = Counter.useFact("count");       // No system arg needed
-  const doubled = Counter.useDerived("doubled");
-  const events = Counter.useEvents();
-  return <button onClick={() => events.increment()}>{count}</button>;
-}
+// CORRECT — useEvents (plural)
+import { useEvents } from "@directive-run/react";
+const events = useEvents(system);
 ```
 
-Returns: `{ Provider, useSystem, useFact, useDerived, useEvents, useDispatch, useSelector, useWatch, useInspect, useExplain, useHistory }`.
-
-Provider accepts `system` prop override for testing:
 ```tsx
-<Counter.Provider system={testSystem}><ComponentUnderTest /></Counter.Provider>
+// WRONG — DirectiveProvider is not a top-level export
+import { DirectiveProvider, useDirectiveContext } from "@directive-run/react";
+<DirectiveProvider system={system}>...</DirectiveProvider>
+
+// CORRECT — Provider comes from createDirectiveContext()
+import { createDirectiveContext } from "@directive-run/react";
+export const Counter = createDirectiveContext(counterSystem);
+<Counter.Provider>...</Counter.Provider>
 ```
 
-## Common Mistakes
+## Common mistakes
 
-### Creating the system inside a component without useSystem
+### Creating the system inside a component body
 
-```typescript
-// WRONG – creates a new system on every render
+```tsx
+// 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);
-
+  const system = createSystem({ module: counterModule });
+  const count = useFact(system, "count");
   return <div>{count}</div>;
 }
 
-// CORRECT – create outside the component
+// CORRECT — create outside the component
 const system = createSystem({ module: counterModule });
 
 function Counter() {
-  const count = useSelector(system, (s) => s.facts.count);
-
+  const count = useFact(system, "count");
   return <div>{count}</div>;
 }
 
-// ALSO CORRECT – useSystem manages lifecycle
+// ALSO CORRECT — useDirective manages lifecycle
 function Counter() {
-  const system = useSystem({ module: counterModule });
-  const count = useSelector(system, (s) => s.facts.count);
-
+  const { facts: { count } } = useDirective(counterModule, { facts: ["count"] });
   return <div>{count}</div>;
 }
 ```
 
-### Selecting too much state (causes unnecessary re-renders)
+### Selecting too much state (excess re-renders)
+
+```tsx
+// WRONG — re-renders on ANY fact change
+const allFacts = useSelector(system, (s) => s);
+
+// WRONG — re-renders even when other facts change (new object identity every time)
+const profile = useSelector(system, (s) => ({ name: s.name, age: s.age }));
 
-```typescript
-// WRONG – re-renders on ANY fact change
-const allFacts = useSelector(system, (s) => s.facts);
+// CORRECT — use the targeted hook
+const name = useFact(system, "name");
 
-// CORRECT – select only what you need
-const name = useSelector(system, (s) => s.facts.userName);
-const count = useSelector(system, (s) => s.facts.count);
+// CORRECT — multi-key reads a stable subset
+const { name, age } = useFact(system, ["name", "age"]);
+
+// CORRECT — useSelector with shallowEqual for shaped output
+import { shallowEqual } from "@directive-run/react";
+const profile = useSelector(system, (s) => ({ name: s.name, age: s.age }), shallowEqual);
 ```
 
-### Mutating facts directly in event handlers
+### Mutating facts directly from an event handler
 
-```typescript
-// WRONG – bypass the event system
+```tsx
+// WRONG — bypasses the event system, no audit trail, no constraint reaction
 function Counter() {
-  const count = useSelector(system, (s) => s.facts.count);
-
-  return (
-    <button onClick={() => { system.facts.count += 1; }}>
-      {count}
-    </button>
-  );
+  const count = useFact(system, "count");
+  return <button onClick={() => { system.facts.count += 1; }}>{count}</button>;
 }
 
-// CORRECT – use events for intent-driven mutations
+// CORRECT — dispatch an event
 function Counter() {
-  const count = useSelector(system, (s) => s.facts.count);
-  const events = useEvent(system);
-
-  return (
-    <button onClick={() => events.increment()}>
-      {count}
-    </button>
-  );
+  const count = useFact(system, "count");
+  const events = useEvents(system);
+  return <button onClick={() => events.increment()}>{count}</button>;
 }
 ```
 
-### Casting values from useSelector
+### Casting values from hooks
+
+```tsx
+// WRONG — types come from the schema
+const profile = useFact(system, "profile") as UserProfile;
 
-```typescript
-// WRONG – unnecessary type casting
-const profile = useSelector(system, (s) => s.facts.profile as UserProfile);
+// CORRECT — the schema types it for you
+const profile = useFact(system, "profile");
+```
+
+### Forgetting `useEvents` is stable
+
+```tsx
+// UNNECESSARY — useEvents returns a stable reference, no useCallback needed
+const events = useEvents(system);
+const handleClick = useCallback(() => events.increment(), [events]);
 
-// CORRECT – types are inferred from the module schema
-const profile = useSelector(system, (s) => s.facts.profile);
+// FINE — events.increment is stable across renders too
+const events = useEvents(system);
+<button onClick={() => events.increment()}>+</button>
 ```

package/core/resolvers.md

@@ -1,5 +1,7 @@
 # Resolvers
 
+> Covers `@directive-run/core` — resolver definition: retry policies, batching, cancellation, custom dedup keys, `owns` binding.
+
 Resolvers fulfill requirements emitted by constraints. They are the supply side of the constraint-resolver pattern. Resolvers handle async work and mutate state through `context.facts`.
 
 ## Decision Tree: "How should this resolver work?"

package/core/schema-types.md

@@ -1,5 +1,7 @@
 # Schema Types
 
+> Covers `@directive-run/core` — schema builders (`t.string` / `t.number` / `t.array` / etc.) and inference helpers.
+
 The `t.*()` builders define fact types in module schemas. They provide runtime validation in dev mode and full TypeScript inference.
 
 ## Decision Tree: "Which type builder do I use?"

package/core/system-api.md

@@ -1,5 +1,7 @@
 # System API
 
+> Covers `@directive-run/core` — `createSystem`, the system instance surface, hydration, inspection, distributable snapshots.
+
 The system is created with `createSystem()` and is the runtime that orchestrates modules, constraints, resolvers, and plugins.
 
 ## Decision Tree: "How do I interact with the system?"