@directive-run/knowledge 0.2.0

package/core/anti-patterns.md

@@ -0,0 +1,382 @@
+# Anti-Patterns
+
+20 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
+
+```typescript
+// WRONG — schema already provides the type
+const profile = system.facts.profile as ResourceState<Profile>;
+
+// CORRECT — trust the schema
+const profile = system.facts.profile;
+```
+
+## 2. Flat Schema (Missing facts Wrapper)
+
+```typescript
+// WRONG — facts must be nested under schema.facts
+createModule("counter", {
+  schema: {
+    phase: t.string(),
+    count: t.number(),
+  },
+});
+
+// CORRECT
+createModule("counter", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      count: t.number(),
+    },
+  },
+});
+```
+
+## 3. Bare `facts.*` in Multi-Module Constraints
+
+```typescript
+// WRONG — multi-module constraints use facts.self for own module
+constraints: {
+  checkItems: {
+    when: (facts) => facts.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+
+// CORRECT — use facts.self.* for own module facts
+constraints: {
+  checkItems: {
+    when: (facts) => facts.self.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+```
+
+## 4. Nonexistent Schema Builders
+
+```typescript
+// WRONG — t.map(), t.set(), t.promise() do not exist
+schema: {
+  facts: {
+    cache: t.map<string, User>(),
+    tags: t.set<string>(),
+    pending: t.promise<Data>(),
+  },
+},
+
+// CORRECT — use t.object() with type parameter
+schema: {
+  facts: {
+    cache: t.object<Map<string, User>>(),
+    tags: t.object<Set<string>>(),
+    pending: t.object<Promise<Data>>(),
+  },
+},
+```
+
+## 5. Abbreviating `context` to `ctx`
+
+```typescript
+// WRONG — never abbreviate context
+resolve: async (req, ctx) => {
+  ctx.facts.status = "done";
+},
+
+// CORRECT — always spell out context
+resolve: async (req, context) => {
+  context.facts.status = "done";
+},
+```
+
+## 6. Flat Module Config (No schema Wrapper)
+
+```typescript
+// WRONG — properties must be inside schema.facts
+createModule("timer", {
+  phase: t.string(),
+  elapsed: t.number(),
+});
+
+// CORRECT — wrap in schema: { facts: {} }
+createModule("timer", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      elapsed: t.number(),
+    },
+  },
+});
+```
+
+## 7. String-Based Event Dispatch
+
+```typescript
+// WRONG — events are not dispatched by string
+system.dispatch("login", { token: "abc" });
+
+// CORRECT — use the events accessor
+system.events.login({ token: "abc" });
+```
+
+## 8. Direct Array/Object Mutation
+
+```typescript
+// WRONG — proxy cannot detect in-place mutations
+facts.items.push(item);
+facts.config.theme = "dark";
+
+// CORRECT — replace the entire value
+facts.items = [...facts.items, item];
+facts.config = { ...facts.config, theme: "dark" };
+```
+
+## 9. Nonexistent `useDirective` Hook
+
+```typescript
+// WRONG — there is no useDirective hook
+const state = useDirective(system);
+
+// CORRECT — use useSelector with a selector function
+const count = useSelector(system, (s) => s.facts.count);
+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
+const status = facts["auth::status"];
+const token = facts["auth_token"];
+
+// CORRECT — use dot notation through the namespace proxy
+const status = facts.auth.status;
+const token = facts.auth.token;
+```
+
+## 11. Builder/Chaining API
+
+```typescript
+// WRONG — there is no builder pattern
+const mod = module("counter")
+  .schema({ count: t.number() })
+  .build();
+
+// CORRECT — use createModule with object syntax
+const mod = createModule("counter", {
+  schema: {
+    facts: { count: t.number() },
+  },
+});
+```
+
+## 12. Returning Data from Resolvers
+
+```typescript
+// 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
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+  context.facts.user = user;
+},
+```
+
+## 13. Async Logic in `init`
+
+```typescript
+// 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
+init: (facts) => {
+  facts.config = null;
+  facts.phase = "loading";
+},
+
+constraints: {
+  loadConfig: {
+    when: (facts) => facts.config === null,
+    require: { type: "LOAD_CONFIG" },
+  },
+},
+```
+
+## 14. Missing `settle()` After `start()`
+
+```typescript
+// 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
+system.start();
+await system.settle();
+console.log(system.facts.data); // Resolved
+```
+
+## 15. Missing `crossModuleDeps` Declaration
+
+```typescript
+// WRONG — accessing auth facts without declaring dependency
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated, // Type error
+      require: { type: "FETCH" },
+    },
+  },
+});
+
+// CORRECT — declare crossModuleDeps for type-safe cross-module access
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  crossModuleDeps: { auth: authSchema },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated,
+      require: { type: "FETCH" },
+    },
+  },
+});
+```
+
+## 16. String Literal for `require`
+
+```typescript
+// WRONG — require must be an object with type property
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: "FETCH_DATA",
+  },
+},
+
+// CORRECT — use object form with type
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: { type: "FETCH_DATA" },
+  },
+},
+```
+
+## 17. Passthrough Derivations
+
+```typescript
+// WRONG — derivation just returns a fact value unchanged
+derive: {
+  count: (facts) => facts.count,
+},
+
+// 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
+import { createModule } from "@directive-run/core/module";
+import { createSystem } from "@directive-run/core/system";
+
+// CORRECT — import from package root
+import { createModule, createSystem } from "@directive-run/core";
+
+// Exception: plugins have their own entry point
+import { loggingPlugin } from "@directive-run/core/plugins";
+```
+
+## 19. Async `when()` Without `deps`
+
+```typescript
+// WRONG — async constraints need explicit deps for tracking
+constraints: {
+  validate: {
+    async: true,
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+
+// CORRECT — add deps array for async constraints
+constraints: {
+  validate: {
+    async: true,
+    deps: ["token"],
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+```
+
+## 20. No Error Handling on Failing Resolvers
+
+```typescript
+// WRONG — unhandled errors crash the system
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// CORRECT — use retry policy and/or module error boundary
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    retry: { attempts: 3, backoff: "exponential" },
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// Also set error boundary at system level
+const system = createSystem({
+  module: myModule,
+  errorBoundary: {
+    onResolverError: "retry-later",
+  },
+});
+```
+
+## Quick Reference Checklist
+
+Before generating any Directive code, verify:
+
+1. Schema is nested: `schema: { facts: { ... } }` (not flat)
+2. No `as` casts when reading facts or derivations
+3. Resolver params are `(req, context)` not `(req, ctx)`
+4. `require` is an object `{ type: "..." }` not a string
+5. `init()` is synchronous
+6. Resolvers return void and mutate `context.facts`
+7. Arrays/objects replaced, not mutated in place
+8. Multi-module uses `facts.self.*` for own facts
+9. Imports from `@directive-run/core`, not deep paths
+10. `await system.settle()` after `system.start()`

