@directive-run/claude-plugin 1.16.0

package/skills/building-directive-systems/multi-module.md

@@ -0,0 +1,327 @@
+# Multi-Module Systems
+
+> Covers `@directive-run/core` — namespaced multi-module systems, cross-module deps, `facts.self.*`.
+
+How to compose multiple modules into a namespaced system with cross-module type safety.
+
+## Decision Tree: "Single or Multi-Module?"
+
+```
+How many state domains?
+├── One → createSystem({ module: myModule })
+│         Direct access: system.facts.count
+│
+└── Two or more → createSystem({ modules: { auth, cart, ui } })
+                   Namespaced: system.facts.auth.token
+
+Does module A need to read module B's state?
+├── No → No crossModuleDeps needed
+│
+└── Yes → Declare crossModuleDeps on the consuming module
+          Own facts at facts.self.*, other at facts.otherModule.*
+```
+
+## Creating a Multi-Module System
+
+```typescript
+import { createModule, createSystem, t } from "@directive-run/core";
+
+const authModule = createModule("auth", {
+  schema: {
+    facts: {
+      token: t.string<string | null>(),
+      isAuthenticated: t.boolean(),
+    },
+    events: {
+      login: { token: t.string() },
+      logout: {},
+    },
+  },
+  init: (facts) => {
+    facts.token = null;
+    facts.isAuthenticated = false;
+  },
+  events: {
+    login: (facts, payload) => {
+      facts.token = payload.token;
+      facts.isAuthenticated = true;
+    },
+    logout: (facts) => {
+      facts.token = null;
+      facts.isAuthenticated = false;
+    },
+  },
+});
+
+const cartModule = createModule("cart", {
+  schema: {
+    facts: {
+      items: t.array(t.object<{ id: string; qty: number }>()),
+    },
+    derivations: {
+      itemCount: t.number(),
+    },
+  },
+  init: (facts) => {
+    facts.items = [];
+  },
+  derive: {
+    itemCount: (facts) => facts.items.length,
+  },
+});
+
+// Multi-module system – namespaced access
+const system = createSystem({
+  modules: { auth: authModule, cart: cartModule },
+});
+
+system.start();
+```
+
+## Accessing Namespaced State
+
+```typescript
+// Facts – namespaced under module name
+system.facts.auth.token;
+system.facts.auth.isAuthenticated;
+system.facts.cart.items;
+
+// Derivations – namespaced under module name
+system.derive.cart.itemCount;
+
+// Events – namespaced under module name
+system.events.auth.login({ token: "abc123" });
+system.events.auth.logout();
+
+// Subscribe – use "namespace.key" format
+system.subscribe(["auth.token", "cart.items"], () => {
+  console.log("auth or cart changed");
+});
+
+// Watch – use "namespace.key" format
+system.watch("auth.isAuthenticated", (newVal, oldVal) => {
+  console.log(`Auth: ${oldVal} -> ${newVal}`);
+});
+
+// Subscribe to all keys in a module
+system.subscribeModule("cart", () => {
+  console.log("anything in cart changed");
+});
+
+// Wait for condition – facts are namespaced
+await system.when((facts) => facts.auth.isAuthenticated);
+```
+
+## Cross-Module Dependencies
+
+When a module needs to read another module's facts in its constraints, effects, or derivations, declare `crossModuleDeps`.
+
+### Extracting the Schema
+
+Export the schema separately from the module so other modules can reference it:
+
+```typescript
+// modules/auth.ts
+export const authSchema = {
+  facts: {
+    token: t.string<string | null>(),
+    isAuthenticated: t.boolean(),
+  },
+  events: {
+    login: { token: t.string() },
+    logout: {},
+  },
+} as const;
+
+export const authModule = createModule("auth", {
+  schema: authSchema,
+  init: (facts) => {
+    facts.token = null;
+    facts.isAuthenticated = false;
+  },
+  // ...
+});
+```
+
+### Declaring crossModuleDeps
+
+```typescript
+// modules/data.ts
+import { authSchema } from "./auth";
+
+const dataModule = createModule("data", {
+  schema: {
+    facts: {
+      items: t.array(t.string()),
+      loaded: t.boolean(),
+    },
+    requirements: {
+      FETCH_ITEMS: {},
+    },
+  },
+
+  // Declare cross-module dependency
+  crossModuleDeps: { auth: authSchema },
+
+  init: (facts) => {
+    facts.items = [];
+    facts.loaded = false;
+  },
+
+  // CORRECT – facts.self for own module, facts.auth for cross-module
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated && !facts.self.loaded,
+      require: { type: "FETCH_ITEMS" },
+    },
+  },
+
+  resolvers: {
+    fetchItems: {
+      requirement: "FETCH_ITEMS",
+      resolve: async (req, context) => {
+        const res = await fetch("/api/items");
+        context.facts.items = await res.json();
+        context.facts.loaded = true;
+      },
+    },
+  },
+
+  // Effects also get cross-module facts
+  effects: {
+    onAuthChange: {
+      run: (facts, prev) => {
+        if (prev && prev.auth.isAuthenticated && !facts.auth.isAuthenticated) {
+          console.log("User logged out, clearing data");
+        }
+      },
+    },
+  },
+});
+```
+
+## Common Mistakes
+
+### Using bare `facts.*` instead of `facts.self.*`
+
+```typescript
+// WRONG – in cross-module context, bare facts has no self-module properties
+constraints: {
+  check: {
+    when: (facts) => facts.loaded, // TypeScript error
+    require: { type: "FETCH" },
+  },
+},
+
+// CORRECT – use facts.self for own module
+constraints: {
+  check: {
+    when: (facts) => facts.self.loaded,
+    require: { type: "FETCH" },
+  },
+},
+```
+
+### Bracket notation for internal keys
+
+```typescript
+// WRONG – the :: separator is internal, never use it directly
+system.facts["auth::token"];
+system.read("auth::status");
+
+// CORRECT – dot notation through namespace proxy
+system.facts.auth.token;
+system.read("auth.status");
+```
+
+### Forgetting crossModuleDeps
+
+```typescript
+// WRONG – facts.auth is untyped without crossModuleDeps
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  constraints: {
+    check: {
+      when: (facts) => facts.auth.isAuthenticated, // No type info
+      require: { type: "FETCH" },
+    },
+  },
+});
+
+// CORRECT – declare the dependency
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  crossModuleDeps: { auth: authSchema },
+  constraints: {
+    check: {
+      when: (facts) => facts.auth.isAuthenticated, // Fully typed
+      require: { type: "FETCH" },
+    },
+  },
+});
+```
+
+## System Configuration Options
+
+```typescript
+const system = createSystem({
+  modules: { auth: authModule, cart: cartModule, data: dataModule },
+
+  // Initial facts – applied after init(), before first reconciliation
+  initialFacts: {
+    auth: { token: "restored-token" },
+    cart: { items: cachedItems },
+  },
+
+  // Init order – control module initialization sequence
+  initOrder: "auto",            // Sort by crossModuleDeps topology (default)
+  // initOrder: "declaration",   // Use object key order
+  // initOrder: ["auth", "data", "cart"], // Explicit order
+
+  plugins: [loggingPlugin()],
+  history: true,
+});
+
+// Hydrate from async source (call before start)
+await system.hydrate(async () => {
+  const stored = localStorage.getItem("app-state");
+
+  return stored ? JSON.parse(stored) : {};
+});
+
+system.start();
+await system.settle();
+```
+
+## Dynamic Module Registration
+
+```typescript
+// Lazy-load and register a module at runtime
+const chatModule = await import("./modules/chat");
+system.registerModule("chat", chatModule.default);
+
+// Now accessible at system.facts.chat.*, system.events.chat.*, etc.
+```
+
+## Cross-Module Events
+
+Events are namespaced at the system level. **Prefer the typed events accessor** — it carries autocomplete and per-event payload typing.
+
+```typescript
+// Multi-module events — canonical form
+system.events.auth.login({ token: "abc" });
+system.events.cart.addItem({ id: "item-1", qty: 1 });
+
+// dispatch() is supported when you need to forward a programmatically-built
+// event (e.g., replaying a serialized event). The string form
+// (system.dispatch("login", payload)) does NOT exist — only the single-arg
+// object form is valid.
+system.dispatch({ type: "login", token: "abc" });
+```
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — start here for the single-module shape before going namespaced
+- [`system-api.md`](./system-api.md) — `createSystem({ modules: { ... } })` and the namespaced facts proxy
+- [`constraints.md`](./constraints.md) — `crossModuleDeps` for constraints that fire on facts owned by another module
+- [`naming.md`](./naming.md) — `facts.self.*` convention; dot-notation vs bracket-notation rules

