@directive-run/claude-plugin 1.16.0

package/skills/writing-directive-constraints/resolvers.md

@@ -0,0 +1,367 @@
+# Resolvers
+
+> Covers `@directive-run/core` — resolver definition: retry policies, batching, cancellation, custom dedup keys, `owns` binding.
+
+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
+```
+
+## See also
+
+- [`constraints.md`](./constraints.md) — the demand side of the loop; what emits the requirements this resolver fulfills
+- [`core-patterns.md`](./core-patterns.md) — how resolvers fit into the module shape
+- [`error-boundaries.md`](./error-boundaries.md) — recovery strategies when a resolver throws (retry, fallback, circuit breaker)
+- [`testing.md`](./testing.md) — mock resolvers via `mocks.resolvers` and the programmatic `mockResolver(type)` helper
+- [`anti-patterns.md`](./anti-patterns.md) — the resolver-shaped mistakes (returning data from `resolve`, abbreviating `context` to `ctx`)

package/skills/writing-directive-modules/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: writing-directive-modules
+description: "Create and structure Directive modules with schema definitions, init functions, derivations, effects, events, constraints, and resolvers using the correct t.* type builders and naming conventions. Use when asked to build a Directive module, add facts/derivations/resolvers to an existing module, or scaffold any stateful domain with Directive."
+---
+
+# Writing Directive Modules
+
+## Prerequisites
+
+This skill applies when the project uses `@directive-run/core`. If not found in `package.json`, suggest installing it: `npm install @directive-run/core`.
+
+## When Claude Should Use This Skill
+
+**Auto-invoke when the user:**
+- Says "create a module", "add a fact", "build with Directive", or "scaffold state"
+- Asks to model a domain (auth, cart, user profile, game state, etc.) in Directive
+- Shows a `createModule()` call and asks to extend it
+- Asks about schema types, derivations, effects, resolvers, or events in Directive context
+
+**Do NOT invoke when:**
+- Working on system composition (see `building-directive-systems.md`)
+- Writing tests (see `testing-directive-code.md`)
+- Asking about constraints/resolver interaction patterns only (see `writing-directive-constraints.md`)
+
+---
+
+## Module Shape – Canonical Form
+
+```typescript
+import { createModule, t } from "@directive-run/core";
+
+const myModule = createModule("name", {
+  schema: {
+    facts: {
+      phase: t.string<"idle" | "loading" | "done">(),
+      count: t.number(),
+      user: t.object<{ id: string; name: string } | null>(),
+    },
+    derivations: {      // Optional – declare types here, define in derive
+      isLoading: t.boolean(),
+      displayName: t.string(),
+    },
+    events: {           // Optional – declare event payloads here
+      increment: {},
+      setUser: { user: t.object<{ id: string; name: string }>() },
+    },
+    requirements: {     // Optional – declare requirement payloads here
+      FETCH_USER: { userId: t.string() },
+    },
+  },
+
+  init: (facts) => {    // Synchronous. Sets all facts to initial values.
+    facts.phase = "idle";
+    facts.count = 0;
+    facts.user = null;
+  },
+
+  derive: {             // Auto-tracked – no manual deps needed
+    isLoading: (facts) => facts.phase === "loading",
+    displayName: (facts) => {
+      if (!facts.user) {
+        return "Guest";
+      }
+
+      return facts.user.name;
+    },
+  },
+
+  effects: {            // Fire-and-forget side effects
+    logPhase: {
+      run: (facts, prev) => {
+        if (prev?.phase !== facts.phase) {
+          console.log(`Phase: ${facts.phase}`);
+        }
+      },
+    },
+  },
+
+  events: {             // Synchronous fact mutations driven by user actions
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    setUser: (facts, payload) => {
+      facts.user = payload.user;
+    },
+  },
+
+  constraints: {        // WHEN conditions are true, REQUIRE something
+    fetchWhenReady: {
+      when: (facts) => facts.phase === "idle" && facts.count > 0,
+      require: (facts) => ({ type: "FETCH_USER", userId: "user-1" }),
+    },
+  },
+
+  resolvers: {          // HOW to fulfill requirements
+    fetchUser: {
+      requirement: "FETCH_USER",
+      resolve: async (req, context) => {
+        context.facts.phase = "loading";
+        const res = await fetch(`/api/users/${req.userId}`);
+        context.facts.user = await res.json();
+        context.facts.phase = "done";
+      },
+    },
+  },
+});
+```
+
+---
+
+## Decision Tree: Where Does This Logic Go?
+
+```
+What does this code do?
+├── Store a value that changes over time
+│   └── schema.facts + init()
+├── Compute a value from other facts (synchronous, cached)
+│   └── schema.derivations + derive
+├── React to fact changes (side effect, fire-and-forget)
+│   └── effects
+├── Respond to a user action
+│   └── schema.events + events
+├── Declare "when X is true, the system needs Y"
+│   └── constraints
+└── Fulfill a requirement with async work
+    └── resolvers
+```
+
+---
+
+## Schema Type Builders
+
+### Which builder to use
+
+```
+Value type?
+├── string (possibly with union)  → t.string() or t.string<"a" | "b">()
+├── number (possibly with bounds) → t.number() or t.number().min(0).max(100)
+├── boolean                       → t.boolean()
+├── object / record               → t.object<Shape>()
+├── array                         → t.array<ItemType>()
+├── string literal union          → t.enum("a", "b", "c")
+├── exact value                   → t.literal(42)
+├── T | null                      → t.nullable(t.string()) or t.object<T | null>()
+├── T | undefined                 → t.optional(t.string())
+└── Map / Set / Date              → t.object<Map<K,V>>() / t.object<Set<T>>() / t.object<Date>()
+```
+
+### Chainable modifiers (available on all types)
+
+```typescript
+t.string().default("light")         // Default if init doesn't set it
+t.string().validate((v) => v.includes("@"))  // Dev-mode validation
+t.string().transform((v) => v.trim())         // Runs on every set
+t.string().brand<"UserId">()         // Nominal typing
+t.number().min(0).max(100).describe("Player score")
+t.array<string>().nonEmpty().maxLength(10)
+t.object<{ url: string }>().nonNull()
+```
+
+### Type assertion alternative (for simple schemas)
+
+```typescript
+schema: {
+  facts: {} as { count: number; name: string },
+  derivations: {} as { doubled: number },
+},
+```
+
+Gives full TypeScript inference, skips runtime validation.
+
+---
+
+## Key Patterns
+
+### Derivation composition (derivation depending on another)
+
+```typescript
+derive: {
+  isRed: (facts) => facts.phase === "red",
+  status: (facts, derived) => ({   // Second param accesses other derivations
+    phase: facts.phase,
+    isRed: derived.isRed,
+  }),
+},
+```
+
+### Dynamic requirement from facts
+
+```typescript
+constraints: {
+  fetchUser: {
+    when: (facts) => facts.isAuthenticated && !facts.profile,
+    require: (facts) => ({ type: "FETCH_USER", userId: facts.userId }),
+  },
+},
+```
+
+### Returning null from require to suppress
+
+```typescript
+require: (facts) => {
+  if (!facts.userId) {
+    return null;  // No requirement emitted
+  }
+
+  return { type: "FETCH_USER", userId: facts.userId };
+},
+```
+
+### Array/object mutation – always replace, never mutate in place
+
+```typescript
+// CORRECT
+facts.items = [...facts.items, newItem];
+facts.config = { ...facts.config, theme: "dark" };
+```
+
+---
+
+## Critical Anti-Patterns
+
+### 1. Missing facts wrapper in schema
+
+```typescript
+// WRONG
+schema: { phase: t.string(), count: t.number() }
+
+// CORRECT
+schema: { facts: { phase: t.string(), count: t.number() } }
+```
+
+### 2. Nonexistent type builders
+
+```typescript
+// WRONG – these do not exist
+t.map<string, User>()
+t.set<string>()
+t.date()
+t.record<string, number>()
+t.any()
+
+// CORRECT
+t.object<Map<string, User>>()
+t.object<Set<string>>()
+t.object<Date>()
+t.object<Record<string, number>>()
+t.object<unknown>()
+```
+
+### 3. Async init
+
+```typescript
+// WRONG – init is synchronous
+init: async (facts) => { facts.config = await fetch("/api/config").then(r => r.json()); }
+
+// CORRECT – init sets defaults; async work goes in constraints/resolvers
+init: (facts) => { facts.config = null; }
+```
+
+### 4. Resolver parameter naming
+Always use `(req, context)` – never `(req, ctx)` or `(request, context)`.
+
+### 5. Resolver returning data
+
+```typescript
+// WRONG – return value is ignored
+resolve: async (req, context) => { return await fetchUser(req.userId); }
+
+// CORRECT – mutate context.facts
+resolve: async (req, context) => { context.facts.user = await fetchUser(req.userId); }
+```
+
+### 6. Unnecessary type casting
+
+```typescript
+// WRONG
+const profile = system.facts.profile as UserProfile;
+
+// CORRECT – schema provides the type
+const profile = system.facts.profile;
+```
+
+### 7. Passthrough derivations
+
+```typescript
+// WRONG – derivation just returns a fact unchanged
+derive: { count: (facts) => facts.count }
+
+// CORRECT – read the fact directly: system.facts.count
+```
+
+### 8. String require instead of object
+
+```typescript
+// WRONG
+require: "FETCH_DATA"
+
+// CORRECT
+require: { type: "FETCH_DATA" }
+```
+
+### 9. Accessing facts.self in single-module context
+
+```typescript
+// facts.self.* is only for multi-module cross-module deps contexts
+// In single-module resolvers: use context.facts.fieldName directly
+```
+
+### 10. Deep imports
+
+```typescript
+// WRONG
+import { createModule } from "@directive-run/core/module";
+
+// CORRECT
+import { createModule } from "@directive-run/core";
+// Exception: plugins use @directive-run/core/plugins
+```
+
+---
+
+## Terminology Quick Reference
+
+| Use | Never Use |
+|-----|-----------|
+| `facts` | state, store, atoms |
+| `derivations` / `derive` | computed, selectors, getters, memos |
+| `constraints` | rules, conditions, triggers |
+| `resolvers` | handlers, actions, reducers |
+| `requirements` | requests, commands |
+| `effects` | watchers, subscriptions, reactions |
+| `(req, context)` | `(req, ctx)` or `(request, context)` |
+
+---
+
+## Reference Files
+
+- `core-patterns.md` – decision trees, full module example, system creation patterns
+- `schema-types.md` – complete t.* builder reference, chainable methods, nonexistent types
+- `naming.md` – req/context rules, return style, blank-line conventions, multi-module naming
+- `anti-patterns.md` – 20 ranked anti-patterns with correct/wrong examples