package/core/constraints.md

@@ -0,0 +1,263 @@
+# Constraints
+
+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?"
+
+```
+Is this a condition that triggers work?
+├── Yes, and the work is async/side-effectful → Constraint + Resolver
+├── Yes, but the work is just a state derivation → Use derive instead
+├── No, it's reacting to a change that already happened → Use effect
+└── No, it's user-initiated → Use event handler
+```
+
+## Basic Constraint Anatomy
+
+A constraint has two parts: `when` (condition) and `require` (what's needed).
+
+```typescript
+constraints: {
+  fetchUserWhenReady: {
+    // 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 },
+  },
+},
+```
+
+### Static vs Dynamic Requirements
+
+```typescript
+// Static requirement — same object every time
+constraints: {
+  loadConfig: {
+    when: (facts) => facts.config === null,
+    require: { type: "LOAD_CONFIG" },
+  },
+},
+
+// Dynamic requirement — function that reads facts
+constraints: {
+  fetchUser: {
+    when: (facts) => facts.isAuthenticated && !facts.profile,
+    require: (facts) => ({ type: "FETCH_USER", userId: facts.userId }),
+  },
+},
+
+// Multiple requirements — return an array
+constraints: {
+  loadAll: {
+    when: (facts) => facts.phase === "init",
+    require: [
+      { type: "LOAD_CONFIG" },
+      { type: "LOAD_USER" },
+    ],
+  },
+},
+```
+
+## Priority
+
+Higher priority constraints are evaluated first. Use priority for conflict resolution when multiple constraints could fire simultaneously.
+
+```typescript
+constraints: {
+  normalTransition: {
+    priority: 50,
+    when: (facts) => facts.phase === "red" && facts.elapsed > 30,
+    require: { type: "TRANSITION", to: "green" },
+  },
+
+  emergencyOverride: {
+    priority: 100, // Evaluated before normalTransition
+    when: (facts) => facts.emergencyActive,
+    require: { type: "TRANSITION", to: "red" },
+  },
+},
+```
+
+Default priority is 0. Higher numbers run first.
+
+## Ordering with `after`
+
+Use `after` to declare that a constraint should only be evaluated after another constraint's resolver completes. This is different from priority (evaluation order) -- `after` blocks evaluation entirely until the dependency is resolved.
+
+```typescript
+constraints: {
+  authenticate: {
+    when: (facts) => !facts.token,
+    require: { type: "AUTHENTICATE" },
+  },
+
+  // Only evaluate after authenticate's resolver completes
+  loadProfile: {
+    after: ["authenticate"],
+    when: (facts) => facts.token && !facts.profile,
+    require: { type: "LOAD_PROFILE" },
+  },
+
+  // Cross-module after reference
+  loadData: {
+    after: ["auth::authenticate"],
+    when: (facts) => facts.self.dataNeeded,
+    require: { type: "LOAD_DATA" },
+  },
+},
+```
+
+If the dependency's `when()` returns false (no requirement emitted), the blocked constraint proceeds normally. If the dependency's resolver fails, the blocked constraint remains blocked.
+
+## Async Constraints
+
+For conditions that require async evaluation (e.g., remote validation). Async constraints MUST declare `deps` for dependency tracking.
+
+```typescript
+constraints: {
+  validateToken: {
+    async: true,
+    deps: ["token"], // REQUIRED for async constraints
+
+    when: async (facts) => {
+      const valid = await validateTokenRemotely(facts.token);
+
+      return valid;
+    },
+
+    require: { type: "REFRESH_TOKEN" },
+    timeout: 5000, // Optional timeout in ms
+  },
+},
+```
+
+### Why `deps` is Required for Async
+
+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
+constraints: {
+  check: {
+    async: true,
+    when: async (facts) => await validate(facts.token),
+    require: { type: "REFRESH" },
+  },
+},
+
+// CORRECT — deps tells the engine to re-evaluate when token changes
+constraints: {
+  check: {
+    async: true,
+    deps: ["token"],
+    when: async (facts) => await validate(facts.token),
+    require: { type: "REFRESH" },
+  },
+},
+```
+
+## Disabling Constraints at Runtime
+
+```typescript
+const system = createSystem({ module: myModule });
+system.start();
+
+// 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
+system.constraints.enable("fetchUserWhenReady");
+```
+
+## Common Mistakes
+
+### Putting async logic in resolvers instead of constraints
+
+```typescript
+// WRONG — resolver checks conditions (constraint's job)
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      if (!context.facts.isAuthenticated) {
+        return; // Should be in constraint's when()
+      }
+      // ...
+    },
+  },
+},
+
+// CORRECT — constraint declares when, resolver just does the work
+constraints: {
+  fetchWhenAuth: {
+    when: (facts) => facts.isAuthenticated && !facts.data,
+    require: { type: "FETCH" },
+  },
+},
+
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      context.facts.data = await res.json();
+    },
+  },
+},
+```
+
+### String literal for require
+
+```typescript
+// WRONG — require must be an object
+require: "FETCH_DATA",
+
+// CORRECT — object with type property
+require: { type: "FETCH_DATA" },
+
+// CORRECT — with payload
+require: { type: "FETCH_DATA", endpoint: "/api/users" },
+
+// CORRECT — dynamic from facts
+require: (facts) => ({ type: "FETCH_DATA", userId: facts.currentUserId }),
+```
+
+### Returning null to conditionally skip
+
+```typescript
+// require can return null to suppress the requirement
+constraints: {
+  conditionalFetch: {
+    when: (facts) => facts.needsUpdate,
+    require: (facts) => {
+      if (!facts.userId) {
+        return null; // No requirement emitted
+      }
+
+      return { type: "FETCH_USER", userId: facts.userId };
+    },
+  },
+},
+```
+
+## Constraints vs Effects vs Derivations
+
+| Feature | Purpose | Triggers |
+|---|---|---|
+| Constraint | Declare a need (emit requirement) | Fact changes, re-evaluated automatically |
+| Resolver | Fulfill a need (async work) | Requirement emitted by constraint |
+| Effect | React to changes (fire-and-forget) | Fact changes, runs after reconciliation |
+| Derivation | Compute a value (synchronous, cached) | Fact changes, recomputed lazily |
+
+### When to Use Which
+
+```
+"When X is true, the system needs Y" → Constraint
+"Do Y" → Resolver
+"Whenever X changes, log it" → Effect
+"X is always facts.a + facts.b" → Derivation
+```