@directive-run/knowledge 0.2.0

package/core/resolvers.md

@@ -0,0 +1,357 @@
+# Resolvers
+
+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?"
+
+```
+Is the work async (API calls, timers)?
+├── Yes → Use resolve: async (req, context) => { ... }
+│
+│   Does it fail often?
+│   ├── Yes → Add retry: { attempts: 3, backoff: "exponential" }
+│   └── No  → No retry needed
+│
+│   Are there many similar requirements at once?
+│   ├── Yes → Add batch config to group them
+│   └── No  → Single resolve is fine
+│
+└── No → Reconsider — maybe this is an event handler or derivation
+```
+
+## Basic Resolver
+
+```typescript
+resolvers: {
+  fetchUser: {
+    // Which requirement type this resolver handles
+    requirement: "FETCH_USER",
+
+    // 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
+      context.facts.user = user;
+      context.facts.phase = "loaded";
+    },
+  },
+},
+```
+
+## Resolver Context
+
+The `context` object provides:
+
+```typescript
+resolve: async (req, context) => {
+  // context.facts — mutable proxy to the module's facts
+  context.facts.status = "loading";
+
+  // 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
+  const before = context.snapshot();
+  context.facts.count += 1;
+  const after = context.snapshot();
+  console.log(`Count: ${before.count} -> ${after.count}`);
+},
+```
+
+## Custom Deduplication Keys
+
+By default, requirements are deduped by their full content. Use `key` for custom deduplication:
+
+```typescript
+resolvers: {
+  fetchUser: {
+    requirement: "FETCH_USER",
+
+    // Custom key — only one inflight resolver per userId
+    key: (req) => `fetch-user-${req.userId}`,
+
+    resolve: async (req, context) => {
+      const user = await fetchUser(req.userId);
+      context.facts.user = user;
+    },
+  },
+},
+```
+
+Without `key`, two requirements `{ type: "FETCH_USER", userId: "1" }` are deduped because they are structurally identical. With `key`, you control exactly what counts as a duplicate.
+
+## Retry Policies
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+
+    retry: {
+      // Maximum number of attempts (including the first)
+      attempts: 3,
+
+      // Backoff strategy between retries
+      backoff: "exponential", // "none" | "linear" | "exponential"
+
+      // Initial delay in ms (default: 100)
+      initialDelay: 200,
+
+      // Maximum delay in ms (caps exponential growth)
+      maxDelay: 5000,
+
+      // Optional: only retry certain errors
+      shouldRetry: (error, attempt) => {
+        // Don't retry 4xx client errors
+        if (error.message.includes("404")) {
+          return false;
+        }
+
+        return true;
+      },
+    },
+
+    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();
+    },
+  },
+},
+```
+
+### Backoff Strategies
+
+| Strategy | Delay Pattern |
+|---|---|
+| `"none"` | No delay between retries |
+| `"linear"` | initialDelay, 2x, 3x, ... |
+| `"exponential"` | initialDelay, 2x, 4x, 8x, ... (capped by maxDelay) |
+
+## Batch Resolution
+
+Group similar requirements and resolve them together. Prevents N+1 problems.
+
+### All-or-Nothing Batch
+
+```typescript
+resolvers: {
+  fetchUsers: {
+    requirement: "FETCH_USER",
+
+    batch: {
+      enabled: true,
+      windowMs: 50,   // Collect requirements for 50ms
+      maxSize: 20,    // Flush immediately at 20 items
+    },
+
+    // resolveBatch receives all collected requirements
+    resolveBatch: async (reqs, context) => {
+      const ids = reqs.map((req) => req.userId);
+      const users = await fetchUsersBatch(ids);
+
+      // Store results
+      context.facts.users = users;
+    },
+  },
+},
+```
+
+### Batch with Per-Item Results
+
+For partial success/failure handling:
+
+```typescript
+resolvers: {
+  fetchUsers: {
+    requirement: "FETCH_USER",
+
+    batch: {
+      enabled: true,
+      windowMs: 50,
+      maxSize: 20,
+      timeoutMs: 10000, // Per-batch timeout
+    },
+
+    // Return results array matching input order
+    resolveBatchWithResults: async (reqs, context) => {
+      const results = await Promise.all(
+        reqs.map(async (req) => {
+          try {
+            const user = await fetchUser(req.userId);
+            context.facts.users = {
+              ...context.facts.users,
+              [req.userId]: user,
+            };
+
+            return { success: true };
+          } catch (error) {
+            return { success: false, error: error as Error };
+          }
+        }),
+      );
+
+      return results;
+    },
+  },
+},
+```
+
+Failed items from `resolveBatchWithResults` can be individually retried if a retry policy is configured.
+
+## Timeout
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    timeout: 10000, // Abort after 10 seconds
+
+    resolve: async (req, context) => {
+      // context.signal is automatically aborted on timeout
+      const res = await fetch("/api/data", { signal: context.signal });
+      context.facts.data = await res.json();
+    },
+  },
+},
+```
+
+## Waiting for Resolution
+
+```typescript
+const system = createSystem({ module: myModule });
+system.start();
+
+// Wait for all resolvers to complete
+await system.settle();
+
+// Wait with timeout
+await system.settle(5000); // Throws if not settled in 5s
+
+// Check settlement state
+system.isSettled; // boolean
+
+// Subscribe to settlement changes
+const unsub = system.onSettledChange(() => {
+  console.log("Settlement state:", system.isSettled);
+});
+```
+
+## Inspecting Resolver Status
+
+```typescript
+const inspection = system.inspect();
+
+// All resolver definitions
+inspection.resolverDefs;
+// [{ id: "fetchUser", requirement: "FETCH_USER" }, ...]
+
+// Current resolver statuses
+inspection.resolvers;
+// { fetchUser: { state: "success", completedAt: ..., duration: 150 } }
+
+// Inflight resolvers
+inspection.inflight;
+// [{ id: "req-1", resolverId: "fetchData", startedAt: 1709000000 }]
+
+// Unmet requirements (no resolver matched)
+inspection.unmet;
+
+// Explain why a specific requirement exists
+const explanation = system.explain("req-123");
+```
+
+## Common Mistakes
+
+### Returning data from resolve
+
+```typescript
+// WRONG — return value is ignored
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+
+  return user; // Ignored!
+},
+
+// CORRECT — mutate context.facts
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+  context.facts.user = user;
+},
+```
+
+### Abbreviating context to ctx
+
+```typescript
+// WRONG
+resolve: async (req, ctx) => { /* ... */ },
+
+// CORRECT
+resolve: async (req, context) => { /* ... */ },
+```
+
+### Checking conditions in resolve (constraint's job)
+
+```typescript
+// WRONG — condition checking belongs in constraint's when()
+resolve: async (req, context) => {
+  if (!context.facts.isAuthenticated) {
+    return;
+  }
+  // ...
+},
+
+// CORRECT — let constraints handle conditions
+// The resolver only runs when a requirement is emitted
+resolve: async (req, context) => {
+  const data = await fetch("/api/data");
+  context.facts.data = await data.json();
+},
+```
+
+### Forgetting error handling
+
+```typescript
+// WRONG — unhandled errors with no recovery
+resolvers: {
+  fetch: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      const res = await fetch("/api");
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// CORRECT — retry policy + error handling
+resolvers: {
+  fetch: {
+    requirement: "FETCH",
+    retry: { attempts: 3, backoff: "exponential" },
+    resolve: async (req, context) => {
+      const res = await fetch("/api");
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      context.facts.data = await res.json();
+    },
+  },
+},
+```
+
+### Missing settle() after start()
+
+```typescript
+// WRONG — reading facts before resolvers finish
+system.start();
+console.log(system.facts.data); // Likely null
+
+// CORRECT
+system.start();
+await system.settle();
+console.log(system.facts.data); // Resolved value
+```

