@directive-run/knowledge 1.13.0 → 1.15.0

package/core/anti-patterns.md

@@ -1,5 +1,7 @@
 # Anti-Patterns
 
+> Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
+
 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
@@ -113,11 +115,16 @@ createModule("timer", {
 ## 7. String-Based Event Dispatch
 
 ```typescript
-// WRONG – events are not dispatched by string
+// WRONG – there is no two-argument string-keyed dispatch signature
 system.dispatch("login", { token: "abc" });
 
-// CORRECT – use the events accessor
+// CORRECT – use the typed events accessor (preferred — autocomplete + payload typing)
 system.events.login({ token: "abc" });
+
+// ALSO VALID – the single-arg object form of dispatch() is supported when you
+// need to forward a programmatically-built event. Prefer the events accessor
+// for normal code.
+system.dispatch({ type: "login", token: "abc" });
 ```
 
 ## 8. Direct Array/Object Mutation

package/core/constraints.md

@@ -1,5 +1,7 @@
 # Constraints
 
+> Covers `@directive-run/core` — constraint definition: `when` / `require`, async constraints with `deps`, priority, data-form predicates.
+
 Constraints declare WHEN something is needed. They are the demand side of the constraint-resolver pattern. Constraints evaluate conditions against facts and emit requirements that resolvers fulfill.
 
 ## Decision Tree: "Should this be a constraint?"
@@ -22,8 +24,10 @@ constraints: {
     // when() returns boolean – evaluated on every fact change
     when: (facts) => facts.isAuthenticated && !facts.user,
 
-    // require – the requirement to emit when condition is true
-    require: { type: "FETCH_USER", userId: facts.userId },
+    // require – the requirement to emit when condition is true.
+    // Use the function form whenever you need to read facts —
+    // facts is NOT in scope inside the static object form.
+    require: (facts) => ({ type: "FETCH_USER", userId: facts.userId }),
   },
 },
 ```

package/core/core-patterns.md

@@ -1,5 +1,7 @@
 # Core Patterns
 
+> Covers `@directive-run/core` — modules, facts, derivations, effects, events, and the constraint-resolver loop.
+
 How to think about building with Directive: modules, systems, and the constraint-resolver pattern.
 
 ## Decision Tree: "Where does this logic go?"

package/core/error-boundaries.md

@@ -1,5 +1,7 @@
 # Error Boundaries
 
+> Covers `@directive-run/core` — error boundaries, recovery strategies, lifecycle hooks, and circuit breakers.
+
 How to handle errors in Directive: recovery strategies, error boundaries, lifecycle hooks, and the circuit breaker pattern.
 
 ## Decision Tree: "How should errors be handled?"

package/core/history.md

@@ -1,5 +1,7 @@
 # History & Snapshots
 
+> Covers `@directive-run/core` — time-travel: snapshot, undo/redo, replay, export/import, changeset grouping.
+
 Directive records fact changes as snapshots, enabling undo/redo, replay, export/import, and changeset grouping.
 
 ## Decision Tree: "Should I enable history?"

package/core/multi-module.md

@@ -1,5 +1,7 @@
 # Multi-Module Systems
 
+> Covers `@directive-run/core` — namespaced multi-module systems, cross-module deps, `facts.self.*`.
+
 How to compose multiple modules into a namespaced system with cross-module type safety.
 
 ## Decision Tree: "Single or Multi-Module?"
@@ -303,13 +305,16 @@ system.registerModule("chat", chatModule.default);
 
 ## Cross-Module Events
 
-Events are namespaced at the system level but dispatched through the events accessor:
+Events are namespaced at the system level. **Prefer the typed events accessor** — it carries autocomplete and per-event payload typing.
 
 ```typescript
-// Multi-module events
+// Multi-module events — canonical form
 system.events.auth.login({ token: "abc" });
 system.events.cart.addItem({ id: "item-1", qty: 1 });
 
-// dispatch() also works with type discriminator
+// dispatch() is supported when you need to forward a programmatically-built
+// event (e.g., replaying a serialized event). The string form
+// (system.dispatch("login", payload)) does NOT exist — only the single-arg
+// object form is valid.
 system.dispatch({ type: "login", token: "abc" });
 ```

package/core/naming.md

@@ -1,5 +1,7 @@
 # Naming Conventions
 
+> Covers all `@directive-run/*` packages — terminology, parameter names, return-style rules.
+
 Directive naming rules that AI coding assistants must follow. These are non-negotiable project conventions.
 
 ## Decision Tree: "What do I call this?"
@@ -68,14 +70,19 @@ resolve: async (req, ctx) => { /* ... */ },
 
 ## Return Style
 
-### Always Use Braces
+### Always Use Braces (for `if` blocks with `return`)
+
+The brace rule applies to control-flow blocks — not to arrow-expression bodies.
 
-No single-line returns. Always wrap in braces.
+**Arrow expressions** (single-line derivations, predicates, computed
+requirements): the concise form is preferred. No braces, no explicit
+`return`.
 
 ```typescript
-// WRONG
+// CORRECT — single-line arrow expressions stay concise
 derive: {
   isReady: (facts) => facts.phase === "ready",
+  greeting: (facts) => `Hi, ${facts.name}!`,
 },
 
 constraints: {
@@ -84,14 +91,16 @@ constraints: {
     require: { type: "PROCESS" },
   },
 },
+```
 
-// Wait -- the above IS correct for one-line arrow expressions.
-// The brace rule applies to if/return blocks:
+**Control-flow statements** (`if`, `for`, `while`): braces required, even
+for single-line bodies. Single-line `if (x) return y` shapes are never used.
 
+```typescript
 // WRONG – single-line if return
 if (facts.user) return "ready";
 
-// CORRECT – always use braces
+// CORRECT – always wrap the body in braces
 if (facts.user) {
   return "ready";
 }

package/core/plugins.md

@@ -1,5 +1,7 @@
 # Plugins
 
+> Covers `@directive-run/core/plugins` — plugin authoring + built-ins (logging, devtools, persistence, audit-ledger, observability, OTLP).
+
 Plugins extend Directive systems with cross-cutting functionality like logging, persistence, devtools, and resilience patterns.
 
 ## Decision Tree: "Which plugin do I need?"