@directive-run/knowledge 0.2.0 → 0.4.2

package/core/naming.md

@@ -33,7 +33,7 @@ Fulfillment logic?
 The `req` parameter in resolvers and constraint `key()` functions is short for **requirement** -- the object emitted by a constraint's `require` property.
 
 ```typescript
-// CORRECT — req is a requirement
+// CORRECT – req is a requirement
 resolvers: {
   fetchUser: {
     requirement: "FETCH_USER",
@@ -47,7 +47,7 @@ resolvers: {
   },
 },
 
-// WRONG — never use "request" or "r"
+// WRONG – never use "request" or "r"
 resolve: async (request, context) => { /* ... */ },
 resolve: async (r, context) => { /* ... */ },
 ```
@@ -62,7 +62,7 @@ resolve: async (req, context) => {
   context.snapshot(); // facts snapshot
 },
 
-// WRONG — never abbreviate to ctx
+// WRONG – never abbreviate to ctx
 resolve: async (req, ctx) => { /* ... */ },
 ```
 
@@ -88,10 +88,10 @@ constraints: {
 // Wait -- the above IS correct for one-line arrow expressions.
 // The brace rule applies to if/return blocks:
 
-// WRONG — single-line if return
+// WRONG – single-line if return
 if (facts.user) return "ready";
 
-// CORRECT — always use braces
+// CORRECT – always use braces
 if (facts.user) {
   return "ready";
 }
@@ -102,7 +102,7 @@ if (facts.user) {
 Add a blank line before `return` when there is code above it. Skip the blank line when `return` is the first statement in a block.
 
 ```typescript
