@directive-run/claude-plugin 1.16.0

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

@@ -0,0 +1,486 @@
+---
+name: writing-directive-constraints
+description: "Write Directive constraints, resolvers, and error boundaries: when/require patterns, static vs dynamic requirements, async constraints with explicit deps, priority and ordering, resolver retry policies, deduplication keys, batch resolution, and system error boundaries. Use when asked to add constraint-resolver pairs, handle errors/retries in resolvers, or configure recovery strategies."
+---
+
+# Writing Directive Constraints
+
+## 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 "add a constraint", "write a resolver", "handle errors in the resolver", or "add retry"
+- Asks "when X happens, do Y" where Y is async work
+- Shows existing constraints/resolvers and asks to extend or fix them
+- Asks about error handling, recovery strategies, circuit breakers, or retry policies
+- Asks about requirement deduplication, batching, or ordering
+
+**Do NOT invoke when:**
+- Scaffolding an entire module from scratch (start with `writing-directive-modules.md`)
+- Composing multiple modules (see `building-directive-systems.md`)
+- Writing tests (see `testing-directive-code.md`)
+
+---
+
+## The Core Mental Model
+
+```
+Constraint declares WHEN something is needed  →  emits a requirement
+Resolver fulfills WHAT to do about it          →  mutates facts
+```
+
+Never put condition checks in a resolver. Never do async work in a constraint's `when()`.
+
+---
+
+## Decision Tree: Constraint or Something Else?
+
+```
+Is this "when X is true, the system needs Y"?
+├── Yes, and Y is async/side-effectful  → Constraint + Resolver
+├── Yes, but Y is just a derived value  → Use derive instead
+├── No, it reacts to a change that happened → Use effect
+└── No, it's user-initiated             → Use event handler
+```
+
+---
+
+## Constraint Anatomy
+
+### Static vs dynamic requirements
+
+```typescript
+constraints: {
+  // Static – same object every time
+  loadConfig: {
+    when: (facts) => facts.config === null,
+    require: { type: "LOAD_CONFIG" },
+  },
+
+  // Dynamic – function reads facts
+  fetchUser: {
+    when: (facts) => facts.isAuthenticated && !facts.profile,
+    require: (facts) => ({ type: "FETCH_USER", userId: facts.userId }),
+  },
+
+  // Multiple requirements at once
+  loadAll: {
+    when: (facts) => facts.phase === "init",
+    require: [
+      { type: "LOAD_CONFIG" },
+      { type: "LOAD_USER" },
+    ],
+  },
+
+  // Suppress conditionally – return null from require
+  conditionalFetch: {
+    when: (facts) => facts.needsUpdate,
+    require: (facts) => {
+      if (!facts.userId) {
+        return null;
+      }
+
+      return { type: "FETCH_USER", userId: facts.userId };
+    },
+  },
+},
+```
+
+### Priority – conflict resolution
+
+```typescript
+constraints: {
+  normalTransition: {
+    priority: 50,          // Default is 0; higher runs first
+    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" },
+  },
+},
+```
+
+### Ordering with `after` – sequencing constraints
+
+```typescript
+constraints: {
+  authenticate: {
+    when: (facts) => !facts.token,
+    require: { type: "AUTHENTICATE" },
+  },
+
+  // Only evaluates after authenticate's resolver completes
+  loadProfile: {
+    after: ["authenticate"],
+    when: (facts) => facts.token && !facts.profile,
+    require: { type: "LOAD_PROFILE" },
+  },
+},
+```
+
+`after` blocks evaluation entirely until the named constraint's resolver finishes. If the dependency's `when()` returns false, the blocked constraint proceeds normally.
+
+### Async constraints – MUST declare `deps`
+
+Synchronous constraints auto-track deps via proxy. Async constraints cannot (suspended across await), so you must declare `deps` explicitly.
+
+```typescript
+constraints: {
+  validateToken: {
+    async: true,
+    deps: ["token"],          // Re-evaluate when token changes
+    when: async (facts) => {
+      const valid = await validateTokenRemotely(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+    timeout: 5000,            // Optional: abort if check takes too long
+  },
+},
+```
+
+### Disabling constraints at runtime
+
+```typescript
+system.constraints.disable("fetchWhenReady");
+system.constraints.isDisabled("fetchWhenReady"); // true
+system.constraints.enable("fetchWhenReady");
+```
+
+---
+
+## Resolver Anatomy
+
+### Basic resolver
+
+```typescript
+resolvers: {
+  fetchUser: {
+    requirement: "FETCH_USER",
+    resolve: async (req, context) => {
+      // req – the requirement object emitted by the constraint
+      // context.facts – mutable proxy to module facts
+      // context.signal – AbortSignal (cancelled on stop or timeout)
+      // context.snapshot() – read-only snapshot for before/after
+      const user = await fetch(`/api/users/${req.userId}`, {
+        signal: context.signal,
+      }).then((r) => r.json());
+      context.facts.user = user;
+      context.facts.phase = "loaded";
+    },
+  },
+},
+```
+
+### Custom deduplication key
+
+Without `key`, requirements are deduped by structural equality. With `key`, you control dedup:
+
+```typescript
+resolvers: {
+  fetchUser: {
+    requirement: "FETCH_USER",
+    key: (req) => `fetch-user-${req.userId}`, // One inflight per userId
+    resolve: async (req, context) => {
+      context.facts.user = await fetchUser(req.userId);
+    },
+  },
+},
+```
+
+### Retry policy
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    retry: {
+      attempts: 3,
+      backoff: "exponential",   // "none" | "linear" | "exponential"
+      initialDelay: 200,
+      maxDelay: 5000,
+      shouldRetry: (error, attempt) => {
+        if (error.message.includes("404")) {
+          return false;          // Don't retry permanent failures
+        }
+
+        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();
+    },
+  },
+},
+```
+
+### Batch resolution – prevent N+1
+
+```typescript
+resolvers: {
+  fetchUsers: {
+    requirement: "FETCH_USER",
+    batch: {
+      enabled: true,
+      windowMs: 50,     // Collect requirements for 50ms
+      maxSize: 20,      // Flush immediately at 20 items
+    },
+    resolveBatch: async (reqs, context) => {
+      const ids = reqs.map((req) => req.userId);
+      context.facts.users = await fetchUsersBatch(ids);
+    },
+  },
+},
+```
+
+For per-item success/failure, use `resolveBatchWithResults` and return a results array matching input order.
+
+### Timeout
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    timeout: 10000,   // context.signal aborted after 10s
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data", { signal: context.signal });
+      context.facts.data = await res.json();
+    },
+  },
+},
+```
+
+---
+
+## Error Boundaries
+
+### System-level error boundary
+
+```typescript
+const system = createSystem({
+  module: myModule,
+  errorBoundary: {
+    onConstraintError: "skip",
+    onResolverError: "retry-later",
+    onEffectError: "skip",
+    onDerivationError: "throw",   // Derivation errors are bugs – throw always
+    onError: (error) => {
+      console.error(`[${error.source}] ${error.sourceId}: ${error.message}`);
+    },
+    retryLater: {
+      delayMs: 1000,
+      maxRetries: 3,
+      backoffMultiplier: 2,
+      maxDelayMs: 30000,
+    },
+  },
+});
+```
+
+Recovery strategies:
+
+| Strategy | Behavior |
+|----------|----------|
+| `"skip"` | Swallow the error, continue |
+| `"retry"` | Retry immediately |
+| `"retry-later"` | Retry after exponential backoff delay |
+| `"disable"` | Disable the failing constraint/effect permanently |
+| `"throw"` | Re-throw, halting the system |
+
+### Dynamic recovery with functions
+
+```typescript
+errorBoundary: {
+  onResolverError: (error, resolverId) => {
+    if (error.message.includes("NetworkError")) {
+      return "retry-later";
+    }
+
+    if (error.message.includes("401")) {
+      return "skip";
+    }
+
+    return "throw";
+  },
+},
+```
+
+### DirectiveError properties
+
+```typescript
+import { DirectiveError } from "@directive-run/core";
+
+try {
+  await system.settle();
+} catch (err) {
+  if (err instanceof DirectiveError) {
+    err.source;      // "constraint" | "resolver" | "effect" | "derivation" | "system"
+    err.sourceId;    // e.g., "fetchUser"
+    err.recoverable; // boolean
+    err.context;     // debug data (e.g., the requirement object)
+  }
+}
+```
+
+### Module-level lifecycle hooks
+
+```typescript
+hooks: {
+  onInit: (system) => { ... },
+  onStart: (system) => { ... },
+  onStop: (system) => { ... },
+  onError: (error, hookContext) => { ... },
+},
+```
+
+### Circuit breaker
+
+```typescript
+import { createCircuitBreaker } from "@directive-run/core/plugins";
+
+const apiBreaker = createCircuitBreaker({
+  name: "external-api",
+  failureThreshold: 5,
+  recoveryTimeMs: 30000,
+  halfOpenMaxRequests: 3,
+  isFailure: (error) => !error.message.includes("404"),
+  onStateChange: (from, to) => console.log(`Circuit: ${from} -> ${to}`),
+});
+
+// Use in resolvers
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const data = await apiBreaker.execute(async () => {
+        return fetch("/api/data").then((r) => r.json());
+      });
+      context.facts.data = data;
+    },
+  },
+},
+
+// Wire into constraints for automatic fallback
+constraints: {
+  apiDown: {
+    when: () => apiBreaker.getState() === "OPEN",
+    require: { type: "USE_FALLBACK" },
+  },
+  fetchNormally: {
+    when: (facts) => apiBreaker.getState() !== "OPEN" && !facts.data,
+    require: { type: "FETCH_DATA" },
+  },
+},
+```
+
+---
+
+## Critical Anti-Patterns
+
+### 1. Async logic in constraint when()
+
+```typescript
+// WRONG – when() must be synchronous (unless async: true + deps)
+when: async (facts) => {
+  return await validate(facts.token);
+}
+
+// CORRECT – either use async: true with deps, or put validation in resolver
+when: (facts) => Boolean(facts.token),
+```
+
+### 2. Condition checking inside a resolver
+
+```typescript
+// WRONG – resolver should not check conditions (that's the constraint's job)
+resolve: async (req, context) => {
+  if (!context.facts.isAuthenticated) {
+    return;
+  }
+  // ...
+}
+
+// CORRECT – let the constraint's when() gate this
+```
+
+### 3. Async constraint without deps
+
+```typescript
+// WRONG – engine cannot track dependencies
+{ async: true, when: async (facts) => await validate(facts.token) }
+
+// CORRECT
+{ async: true, deps: ["token"], when: async (facts) => await validate(facts.token) }
+```
+
+### 4. String literal for require
+
+```typescript
+// WRONG
+require: "FETCH_DATA"
+
+// CORRECT
+require: { type: "FETCH_DATA" }
+```
+
+### 5. Returning data from a resolver
+
+```typescript
+// WRONG – return value ignored
+resolve: async (req, context) => { return await fetchUser(req.userId); }
+
+// CORRECT
+resolve: async (req, context) => { context.facts.user = await fetchUser(req.userId); }
+```
+
+### 6. Resolver parameter naming
+Always use `(req, context)` – never `(req, ctx)` or `(request, context)`.
+
+### 7. No error handling on network resolvers
+
+```typescript
+// WRONG
+resolve: async (req, context) => {
+  context.facts.data = await fetch("/api").then((r) => r.json());
+}
+
+// CORRECT – add retry and check response status
+resolve: async (req, context) => {
+  const res = await fetch("/api");
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}`);
+  }
+  context.facts.data = await res.json();
+},
+```
+
+---
+
+## Constraint vs Effect vs Derivation
+
+| Feature | Purpose | When to use |
+|---------|---------|-------------|
+| Constraint | Declare a need (emit requirement) | "When X, the system needs Y" |
+| Resolver | Fulfill a need (async work) | "Do Y" |
+| Effect | React to changes (fire-and-forget) | "Whenever X changes, log it" |
+| Derivation | Compute a value (sync, cached) | "X is always facts.a + facts.b" |
+
+---
+
+## Reference Files
+
+- `constraints.md` – full constraint API, async constraints, disabling, common mistakes
+- `resolvers.md` – full resolver API, context object, batch resolution, inspecting resolver status
+- `error-boundaries.md` – all recovery strategies, DirectiveError API, circuit breaker patterns

package/skills/writing-directive-constraints/api-skeleton.md

@@ -0,0 +1,5 @@
+# API Skeleton
+
+> Auto-generated. Do not edit.
+
+> Source JSON not found. Build website docs first.