@directive-run/knowledge 0.2.0 → 0.4.2

package/core/anti-patterns.md

@@ -5,17 +5,17 @@
 ## 1. Unnecessary Type Casting on Facts/Derivations
 
 ```typescript
-// WRONG — schema already provides the type
+// WRONG – schema already provides the type
 const profile = system.facts.profile as ResourceState<Profile>;
 
-// CORRECT — trust the schema
+// CORRECT – trust the schema
 const profile = system.facts.profile;
 ```
 
 ## 2. Flat Schema (Missing facts Wrapper)
 
 ```typescript
-// WRONG — facts must be nested under schema.facts
+// WRONG – facts must be nested under schema.facts
 createModule("counter", {
   schema: {
     phase: t.string(),
@@ -37,7 +37,7 @@ createModule("counter", {
 ## 3. Bare `facts.*` in Multi-Module Constraints
 
 ```typescript
-// WRONG — multi-module constraints use facts.self for own module
+// WRONG – multi-module constraints use facts.self for own module
 constraints: {
   checkItems: {
     when: (facts) => facts.items.length > 0,
@@ -45,7 +45,7 @@ constraints: {
   },
 },
 
-// CORRECT — use facts.self.* for own module facts
+// CORRECT – use facts.self.* for own module facts
 constraints: {
   checkItems: {
     when: (facts) => facts.self.items.length > 0,
@@ -57,7 +57,7 @@ constraints: {
 ## 4. Nonexistent Schema Builders
 
 ```typescript
-// WRONG — t.map(), t.set(), t.promise() do not exist
+// WRONG – t.map(), t.set(), t.promise() do not exist
 schema: {
   facts: {
     cache: t.map<string, User>(),
@@ -66,7 +66,7 @@ schema: {
   },
 },
 
-// CORRECT — use t.object() with type parameter
+// CORRECT – use t.object() with type parameter
 schema: {
   facts: {
     cache: t.object<Map<string, User>>(),
@@ -79,12 +79,12 @@ schema: {
 ## 5. Abbreviating `context` to `ctx`
 
 ```typescript
-// WRONG — never abbreviate context
+// WRONG – never abbreviate context
 resolve: async (req, ctx) => {
   ctx.facts.status = "done";
 },
 
-// CORRECT — always spell out context
+// CORRECT – always spell out context
 resolve: async (req, context) => {
   context.facts.status = "done";
 },
@@ -93,13 +93,13 @@ resolve: async (req, context) => {
 ## 6. Flat Module Config (No schema Wrapper)
 
 ```typescript
-// WRONG — properties must be inside schema.facts
+// WRONG – properties must be inside schema.facts
 createModule("timer", {
   phase: t.string(),
   elapsed: t.number(),
 });
 
-// CORRECT — wrap in schema: { facts: {} }
+// CORRECT – wrap in schema: { facts: {} }
 createModule("timer", {
   schema: {
     facts: {
@@ -113,21 +113,21 @@ createModule("timer", {
 ## 7. String-Based Event Dispatch
 
 ```typescript
-// WRONG — events are not dispatched by string
+// WRONG – events are not dispatched by string
 system.dispatch("login", { token: "abc" });
 
-// CORRECT — use the events accessor
+// CORRECT – use the events accessor
 system.events.login({ token: "abc" });
 ```
 
 ## 8. Direct Array/Object Mutation
 
 ```typescript
-// WRONG — proxy cannot detect in-place mutations
+// WRONG – proxy cannot detect in-place mutations
 facts.items.push(item);
 facts.config.theme = "dark";
 
-// CORRECT — replace the entire value
+// CORRECT – replace the entire value
 facts.items = [...facts.items, item];
 facts.config = { ...facts.config, theme: "dark" };
 ```
@@ -135,10 +135,10 @@ facts.config = { ...facts.config, theme: "dark" };
 ## 9. Nonexistent `useDirective` Hook
 
 ```typescript
-// WRONG — there is no useDirective hook
+// WRONG – there is no useDirective hook
 const state = useDirective(system);
 
-// CORRECT — use useSelector with a selector function
+// CORRECT – use useSelector with a selector function
 const count = useSelector(system, (s) => s.facts.count);
 const isLoading = useSelector(system, (s) => s.derive.isLoading);
 ```
@@ -146,11 +146,11 @@ const isLoading = useSelector(system, (s) => s.derive.isLoading);
 ## 10. Bracket Notation for Namespaced Facts
 
 ```typescript
-// WRONG — internal separator is not part of the public API
+// WRONG – internal separator is not part of the public API
 const status = facts["auth::status"];
 const token = facts["auth_token"];
 
-// CORRECT — use dot notation through the namespace proxy
+// CORRECT – use dot notation through the namespace proxy
 const status = facts.auth.status;
 const token = facts.auth.token;
 ```
@@ -158,12 +158,12 @@ const token = facts.auth.token;
 ## 11. Builder/Chaining API
 
 ```typescript
-// WRONG — there is no builder pattern
+// WRONG – there is no builder pattern
 const mod = module("counter")
   .schema({ count: t.number() })
   .build();
 
-// CORRECT — use createModule with object syntax
+// CORRECT – use createModule with object syntax
 const mod = createModule("counter", {
   schema: {
     facts: { count: t.number() },
@@ -174,14 +174,14 @@ const mod = createModule("counter", {
 ## 12. Returning Data from Resolvers
 
 ```typescript
-// WRONG — resolvers return void, not data
+// WRONG – resolvers return void, not data
 resolve: async (req, context) => {
   const user = await fetchUser(req.userId);
 
   return user; // Return value is ignored
 },
 
-// CORRECT — mutate context.facts to store results
+// CORRECT – mutate context.facts to store results
 resolve: async (req, context) => {
   const user = await fetchUser(req.userId);
   context.facts.user = user;
@@ -191,13 +191,13 @@ resolve: async (req, context) => {
 ## 13. Async Logic in `init`
 
 ```typescript
-// WRONG — init is synchronous, facts assignment only
+// WRONG – init is synchronous, facts assignment only
 init: async (facts) => {
   const data = await fetch("/api/config");
   facts.config = await data.json();
 },
 
-// CORRECT — init sets defaults; use constraints/resolvers for async work
+// CORRECT – init sets defaults; use constraints/resolvers for async work
 init: (facts) => {
   facts.config = null;
   facts.phase = "loading";
@@ -214,11 +214,11 @@ constraints: {
 ## 14. Missing `settle()` After `start()`
 
 ```typescript
-// WRONG — constraints fire on start, resolvers are async
+// WRONG – constraints fire on start, resolvers are async
 system.start();
 console.log(system.facts.data); // May still be null
 
-// CORRECT — wait for resolvers to complete
+// CORRECT – wait for resolvers to complete
 system.start();
 await system.settle();
 console.log(system.facts.data); // Resolved
@@ -227,7 +227,7 @@ console.log(system.facts.data); // Resolved
 ## 15. Missing `crossModuleDeps` Declaration
 
 ```typescript
-// WRONG — accessing auth facts without declaring dependency
+// WRONG – accessing auth facts without declaring dependency
 const dataModule = createModule("data", {
   schema: { facts: { items: t.array(t.string()) } },
   constraints: {
@@ -238,7 +238,7 @@ const dataModule = createModule("data", {
   },
 });
 
-// CORRECT — declare crossModuleDeps for type-safe cross-module access
+// CORRECT – declare crossModuleDeps for type-safe cross-module access
 const dataModule = createModule("data", {
   schema: { facts: { items: t.array(t.string()) } },
   crossModuleDeps: { auth: authSchema },
@@ -254,7 +254,7 @@ const dataModule = createModule("data", {
 ## 16. String Literal for `require`
 
 ```typescript
-// WRONG — require must be an object with type property
+// WRONG – require must be an object with type property
 constraints: {
   check: {
     when: (facts) => facts.ready,
@@ -262,7 +262,7 @@ constraints: {
   },
 },
 
-// CORRECT — use object form with type
+// CORRECT – use object form with type
 constraints: {
   check: {
     when: (facts) => facts.ready,
@@ -274,23 +274,23 @@ constraints: {
 ## 17. Passthrough Derivations
 
 ```typescript
-// WRONG — derivation just returns a fact value unchanged
+// WRONG – derivation just returns a fact value unchanged
 derive: {
   count: (facts) => facts.count,
 },
 
-// CORRECT — remove it, read the fact directly instead
+// CORRECT – remove it, read the fact directly instead
 // system.facts.count instead of system.derive.count
 ```
 
 ## 18. Deep Import Paths
 
 ```typescript
-// WRONG — internal module paths are not public API
+// WRONG – internal module paths are not public API
 import { createModule } from "@directive-run/core/module";
 import { createSystem } from "@directive-run/core/system";
 
-// CORRECT — import from package root
+// CORRECT – import from package root
 import { createModule, createSystem } from "@directive-run/core";
 
 // Exception: plugins have their own entry point
@@ -300,7 +300,7 @@ import { loggingPlugin } from "@directive-run/core/plugins";
 ## 19. Async `when()` Without `deps`
 
 ```typescript
-// WRONG — async constraints need explicit deps for tracking
+// WRONG – async constraints need explicit deps for tracking
 constraints: {
   validate: {
     async: true,
@@ -313,7 +313,7 @@ constraints: {
   },
 },
 
-// CORRECT — add deps array for async constraints
+// CORRECT – add deps array for async constraints
 constraints: {
   validate: {
     async: true,
@@ -331,7 +331,7 @@ constraints: {
 ## 20. No Error Handling on Failing Resolvers
 
 ```typescript
-// WRONG — unhandled errors crash the system
+// WRONG – unhandled errors crash the system
 resolvers: {
   fetchData: {
     requirement: "FETCH",
@@ -342,7 +342,7 @@ resolvers: {
   },
 },
 
-// CORRECT — use retry policy and/or module error boundary
+// CORRECT – use retry policy and/or module error boundary
 resolvers: {
   fetchData: {
     requirement: "FETCH",

package/core/constraints.md

@@ -19,10 +19,10 @@ A constraint has two parts: `when` (condition) and `require` (what's needed).
 ```typescript
 constraints: {
   fetchUserWhenReady: {
-    // when() returns boolean — evaluated on every fact change
+    // when() returns boolean – evaluated on every fact change
     when: (facts) => facts.isAuthenticated && !facts.user,
 
-    // require — the requirement to emit when condition is true
+    // require – the requirement to emit when condition is true
     require: { type: "FETCH_USER", userId: facts.userId },
   },
 },
@@ -31,7 +31,7 @@ constraints: {
 ### Static vs Dynamic Requirements
 
 ```typescript
-// Static requirement — same object every time
+// Static requirement – same object every time
 constraints: {
   loadConfig: {
     when: (facts) => facts.config === null,
@@ -39,7 +39,7 @@ constraints: {
   },
 },
 
-// Dynamic requirement — function that reads facts
+// Dynamic requirement – function that reads facts
 constraints: {
   fetchUser: {
     when: (facts) => facts.isAuthenticated && !facts.profile,
@@ -47,7 +47,7 @@ constraints: {
   },
 },
 
-// Multiple requirements — return an array
+// Multiple requirements – return an array
 constraints: {
   loadAll: {
     when: (facts) => facts.phase === "init",
@@ -137,7 +137,7 @@ constraints: {
 Synchronous constraints use auto-tracking (proxy-based). Async constraints cannot be auto-tracked because the function is suspended across await boundaries. The `deps` array tells the engine which facts to watch.
 
 ```typescript
-// WRONG — async without deps, engine cannot track dependencies
+// WRONG – async without deps, engine cannot track dependencies
 constraints: {
   check: {
     async: true,
@@ -146,7 +146,7 @@ constraints: {
   },
 },
 
-// CORRECT — deps tells the engine to re-evaluate when token changes
+// CORRECT – deps tells the engine to re-evaluate when token changes
 constraints: {
   check: {
     async: true,
@@ -163,13 +163,13 @@ constraints: {
 const system = createSystem({ module: myModule });
 system.start();
 
-// Disable a constraint — it won't be evaluated
+// Disable a constraint – it won't be evaluated
 system.constraints.disable("fetchUserWhenReady");
 
 // Check if disabled
 system.constraints.isDisabled("fetchUserWhenReady"); // true
 
-// Re-enable — triggers re-evaluation on next cycle
+// Re-enable – triggers re-evaluation on next cycle
 system.constraints.enable("fetchUserWhenReady");
 ```
 
@@ -178,7 +178,7 @@ system.constraints.enable("fetchUserWhenReady");
 ### Putting async logic in resolvers instead of constraints
 
 ```typescript
-// WRONG — resolver checks conditions (constraint's job)
+// WRONG – resolver checks conditions (constraint's job)
 resolvers: {
   fetchData: {
     requirement: "FETCH",
@@ -191,7 +191,7 @@ resolvers: {
   },
 },
 
-// CORRECT — constraint declares when, resolver just does the work
+// CORRECT – constraint declares when, resolver just does the work
 constraints: {
   fetchWhenAuth: {
     when: (facts) => facts.isAuthenticated && !facts.data,
@@ -213,16 +213,16 @@ resolvers: {
 ### String literal for require
 
 ```typescript
-// WRONG — require must be an object
+// WRONG – require must be an object
 require: "FETCH_DATA",
 
-// CORRECT — object with type property
+// CORRECT – object with type property
 require: { type: "FETCH_DATA" },
 
-// CORRECT — with payload
+// CORRECT – with payload
 require: { type: "FETCH_DATA", endpoint: "/api/users" },
 
-// CORRECT — dynamic from facts
+// CORRECT – dynamic from facts
 require: (facts) => ({ type: "FETCH_DATA", userId: facts.currentUserId }),
 ```
 

package/core/core-patterns.md

@@ -17,7 +17,7 @@ User wants to...
 ## Module Shape (Canonical Object Syntax)
 
 ```typescript
-// CORRECT — full module definition
+// CORRECT – full module definition
 import { createModule, t } from "@directive-run/core";
 
 const myModule = createModule("name", {
@@ -104,14 +104,14 @@ const myModule = createModule("name", {
 import { createSystem } from "@directive-run/core";
 import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
 
-// Single module — direct access: system.facts.count
+// Single module – direct access: system.facts.count
 const system = createSystem({
   module: myModule,
   plugins: [loggingPlugin(), devtoolsPlugin()],
   debug: { timeTravel: true, maxSnapshots: 100 },
 });
 
-// Multi-module — namespaced access: system.facts.auth.token
+// Multi-module – namespaced access: system.facts.auth.token
 const system = createSystem({
   modules: { auth: authModule, cart: cartModule },
   plugins: [devtoolsPlugin()],
@@ -130,7 +130,7 @@ system.destroy();
 WRONG thinking: "I'll put the fetch call in a resolver that checks auth."
 
 ```typescript
-// WRONG — resolver doing condition checking + data fetching
+// WRONG – resolver doing condition checking + data fetching
 resolvers: {
   fetchData: {
     requirement: "FETCH_DATA",
@@ -148,7 +148,7 @@ resolvers: {
 CORRECT thinking: "Constraint declares WHEN, resolver declares HOW."
 
 ```typescript
-// CORRECT — constraint declares the need, resolver fulfills it
+// CORRECT – constraint declares the need, resolver fulfills it
 constraints: {
   fetchWhenAuthenticated: {
     when: (facts) => facts.isAuthenticated && !facts.data,
@@ -170,14 +170,14 @@ resolvers: {
 ## Reading System State
 
 ```typescript
-// Facts — mutable state
+// Facts – mutable state
 system.facts.count = 5;
 const val = system.facts.count;
 
-// Derivations — read-only computed values
+// Derivations – read-only computed values
 const loading = system.derive.isLoading;
 
-// Events — dispatch user actions
+// Events – dispatch user actions
 system.events.increment();
 system.events.setUser({ user: { id: "1", name: "Alice" } });
 
@@ -201,7 +201,7 @@ await system.when((facts) => facts.phase === "done", { timeout: 5000 });
 Only `facts` is required in the schema. Other sections are optional:
 
 ```typescript
-// Minimal module — facts only
+// Minimal module – facts only
 const minimal = createModule("minimal", {
   schema: {
     facts: { count: t.number() },

package/core/error-boundaries.md

@@ -53,7 +53,7 @@ const system = createSystem({
     onEffectError: "skip",
     onDerivationError: "throw",
 
-    // Global error callback — fires for all errors
+    // Global error callback – fires for all errors
     onError: (error) => {
       // error is a DirectiveError with source tracking
       console.error(`[${error.source}] ${error.sourceId}: ${error.message}`);
@@ -79,17 +79,17 @@ Use functions instead of strings for conditional recovery:
 ```typescript
 errorBoundary: {
   onResolverError: (error, resolverId) => {
-    // Network errors — retry later
+    // Network errors – retry later
     if (error.message.includes("NetworkError")) {
       return "retry-later";
     }
 
-    // Auth errors — skip, don't retry
+    // Auth errors – skip, don't retry
     if (error.message.includes("401")) {
       return "skip";
     }
 
-    // Everything else — throw
+    // Everything else – throw
     return "throw";
   },
 
@@ -125,8 +125,8 @@ try {
 } catch (err) {
   if (err instanceof DirectiveError) {
     err.source;      // "constraint" | "resolver" | "effect" | "derivation" | "system"
-    err.sourceId;    // e.g., "fetchUser" — the specific item that failed
-    err.recoverable; // boolean — whether recovery strategies apply
+    err.sourceId;    // e.g., "fetchUser" – the specific item that failed
+    err.recoverable; // boolean – whether recovery strategies apply
     err.context;     // arbitrary debug data (e.g., the requirement object)
     err.message;     // human-readable description
   }
@@ -286,7 +286,7 @@ HALF_OPEN → Limited trial requests allowed
 
 ```typescript
 apiBreaker.getState();     // "CLOSED" | "OPEN" | "HALF_OPEN"
-apiBreaker.isAllowed();    // boolean — would a request be allowed?
+apiBreaker.isAllowed();    // boolean – would a request be allowed?
 apiBreaker.getStats();     // { totalRequests, totalFailures, recentFailures, ... }
 apiBreaker.forceState("CLOSED"); // Force state (useful in tests)
 apiBreaker.reset();        // Reset to CLOSED with cleared stats

package/core/multi-module.md

@@ -68,7 +68,7 @@ const cartModule = createModule("cart", {
   },
 });
 
-// Multi-module system — namespaced access
+// Multi-module system – namespaced access
 const system = createSystem({
   modules: { auth: authModule, cart: cartModule },
 });
@@ -79,24 +79,24 @@ system.start();
 ## Accessing Namespaced State
 
 ```typescript
-// Facts — namespaced under module name
+// Facts – namespaced under module name
 system.facts.auth.token;
 system.facts.auth.isAuthenticated;
 system.facts.cart.items;
 
-// Derivations — namespaced under module name
+// Derivations – namespaced under module name
 system.derive.cart.itemCount;
 
-// Events — namespaced under module name
+// Events – namespaced under module name
 system.events.auth.login({ token: "abc123" });
 system.events.auth.logout();
 
-// Subscribe — use "namespace.key" format
+// Subscribe – use "namespace.key" format
 system.subscribe(["auth.token", "cart.items"], () => {
   console.log("auth or cart changed");
 });
 
-// Watch — use "namespace.key" format
+// Watch – use "namespace.key" format
 system.watch("auth.isAuthenticated", (newVal, oldVal) => {
   console.log(`Auth: ${oldVal} -> ${newVal}`);
 });
@@ -106,7 +106,7 @@ system.subscribeModule("cart", () => {
   console.log("anything in cart changed");
 });
 
-// Wait for condition — facts are namespaced
+// Wait for condition – facts are namespaced
 await system.when((facts) => facts.auth.isAuthenticated);
 ```
 
@@ -166,7 +166,7 @@ const dataModule = createModule("data", {
     facts.loaded = false;
   },
 
-  // CORRECT — facts.self for own module, facts.auth for cross-module
+  // CORRECT – facts.self for own module, facts.auth for cross-module
   constraints: {
     fetchWhenAuth: {
       when: (facts) => facts.auth.isAuthenticated && !facts.self.loaded,
@@ -203,7 +203,7 @@ const dataModule = createModule("data", {
 ### Using bare `facts.*` instead of `facts.self.*`
 
 ```typescript
-// WRONG — in cross-module context, bare facts has no self-module properties
+// WRONG – in cross-module context, bare facts has no self-module properties
 constraints: {
   check: {
     when: (facts) => facts.loaded, // TypeScript error
@@ -211,7 +211,7 @@ constraints: {
   },
 },
 
-// CORRECT — use facts.self for own module
+// CORRECT – use facts.self for own module
 constraints: {
   check: {
     when: (facts) => facts.self.loaded,
@@ -223,11 +223,11 @@ constraints: {
 ### Bracket notation for internal keys
 
 ```typescript
-// WRONG — the :: separator is internal, never use it directly
+// WRONG – the :: separator is internal, never use it directly
 system.facts["auth::token"];
 system.read("auth::status");
 
-// CORRECT — dot notation through namespace proxy
+// CORRECT – dot notation through namespace proxy
 system.facts.auth.token;
 system.read("auth.status");
 ```
@@ -235,7 +235,7 @@ system.read("auth.status");
 ### Forgetting crossModuleDeps
 
 ```typescript
-// WRONG — facts.auth is untyped without crossModuleDeps
+// WRONG – facts.auth is untyped without crossModuleDeps
 const dataModule = createModule("data", {
   schema: { facts: { items: t.array(t.string()) } },
   constraints: {
@@ -246,7 +246,7 @@ const dataModule = createModule("data", {
   },
 });
 
-// CORRECT — declare the dependency
+// CORRECT – declare the dependency
 const dataModule = createModule("data", {
   schema: { facts: { items: t.array(t.string()) } },
   crossModuleDeps: { auth: authSchema },
@@ -265,13 +265,13 @@ const dataModule = createModule("data", {
 const system = createSystem({
   modules: { auth: authModule, cart: cartModule, data: dataModule },
 
-  // Initial facts — applied after init(), before first reconciliation
+  // Initial facts – applied after init(), before first reconciliation
   initialFacts: {
     auth: { token: "restored-token" },
     cart: { items: cachedItems },
   },
 
-  // Init order — control module initialization sequence
+  // Init order – control module initialization sequence
   initOrder: "auto",            // Sort by crossModuleDeps topology (default)
   // initOrder: "declaration",   // Use object key order
   // initOrder: ["auth", "data", "cart"], // Explicit order