-// CORRECT — blank line before return when code precedes it
+// CORRECT – blank line before return when code precedes it
 function getStatus(facts) {
   const phase = facts.phase;
   const hasUser = facts.user !== null;
@@ -110,12 +110,12 @@ function getStatus(facts) {
   return phase === "ready" && hasUser;
 }
 
-// CORRECT — no blank line when return is first statement
+// CORRECT – no blank line when return is first statement
 function isReady(facts) {
   return facts.phase === "ready";
 }
 
-// CORRECT — blank line after brace-style return block
+// CORRECT – blank line after brace-style return block
 function process(facts) {
   if (!facts.ready) {
     return null;
@@ -126,7 +126,7 @@ function process(facts) {
   return result;
 }
 
-// WRONG — no blank line before return after code
+// WRONG – no blank line before return after code
 function getStatus(facts) {
   const phase = facts.phase;
   return phase === "ready"; // Missing blank line
@@ -138,13 +138,13 @@ function getStatus(facts) {
 Never put properties or statements on a single line inside braces. Always expand to one item per line with proper indentation. This applies everywhere: schema definitions, init functions, events, effects, requirement types, and any other object or block.
 
 ```typescript
-// WRONG — properties crammed on one line
+// WRONG – properties crammed on one line
 schema: {
   facts: { phase: t.string(), count: t.number() },
   requirements: { FETCH_USER: { id: t.string() }, RESET: {} },
 },
 
-// CORRECT — one property per line, always expanded
+// CORRECT – one property per line, always expanded
 schema: {
   facts: {
     phase: t.string(),
@@ -158,10 +158,10 @@ schema: {
   },
 },
 
-// WRONG — statements crammed on one line
+// WRONG – statements crammed on one line
 init: (facts) => { facts.phase = "idle"; facts.count = 0; },
 
-// CORRECT — one statement per line
+// CORRECT – one statement per line
 init: (facts) => {
   facts.phase = "idle";
   facts.count = 0;
@@ -181,12 +181,12 @@ events: {
 
 Single-expression arrows (no braces) are fine on one line. Empty objects `{}` are fine inline.
 ```typescript
-// OK — single expression, no braces
+// OK – single expression, no braces
 derive: {
   isReady: (facts) => facts.phase === "ready",
 },
 
-// OK — empty object
+// OK – empty object
 RESET: {},
 ```
 
@@ -205,7 +205,7 @@ constraints: {
   },
 },
 
-// WRONG — bare facts.* in multi-module context
+// WRONG – bare facts.* in multi-module context
 constraints: {
   loadWhenAuth: {
     when: (facts) => facts.isAuthenticated && !facts.loaded,
@@ -217,13 +217,13 @@ constraints: {
 ### System-Level Access Uses Dot Notation
 
 ```typescript
-// CORRECT — dot notation through namespace proxy
+// CORRECT – dot notation through namespace proxy
 system.facts.auth.token;
 system.facts.cart.items;
 system.derive.auth.isLoggedIn;
 system.events.auth.login({ token: "..." });
 
-// WRONG — bracket notation with internal separator
+// WRONG – bracket notation with internal separator
 system.facts["auth::token"];
 system.facts["auth_token"];
 ```
@@ -235,11 +235,11 @@ system.facts["auth_token"];
 The schema provides all types. Do not add `as` casts when reading facts or derivations from the system.
 
 ```typescript
-// CORRECT — schema provides the type
+// CORRECT – schema provides the type
 const profile = system.facts.profile;
 const isReady = system.derive.isReady;
 
-// WRONG — unnecessary cast
+// WRONG – unnecessary cast
 const profile = system.facts.profile as UserProfile;
 const isReady = system.derive.isReady as boolean;
 ```
@@ -249,7 +249,7 @@ const isReady = system.derive.isReady as boolean;
 Type assertions are only valid in schema definition using the `{} as {}` pattern:
 
 ```typescript
-// CORRECT — cast in schema definition
+// CORRECT – cast in schema definition
 schema: {
   facts: {} as { profile: UserProfile; settings: AppSettings },
   derivations: {} as { displayName: string },

package/core/plugins.md

@@ -46,13 +46,13 @@ 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
+// Default – logs facts changes and resolver start/complete
 loggingPlugin()
 
-// Verbose — logs everything including derivation recomputation and constraint evaluation
+// Verbose – logs everything including derivation recomputation and constraint evaluation
 loggingPlugin({ verbose: true })
 
-// Custom filter — only log specific events
+// Custom filter – only log specific events
 loggingPlugin({
   filter: (event) => {
     // Only log resolver events
@@ -97,7 +97,7 @@ persistencePlugin({
   storage: localStorage,
 })
 
-// sessionStorage — cleared when tab closes
+// sessionStorage – cleared when tab closes
 persistencePlugin({
   key: "session-state",
   storage: sessionStorage,
@@ -113,7 +113,7 @@ persistencePlugin({
   },
 })
 
-// Selective persistence — only persist certain facts
+// Selective persistence – only persist certain facts
 persistencePlugin({
   key: "my-app",
   storage: localStorage,
@@ -122,7 +122,7 @@ persistencePlugin({
   exclude: ["tempData", "sessionId"], // Everything except these
 })
 
-// Versioning — handle schema changes
+// Versioning – handle schema changes
 persistencePlugin({
   key: "my-app",
   storage: localStorage,
@@ -267,13 +267,13 @@ const system = createSystem({
 ### Enabling devtools in production
 
 ```typescript
-// WRONG — devtools overhead in production
+// WRONG – devtools overhead in production
 const system = createSystem({
   module: myModule,
   plugins: [devtoolsPlugin()],
 });
 
-// CORRECT — conditional on environment
+// CORRECT – conditional on environment
 const plugins = [];
 if (process.env.NODE_ENV === "development") {
   plugins.push(devtoolsPlugin());
@@ -289,13 +289,13 @@ const system = createSystem({
 ### Persistence without versioning
 
 ```typescript
-// WRONG — schema changes break existing users
+// WRONG – schema changes break existing users
 persistencePlugin({
   key: "app-state",
   storage: localStorage,
 })
 
-// CORRECT — version and migrate
+// CORRECT – version and migrate
 persistencePlugin({
   key: "app-state",
   storage: localStorage,
@@ -307,7 +307,7 @@ persistencePlugin({
 ### Plugin order matters
 
 ```typescript
-// WRONG — logging misses events from persistence restore
+// WRONG – logging misses events from persistence restore
 const system = createSystem({
   module: myModule,
   plugins: [
@@ -316,7 +316,7 @@ const system = createSystem({
   ],
 });
 
-// CORRECT — logging first to capture everything
+// CORRECT – logging first to capture everything
 const system = createSystem({
   module: myModule,
   plugins: [
@@ -329,13 +329,13 @@ const system = createSystem({
 ### Persisting sensitive or transient data
 
 ```typescript
-// WRONG — persists auth tokens and loading state
+// WRONG – persists auth tokens and loading state
 persistencePlugin({
   key: "app",
   storage: localStorage,
 })
 
-// CORRECT — exclude sensitive and transient facts
+// CORRECT – exclude sensitive and transient facts
 persistencePlugin({
   key: "app",
   storage: localStorage,

package/core/react-adapter.md

@@ -18,7 +18,7 @@ What are you building?
 Create the system outside of React. Components subscribe to it.
 
 ```typescript
-// system.ts — created once, imported anywhere
+// system.ts – created once, imported anywhere
 import { createSystem } from "@directive-run/core";
 import { counterModule } from "./counter-module";
 
@@ -31,7 +31,7 @@ import { useSelector, useEvent } from "@directive-run/react";
 import { system } from "./system";
 
 function Counter() {
-  // Subscribe to derived state — re-renders only when value changes
+  // 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);
 
@@ -174,10 +174,10 @@ function Dashboard() {
 ## CRITICAL: Hooks That DO NOT Exist
 
 ```typescript
-// WRONG — useDirective() does not exist. This is a common hallucination.
+// WRONG – useDirective() does not exist. This is a common hallucination.
 const { facts, derive, events } = useDirective(system);
 
-// CORRECT — use useSelector for state, useEvent for actions
+// CORRECT – use useSelector for state, useEvent for actions
 const count = useSelector(system, (s) => s.facts.count);
 const events = useEvent(system);
 ```
@@ -187,7 +187,7 @@ const events = useEvent(system);
 ### Creating the system inside a component without useSystem
 
 ```typescript
-// WRONG — creates a new system on every render
+// 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);
@@ -195,7 +195,7 @@ function Counter() {
   return <div>{count}</div>;
 }
 
-// CORRECT — create outside the component
+// CORRECT – create outside the component
 const system = createSystem({ module: counterModule });
 
 function Counter() {
@@ -204,7 +204,7 @@ function Counter() {
   return <div>{count}</div>;
 }
 
-// ALSO CORRECT — useSystem manages lifecycle
+// ALSO CORRECT – useSystem manages lifecycle
 function Counter() {
   const system = useSystem({ module: counterModule });
   const count = useSelector(system, (s) => s.facts.count);
@@ -216,10 +216,10 @@ function Counter() {
 ### Selecting too much state (causes unnecessary re-renders)
 
 ```typescript
-// WRONG — re-renders on ANY fact change
+// WRONG – re-renders on ANY fact change
 const allFacts = useSelector(system, (s) => s.facts);
 
-// CORRECT — select only what you need
+// CORRECT – select only what you need
 const name = useSelector(system, (s) => s.facts.userName);
 const count = useSelector(system, (s) => s.facts.count);
 ```
@@ -227,7 +227,7 @@ const count = useSelector(system, (s) => s.facts.count);
 ### Mutating facts directly in event handlers
 
 ```typescript
-// WRONG — bypass the event system
+// WRONG – bypass the event system
 function Counter() {
   const count = useSelector(system, (s) => s.facts.count);
 
@@ -238,7 +238,7 @@ function Counter() {
   );
 }
 
-// CORRECT — use events for intent-driven mutations
+// CORRECT – use events for intent-driven mutations
 function Counter() {
   const count = useSelector(system, (s) => s.facts.count);
   const events = useEvent(system);
@@ -254,9 +254,9 @@ function Counter() {
 ### Casting values from useSelector
 
 ```typescript
-// WRONG — unnecessary type casting
+// WRONG – unnecessary type casting
 const profile = useSelector(system, (s) => s.facts.profile as UserProfile);
 
-// CORRECT — types are inferred from the module schema
+// CORRECT – types are inferred from the module schema
 const profile = useSelector(system, (s) => s.facts.profile);
 ```

package/core/resolvers.md

@@ -16,7 +16,7 @@ Is the work async (API calls, timers)?
 │   ├── Yes → Add batch config to group them
 │   └── No  → Single resolve is fine
 │
-└── No → Reconsider — maybe this is an event handler or derivation
+└── No → Reconsider – maybe this is an event handler or derivation
 ```
 
 ## Basic Resolver
@@ -27,12 +27,12 @@ resolvers: {
     // Which requirement type this resolver handles
     requirement: "FETCH_USER",
 
-    // Async function — req is the requirement, context has facts + signal
+    // Async function – req is the requirement, context has facts + signal
     resolve: async (req, context) => {
       const res = await fetch(`/api/users/${req.userId}`);
       const user = await res.json();
 
-      // Mutate facts to store results — resolvers return void
+      // Mutate facts to store results – resolvers return void
       context.facts.user = user;
       context.facts.phase = "loaded";
     },
@@ -46,13 +46,13 @@ The `context` object provides:
 
 ```typescript
 resolve: async (req, context) => {
-  // context.facts — mutable proxy to the module's facts
+  // context.facts – mutable proxy to the module's facts
   context.facts.status = "loading";
 
-  // context.signal — AbortSignal, cancelled when system stops or requirement removed
+  // context.signal – AbortSignal, cancelled when system stops or requirement removed
   const res = await fetch("/api/data", { signal: context.signal });
 
-  // context.snapshot() — read-only snapshot for before/after comparisons
+  // context.snapshot() – read-only snapshot for before/after comparisons
   const before = context.snapshot();
   context.facts.count += 1;
   const after = context.snapshot();
@@ -69,7 +69,7 @@ resolvers: {
   fetchUser: {
     requirement: "FETCH_USER",
 
-    // Custom key — only one inflight resolver per userId
+    // Custom key – only one inflight resolver per userId
     key: (req) => `fetch-user-${req.userId}`,
 
     resolve: async (req, context) => {
@@ -270,14 +270,14 @@ const explanation = system.explain("req-123");
 ### Returning data from resolve
 
 ```typescript
-// WRONG — return value is ignored
+// WRONG – return value is ignored
 resolve: async (req, context) => {
   const user = await fetchUser(req.userId);
 
   return user; // Ignored!
 },
 
-// CORRECT — mutate context.facts
+// CORRECT – mutate context.facts
 resolve: async (req, context) => {
   const user = await fetchUser(req.userId);
   context.facts.user = user;
@@ -297,7 +297,7 @@ resolve: async (req, context) => { /* ... */ },
 ### Checking conditions in resolve (constraint's job)
 
 ```typescript
-// WRONG — condition checking belongs in constraint's when()
+// WRONG – condition checking belongs in constraint's when()
 resolve: async (req, context) => {
   if (!context.facts.isAuthenticated) {
     return;
@@ -305,7 +305,7 @@ resolve: async (req, context) => {
   // ...
 },
 
-// CORRECT — let constraints handle conditions
+// CORRECT – let constraints handle conditions
 // The resolver only runs when a requirement is emitted
 resolve: async (req, context) => {
   const data = await fetch("/api/data");
@@ -316,7 +316,7 @@ resolve: async (req, context) => {
 ### Forgetting error handling
 
 ```typescript
-// WRONG — unhandled errors with no recovery
+// WRONG – unhandled errors with no recovery
 resolvers: {
   fetch: {
     requirement: "FETCH",
@@ -327,7 +327,7 @@ resolvers: {
   },
 },
 
-// CORRECT — retry policy + error handling
+// CORRECT – retry policy + error handling
 resolvers: {
   fetch: {
     requirement: "FETCH",
@@ -346,7 +346,7 @@ resolvers: {
 ### Missing settle() after start()
 
 ```typescript
-// WRONG — reading facts before resolvers finish
+// WRONG – reading facts before resolvers finish
 system.start();
 console.log(system.facts.data); // Likely null
 

package/core/schema-types.md

@@ -32,7 +32,7 @@ const myModule = createModule("example", {
       // Basic string
       name: t.string(),
 
-      // String literal union — full type safety
+      // String literal union – full type safety
       phase: t.string<"idle" | "loading" | "done">(),
 
       // Number with validation
@@ -85,11 +85,11 @@ schema: {
 ```typescript
 schema: {
   facts: {
-    // Enum — string literal union from values
+    // Enum – string literal union from values
     status: t.enum("pending", "active", "archived"),
     // TypeScript type: "pending" | "active" | "archived"
 
-    // Literal — exact match
+    // Literal – exact match
     version: t.literal(2),
     mode: t.literal("strict"),
     enabled: t.literal(true),
@@ -102,13 +102,13 @@ schema: {
 ```typescript
 schema: {
   facts: {
-    // Nullable — T | null
+    // Nullable – T | null
     selectedItem: t.nullable(t.string()),
 
-    // Optional — T | undefined
+    // Optional – T | undefined
     nickname: t.optional(t.string()),
 
-    // Union — combine types
+    // Union – combine types
     result: t.union(t.string(), t.number()),
 
     // Nullable via object generic (also valid)
@@ -122,28 +122,28 @@ schema: {
 ```typescript
 schema: {
   facts: {
-    // Default value — used if init doesn't set it
+    // Default value – used if init doesn't set it
     theme: t.string<"light" | "dark">().default("light"),
 
-    // Custom validation — runs in dev mode
+    // Custom validation – runs in dev mode
     email: t.string().validate((val) => val.includes("@")),
 
-    // Transform on set — runs when fact is mutated
+    // Transform on set – runs when fact is mutated
     slug: t.string().transform((val) => val.toLowerCase().replace(/\s+/g, "-")),
 
-    // Branded type — nominal typing
+    // Branded type – nominal typing
     userId: t.string().brand<"UserId">(),
 
-    // Description — for docs and devtools
+    // Description – for docs and devtools
     retryCount: t.number().describe("Number of failed attempts"),
 
-    // Refinement — predicate with error message
+    // Refinement – predicate with error message
     port: t.number().refine(
       (n) => n >= 1 && n <= 65535,
       "Port must be between 1 and 65535",
     ),
 
-    // Chaining — combine multiple modifiers
+    // Chaining – combine multiple modifiers
     score: t.number()
       .min(0)
       .max(100)
@@ -193,43 +193,43 @@ schema: {
 These are common AI hallucinations. Do not use them.
 
 ```typescript
-// WRONG — t.map() does not exist
+// WRONG – t.map() does not exist
 items: t.map<string, number>(),
 // CORRECT
 items: t.object<Map<string, number>>(),
 
-// WRONG — t.set() does not exist
+// WRONG – t.set() does not exist
 tags: t.set<string>(),
 // CORRECT
 tags: t.object<Set<string>>(),
 
-// WRONG — t.date() does not exist
+// WRONG – t.date() does not exist
 createdAt: t.date(),
 // CORRECT
 createdAt: t.object<Date>(),
 // OR use timestamps
 createdAt: t.number(), // Unix ms
 
-// WRONG — t.tuple() does not exist
+// WRONG – t.tuple() does not exist
 coords: t.tuple<[number, number]>(),
 // CORRECT
 coords: t.array<[number, number]>(),
 
-// WRONG — t.record() does not exist
+// WRONG – t.record() does not exist
 scores: t.record<string, number>(),
 // CORRECT
 scores: t.object<Record<string, number>>(),
 
-// WRONG — t.promise() does not exist (facts are synchronous)
+// WRONG – t.promise() does not exist (facts are synchronous)
 result: t.promise<string>(),
 
-// WRONG — t.any() does not exist
+// WRONG – t.any() does not exist
 data: t.any(),
 // CORRECT
 data: t.object<unknown>(),
 
-// WRONG — t.void() does not exist (not a fact type)
-// WRONG — t.function() does not exist (functions are not serializable)
+// WRONG – t.void() does not exist (not a fact type)
+// WRONG – t.function() does not exist (functions are not serializable)
 ```
 
 ## Type Assertion Alternative