package/skills/building-directive-systems/plugins.md

@@ -0,0 +1,361 @@
+# Plugins
+
+> Covers `@directive-run/core/plugins` — plugin authoring + built-ins (logging, devtools, persistence, audit-ledger, observability, OTLP).
+
+Plugins extend Directive systems with cross-cutting functionality like logging, persistence, devtools, and resilience patterns.
+
+## Decision Tree: "Which plugin do I need?"
+
+```
+What do you want?
+├── See state changes in console → loggingPlugin()
+├── Connect to browser DevTools → devtoolsPlugin()
+├── Persist state across reloads → persistencePlugin(config)
+├── Protect resolvers from cascading failures → createCircuitBreaker(config)
+├── Track metrics, traces, alerts → createObservability(config)
+└── Custom cross-cutting behavior → Write a custom plugin
+```
+
+## Using Built-In Plugins
+
+```typescript
+import { createSystem } from "@directive-run/core";
+import {
+  devtoolsPlugin,
+  loggingPlugin,
+  persistencePlugin,
+} from "@directive-run/core/plugins";
+
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    devtoolsPlugin(),
+    loggingPlugin({ level: "debug" }),
+    persistencePlugin({
+      key: "my-app-state",
+      storage: localStorage,
+    }),
+  ],
+});
+```
+
+Plugins are applied in order. Place logging first to capture all events including those from other plugins.
+
+## loggingPlugin
+
+Logs state changes, requirements, and resolutions to the console.
+
+```typescript
+import { loggingPlugin } from "@directive-run/core/plugins";
+
+// Default – logs facts changes and resolver start/complete at "info" level
+loggingPlugin()
+
+// Debug level – logs everything including derivation recomputation and constraint evaluation
+loggingPlugin({ level: "debug" })
+
+// Custom filter – only log specific events
+loggingPlugin({
+  filter: (event) => event.startsWith("resolver."),
+})
+
+// Custom logger and prefix
+loggingPlugin({
+  level: "warn",
+  prefix: "[MyApp]",
+  logger: customLogger,
+})
+```
+
+Options: `level` ("debug" | "info" | "warn" | "error"), `filter` (predicate on event name string), `logger` (Console-compatible object), `prefix` (string, default "[Directive]").
+
+## devtoolsPlugin
+
+Connects to the Directive DevTools browser extension for visual state inspection.
+
+```typescript
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// Default
+devtoolsPlugin()
+
+// With options
+devtoolsPlugin({
+  name: "My App",        // Name shown in DevTools
+  maxEvents: 1000,       // Max trace events to retain (default: 1000)
+  trace: true,           // Enable trace logging
+  panel: true,           // Show floating debug panel (dev mode only)
+})
+```
+
+Only enable in development. The plugin is a no-op if the DevTools extension is not installed.
+
+## persistencePlugin
+
+Persists fact state to storage. Restores on system creation.
+
+```typescript
+import { persistencePlugin } from "@directive-run/core/plugins";
+
+// localStorage (default)
+persistencePlugin({
+  key: "my-app-state",
+  storage: localStorage,
+})
+
+// sessionStorage – cleared when tab closes
+persistencePlugin({
+  key: "session-state",
+  storage: sessionStorage,
+})
+
+// Custom storage adapter
+persistencePlugin({
+  key: "my-app",
+  storage: {
+    getItem: (key) => myCustomStore.get(key),
+    setItem: (key, value) => myCustomStore.set(key, value),
+    removeItem: (key) => myCustomStore.delete(key),
+  },
+})
+
+// Selective persistence – only persist certain facts
+persistencePlugin({
+  key: "my-app",
+  storage: localStorage,
+  include: ["user", "preferences"],  // Only these facts
+  // OR
+  exclude: ["tempData", "sessionId"], // Everything except these
+})
+
+// With callbacks
+persistencePlugin({
+  key: "my-app",
+  storage: localStorage,
+  debounce: 200,                       // Debounce saves (default: 100ms)
+  onRestore: (data) => console.log("Restored:", data),
+  onSave: (data) => console.log("Saved:", data),
+  onError: (err) => console.error("Persistence error:", err),
+})
+```
+
+## createCircuitBreaker
+
+Standalone utility (not a Plugin) that implements the circuit breaker pattern for resilience. Use it inside resolvers to protect against cascading failures from external services.
+
+```typescript
+import { createCircuitBreaker } from "@directive-run/core/plugins";
+
+const breaker = createCircuitBreaker({
+  failureThreshold: 5,         // Failures before opening (default: 5)
+  recoveryTimeMs: 30000,       // Time before HALF_OPEN (default: 30000)
+  halfOpenMaxRequests: 3,      // Requests allowed in HALF_OPEN (default: 3)
+  failureWindowMs: 60000,      // Window for counting failures (default: 60000)
+  name: "api-breaker",         // Name for metrics/errors
+  onStateChange: (from, to) => console.log(`Circuit: ${from} -> ${to}`),
+});
+
+// Use inside a resolver
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const result = await breaker.execute(async () => {
+        return await callExternalAPI();
+      });
+      context.facts.data = result;
+    },
+  },
+},
+
+// Wire circuit state into constraints
+constraints: {
+  apiDown: {
+    when: () => breaker.getState() === "OPEN",
+    require: { type: "FALLBACK_RESPONSE" },
+  },
+},
+```
+
+Circuit breaker states: **Closed** (normal) -> **Open** (failing, rejects immediately) -> **Half-Open** (testing limited requests).
+
+## createObservability
+
+Metrics, tracing, and alerting for production systems.
+
+```typescript
+import { createObservability } from "@directive-run/core/plugins";
+
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    createObservability({
+      metrics: {
+        enabled: true,
+        // Track resolver duration, constraint evaluation count, etc.
+      },
+      tracing: {
+        enabled: true,
+        // Trace resolver execution with spans
+      },
+      alerts: {
+        enabled: true,
+        onAlert: (alert) => {
+          // Send to monitoring service
+          sendToDatadog(alert);
+        },
+      },
+    }),
+  ],
+});
+```
+
+## Plugin Lifecycle Hooks
+
+Plugins hook into the system lifecycle. Use these to build custom plugins.
+
+```typescript
+import type { Plugin, ModuleSchema } from "@directive-run/core";
+
+const myPlugin: Plugin<ModuleSchema> = {
+  name: "my-custom-plugin",
+
+  // System lifecycle
+  onInit: (system) => {
+    // Called when system is created (only async hook)
+  },
+  onStart: (system) => {
+    // Called when system.start() is invoked
+  },
+  onStop: (system) => {
+    // Called when system.stop() is invoked
+  },
+  onDestroy: (system) => {
+    // Called when system.destroy() is invoked
+  },
+
+  // Fact tracking
+  onFactSet: (key, value, prev) => {
+    // Called when a single fact is set
+  },
+  onFactsBatch: (changes) => {
+    // Called after a batch of fact changes completes
+  },
+
+  // Requirement pipeline
+  onRequirementCreated: (requirement) => {
+    // Called when a constraint emits a requirement
+    // requirement.type, requirement.id
+  },
+  onRequirementMet: (requirement, byResolver) => {
+    // Called when a requirement is fulfilled
+  },
+
+  // Resolver pipeline
+  onResolverStart: (resolverId, requirement) => {
+    // Called when a resolver begins executing
+  },
+  onResolverComplete: (resolverId, requirement, duration) => {
+    // Called when a resolver finishes successfully
+  },
+  onResolverError: (resolverId, requirement, error) => {
+    // Called when a resolver fails (after all retries)
+  },
+
+  // Error handling
+  onError: (error) => {
+    // Called on any DirectiveError in the system
+    // error.source, error.message, error.context
+  },
+};
+
+const system = createSystem({
+  module: myModule,
+  plugins: [myPlugin],
+});
+```
+
+## Common Mistakes
+
+### Enabling devtools in production
+
+```typescript
+// WRONG – devtools overhead in production
+const system = createSystem({
+  module: myModule,
+  plugins: [devtoolsPlugin()],
+});
+
+// CORRECT – conditional on environment
+const plugins = [];
+if (process.env.NODE_ENV === "development") {
+  plugins.push(devtoolsPlugin());
+  plugins.push(loggingPlugin({ level: "debug" }));
+}
+
+const system = createSystem({
+  module: myModule,
+  plugins,
+});
+```
+
+### Persistence without filtering
+
+```typescript
+// WRONG – persists everything including transient state
+persistencePlugin({
+  key: "app-state",
+  storage: localStorage,
+})
+
+// CORRECT – use include/exclude to control what's persisted
+persistencePlugin({
+  key: "app-state",
+  storage: localStorage,
+  include: ["user", "preferences", "settings"],
+})
+```
+
+### Plugin order matters
+
+```typescript
+// WRONG – logging misses events from persistence restore
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    persistencePlugin({ key: "app", storage: localStorage }),
+    loggingPlugin(), // Misses restore events
+  ],
+});
+
+// CORRECT – logging first to capture everything
+const system = createSystem({
+  module: myModule,
+  plugins: [
+    loggingPlugin(),
+    persistencePlugin({ key: "app", storage: localStorage }),
+  ],
+});
+```
+
+### Persisting sensitive or transient data
+
+```typescript
+// WRONG – persists auth tokens and loading state
+persistencePlugin({
+  key: "app",
+  storage: localStorage,
+})
+
+// CORRECT – exclude sensitive and transient facts
+persistencePlugin({
+  key: "app",
+  storage: localStorage,
+  exclude: ["authToken", "isLoading", "error"],
+})
+```
+
+## See also
+
+- [`system-api.md`](./system-api.md) — `plugins:` option on `createSystem` and the lifecycle hooks plugins observe
+- [`error-boundaries.md`](./error-boundaries.md) — `createCircuitBreaker` and the resilience plugins that pair with error boundaries