@directive-run/claude-plugin 1.16.0

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

@@ -0,0 +1,274 @@
+# Constraints
+
+> Covers `@directive-run/core` — constraint definition: `when` / `require`, async constraints with `deps`, priority, data-form predicates.
+
+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.
+    // Use the function form whenever you need to read facts —
+    // facts is NOT in scope inside the static object form.
+    require: (facts) => ({ 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
+```
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — the other half of the constraint-resolver loop; the supply side that fulfills the requirements constraints emit
+- [`core-patterns.md`](./core-patterns.md) — how constraints fit into the module shape alongside facts, derivations, events, and effects
+- [`multi-module.md`](./multi-module.md) — `crossModuleDeps` for constraints that fire on facts owned by another module
+- [`anti-patterns.md`](./anti-patterns.md) — the constraint-shaped mistakes AI assistants reliably make

package/skills/writing-directive-constraints/error-boundaries.md

@@ -0,0 +1,330 @@
+# Error Boundaries
+
+> Covers `@directive-run/core` — error boundaries, recovery strategies, lifecycle hooks, and circuit breakers.
+
+How to handle errors in Directive: recovery strategies, error boundaries, lifecycle hooks, and the circuit breaker pattern.
+
+## Decision Tree: "How should errors be handled?"
+
+```
+Where did the error occur?
+├── Resolver (API call, async work)
+│   ├── Transient failure (network, timeout) → retry / retry-later
+│   ├── Permanent failure (404, auth) → skip or throw
+│   └── Unknown → retry-later with maxRetries
+│
+├── Constraint (evaluation error)
+│   ├── Bug in when() logic → throw (fix the code)
+│   └── Unexpected data shape → skip (disable constraint)
+│
+├── Effect (side effect failed)
+│   ├── Non-critical (logging, analytics) → skip
+│   └── Critical (sync to external system) → retry-later
+│
+├── Derivation (computation error)
+│   └── Usually a bug → throw (fix the code)
+│
+└── External service (repeated failures)
+    └── Circuit breaker pattern
+```
+
+## Recovery Strategies
+
+Directive supports five recovery strategies:
+
+| Strategy | Behavior |
+|---|---|
+| `"skip"` | Swallow the error, continue processing |
+| `"retry"` | Retry immediately (respects resolver retry policy) |
+| `"retry-later"` | Retry after a delay with exponential backoff |
+| `"disable"` | Disable the failing constraint/effect permanently |
+| `"throw"` | Re-throw the error, halting the system |
+
+## System-Level Error Boundary
+
+Configure error handling for the entire system:
+
+```typescript
+const system = createSystem({
+  module: myModule,
+
+  errorBoundary: {
+    // Per-subsystem strategies (string or function)
+    onConstraintError: "skip",
+    onResolverError: "retry-later",
+    onEffectError: "skip",
+    onDerivationError: "throw",
+
+    // Global error callback – fires for all errors
+    onError: (error) => {
+      // error is a DirectiveError with source tracking
+      console.error(`[${error.source}] ${error.sourceId}: ${error.message}`);
+      console.error("Recoverable:", error.recoverable);
+      console.error("Context:", error.context);
+    },
+
+    // Configuration for retry-later strategy
+    retryLater: {
+      delayMs: 1000,       // Initial delay (default: 1000)
+      maxRetries: 3,        // Max retry attempts (default: 3)
+      backoffMultiplier: 2, // Multiply delay each retry (default: 2)
+      maxDelayMs: 30000,    // Cap on delay growth (default: 30000)
+    },
+  },
+});
+```
+
+## Dynamic Error Handling with Functions
+
+Use functions instead of strings for conditional recovery:
+
+```typescript
+errorBoundary: {
+  onResolverError: (error, resolverId) => {
+    // Network errors – retry later
+    if (error.message.includes("NetworkError")) {
+      return "retry-later";
+    }
+
+    // Auth errors – skip, don't retry
+    if (error.message.includes("401")) {
+      return "skip";
+    }
+
+    // Everything else – throw
+    return "throw";
+  },
+
+  onConstraintError: (error, constraintId) => {
+    // Disable constraints that repeatedly fail
+    if (constraintId === "experimentalFeature") {
+      return "disable";
+    }
+
+    return "skip";
+  },
+
+  onEffectError: (error, effectId) => {
+    // Analytics can fail silently
+    if (effectId.startsWith("analytics")) {
+      return "skip";
+    }
+
+    return "throw";
+  },
+},
+```
+
+## DirectiveError
+
+All errors passed to error boundary callbacks are `DirectiveError` instances with source tracking:
+
+```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" – the specific item that failed
+    err.recoverable; // boolean – whether recovery strategies apply
+    err.context;     // arbitrary debug data (e.g., the requirement object)
+    err.message;     // human-readable description
+  }
+}
+```
+
+## Resolver-Level Error Handling
+
+Resolvers have their own retry policy independent of the error boundary:
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+
+    // Resolver-level retry policy
+    retry: {
+      attempts: 3,
+      backoff: "exponential",
+      initialDelay: 200,
+      maxDelay: 5000,
+      shouldRetry: (error, attempt) => {
+        // Only retry server errors, not client errors
+        if (error.message.includes("4")) {
+          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();
+    },
+  },
+},
+```
+
+When both resolver retry and error boundary are configured, the resolver retries first. If all retries fail, the error boundary strategy is applied.
+
+## Lifecycle Hooks
+
+Module-level hooks for lifecycle events:
+
+```typescript
+const myModule = createModule("app", {
+  schema: { facts: { status: t.string() } },
+
+  hooks: {
+    onInit: (system) => {
+      console.log("Module initialized");
+    },
+    onStart: (system) => {
+      console.log("System started");
+    },
+    onStop: (system) => {
+      console.log("System stopped");
+    },
+    onError: (error, hookContext) => {
+      console.error("Module error:", error.message);
+      // error is a DirectiveError
+      // hookContext provides additional details
+    },
+  },
+
+  init: (facts) => {
+    facts.status = "ready";
+  },
+});
+```
+
+## Circuit Breaker
+
+For protecting against cascading failures from external services. The circuit breaker tracks failure rates and short-circuits requests when a threshold is exceeded.
+
+```typescript
+import { createCircuitBreaker } from "@directive-run/core/plugins";
+
+const apiBreaker = createCircuitBreaker({
+  name: "external-api",
+  failureThreshold: 5,       // Open after 5 failures (default: 5)
+  recoveryTimeMs: 30000,     // Wait 30s before trying again (default: 30000)
+  halfOpenMaxRequests: 3,    // Allow 3 trial requests in half-open (default: 3)
+  failureWindowMs: 60000,    // Count failures within 60s window (default: 60000)
+
+  // Optional: classify which errors count as failures
+  isFailure: (error) => {
+    // Don't count 404s as circuit-breaking failures
+    if (error.message.includes("404")) {
+      return false;
+    }
+
+    return true;
+  },
+
+  // Optional: react to state changes
+  onStateChange: (from, to) => {
+    console.log(`Circuit: ${from} -> ${to}`);
+  },
+});
+```
+
+### Using Circuit Breaker in Resolvers
+
+```typescript
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const data = await apiBreaker.execute(async () => {
+        const res = await fetch("/api/data");
+
+        return res.json();
+      });
+
+      context.facts.data = data;
+    },
+  },
+},
+```
+
+### Circuit Breaker + Constraints
+
+Wire the circuit breaker state into constraints for automatic fallback:
+
+```typescript
+constraints: {
+  apiDown: {
+    when: () => apiBreaker.getState() === "OPEN",
+    require: { type: "USE_FALLBACK" },
+  },
+
+  fetchNormally: {
+    when: (facts) => apiBreaker.getState() !== "OPEN" && !facts.data,
+    require: { type: "FETCH_DATA" },
+  },
+},
+```
+
+### Circuit Breaker States
+
+```
+CLOSED → Normal operation, all requests pass through
+  ↓ (failures >= threshold)
+OPEN → All requests rejected immediately
+  ↓ (after recoveryTimeMs)
+HALF_OPEN → Limited trial requests allowed
+  ↓ (trial succeeds) → CLOSED
+  ↓ (trial fails)    → OPEN
+```
+
+### Circuit Breaker API
+
+```typescript
+apiBreaker.getState();     // "CLOSED" | "OPEN" | "HALF_OPEN"
+apiBreaker.isAllowed();    // boolean – would a request be allowed?
+apiBreaker.getStats();     // { totalRequests, totalFailures, recentFailures, ... }
+apiBreaker.forceState("CLOSED"); // Force state (useful in tests)
+apiBreaker.reset();        // Reset to CLOSED with cleared stats
+```
+
+### CircuitBreakerOpenError
+
+When the circuit is open, `execute()` throws a `CircuitBreakerOpenError`:
+
+```typescript
+import { CircuitBreakerOpenError } from "@directive-run/core/plugins";
+
+try {
+  await apiBreaker.execute(() => fetch("/api"));
+} catch (error) {
+  if (error instanceof CircuitBreakerOpenError) {
+    error.code;          // "CIRCUIT_OPEN"
+    error.retryAfterMs;  // ms until circuit transitions to HALF_OPEN
+    error.state;         // "OPEN" | "HALF_OPEN"
+  }
+}
+```
+
+## Error Handling Checklist
+
+1. Set system-level `errorBoundary` with strategies for each subsystem
+2. Add `retry` policy on resolvers that call external services
+3. Use `shouldRetry` to avoid retrying permanent failures (4xx errors)
+4. Use circuit breaker for services with known reliability issues
+5. Wire circuit breaker state into constraints for automatic fallback
+6. Add `onError` callback for logging/monitoring
+7. Use `"throw"` for derivation errors (they indicate bugs)
+8. Use `"skip"` for non-critical effects (logging, analytics)
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — retry policies and cancellation; the most common error source
+- [`plugins.md`](./plugins.md) — `createCircuitBreaker` lives in `@directive-run/core/plugins`; pair it with error boundaries for cascading-failure isolation
+- [`anti-patterns.md`](./anti-patterns.md) — common error-handling mistakes (catching the wrong type, swallowing recoverable errors)