package/core/schema-types.md

@@ -0,0 +1,262 @@
+# Schema Types
+
+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?"
+
+```
+What kind of value?
+├── String → t.string() or t.string<"a" | "b">() for literal unions
+├── Number → t.number() with optional .min() / .max()
+├── Boolean → t.boolean()
+├── Array → t.array<ItemType>() with optional .of() / .nonEmpty()
+├── Object/Record → t.object<Shape>()
+├── Fixed set of string values → t.enum("a", "b", "c")
+├── Exact value → t.literal(42) or t.literal("active")
+├── Nullable → t.nullable(t.string())
+├── Optional → t.optional(t.number())
+├── Union → t.union(t.string(), t.number())
+├── Map/Set → t.object<Map<K,V>>() or t.object<Set<T>>()
+├── Date → t.object<Date>() or t.number() for timestamps
+└── Unknown/any → t.object<unknown>()
+```
+
+## Primitive Types
+
+```typescript
+import { createModule, t } from "@directive-run/core";
+
+const myModule = createModule("example", {
+  schema: {
+    facts: {
+      // Basic string
+      name: t.string(),
+
+      // String literal union — full type safety
+      phase: t.string<"idle" | "loading" | "done">(),
+
+      // Number with validation
+      count: t.number(),
+      age: t.number().min(0).max(150),
+
+      // Boolean
+      isActive: t.boolean(),
+    },
+  },
+  init: (facts) => {
+    facts.name = "";
+    facts.phase = "idle";
+    facts.count = 0;
+    facts.age = 25;
+    facts.isActive = false;
+  },
+});
+```
+
+## Complex Types
+
+```typescript
+schema: {
+  facts: {
+    // Object with shape
+    user: t.object<{ id: string; name: string; email: string }>(),
+
+    // Nullable object
+    profile: t.object<{ bio: string; avatar: string } | null>(),
+
+    // Array
+    tags: t.array<string>(),
+    items: t.array<{ id: string; label: string }>().nonEmpty(),
+
+    // Record (key-value map)
+    scores: t.object<Record<string, number>>(),
+
+    // Nested complex type
+    config: t.object<{
+      theme: "light" | "dark";
+      notifications: { email: boolean; push: boolean };
+    }>(),
+  },
+},
+```
+
+## Enum and Literal
+
+```typescript
+schema: {
+  facts: {
+    // Enum — string literal union from values
+    status: t.enum("pending", "active", "archived"),
+    // TypeScript type: "pending" | "active" | "archived"
+
+    // Literal — exact match
+    version: t.literal(2),
+    mode: t.literal("strict"),
+    enabled: t.literal(true),
+  },
+},
+```
+
+## Nullable and Optional
+
+```typescript
+schema: {
+  facts: {
+    // Nullable — T | null
+    selectedItem: t.nullable(t.string()),
+
+    // Optional — T | undefined
+    nickname: t.optional(t.string()),
+
+    // Union — combine types
+    result: t.union(t.string(), t.number()),
+
+    // Nullable via object generic (also valid)
+    user: t.object<{ id: string } | null>(),
+  },
+},
+```
+
+## Chainable Methods (Available on All Types)
+
+```typescript
+schema: {
+  facts: {
+    // Default value — used if init doesn't set it
+    theme: t.string<"light" | "dark">().default("light"),
+
+    // Custom validation — runs in dev mode
+    email: t.string().validate((val) => val.includes("@")),
+
+    // Transform on set — runs when fact is mutated
+    slug: t.string().transform((val) => val.toLowerCase().replace(/\s+/g, "-")),
+
+    // Branded type — nominal typing
+    userId: t.string().brand<"UserId">(),
+
+    // Description — for docs and devtools
+    retryCount: t.number().describe("Number of failed attempts"),
+
+    // 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
+    score: t.number()
+      .min(0)
+      .max(100)
+      .default(0)
+      .describe("Player score"),
+  },
+},
+```
+
+## Array-Specific Methods
+
+```typescript
+schema: {
+  facts: {
+    // Basic array
+    items: t.array<string>(),
+
+    // Non-empty validation
+    requiredItems: t.array<string>().nonEmpty(),
+
+    // Length constraints
+    topFive: t.array<string>().maxLength(5),
+    atLeastThree: t.array<number>().minLength(3),
+
+    // Combined
+    tags: t.array<string>().nonEmpty().maxLength(10),
+  },
+},
+```
+
+## Object-Specific Methods
+
+```typescript
+schema: {
+  facts: {
+    // Non-null assertion
+    config: t.object<{ url: string }>().nonNull(),
+
+    // Required keys validation
+    settings: t.object<Record<string, unknown>>().hasKeys("apiUrl", "timeout"),
+  },
+},
+```
+
+## Types That DO NOT Exist
+
+These are common AI hallucinations. Do not use them.
+
+```typescript
+// WRONG — t.map() does not exist
+items: t.map<string, number>(),
+// CORRECT
+items: t.object<Map<string, number>>(),
+
+// WRONG — t.set() does not exist
+tags: t.set<string>(),
+// CORRECT
+tags: t.object<Set<string>>(),
+
+// 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
+coords: t.tuple<[number, number]>(),
+// CORRECT
+coords: t.array<[number, number]>(),
+
+// 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)
+result: t.promise<string>(),
+
+// 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)
+```
+
+## Type Assertion Alternative
+
+For simple modules, you can skip `t.*()` and use TypeScript type assertions:
+
+```typescript
+const myModule = createModule("simple", {
+  schema: {
+    facts: {} as {
+      count: number;
+      name: string;
+      items: string[];
+    },
+    derivations: {} as {
+      doubled: number;
+    },
+  },
+  init: (facts) => {
+    facts.count = 0;
+    facts.name = "";
+    facts.items = [];
+  },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+  },
+});
+```
+
+This gives full TypeScript inference but skips runtime validation. Use `t.*()` when you want dev-mode validation, transforms, or self-documenting schemas.