@directive-run/claude-plugin 1.16.0

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

@@ -0,0 +1,321 @@
+# Naming Conventions
+
+> Covers all `@directive-run/*` packages — terminology, parameter names, return-style rules.
+
+Directive uses precise vocabulary by design: each concept has one canonical name across every package, every language adapter, and every doc. The names are non-negotiable for code Directive ships, AND every term has a cross-paradigm alias so a developer coming from Redux / Zustand / XState / Jotai / React Query can find the right Directive concept on the first search.
+
+This file is both the rules and the bridge. Search for the term you already know; you'll land on the Directive equivalent.
+
+## Coming from another library? Start here
+
+| If you call it… | (in this library) | Directive calls it… | Why the name |
+|---|---|---|---|
+| **state**, **store**, **atom**, **signal**, **observable** | Redux, Zustand, Jotai, Preact Signals, MobX | **facts** | "Facts about the world" — the system observes them. Same value-bag role as state, with a proxy that auto-tracks reads. |
+| **selector**, **computed**, **getter**, **memo**, **derived store** | Redux, Vue/MobX, Zustand getters, Memoize, Svelte | **derivations** / `derive` | Auto-tracked computed values. No dep arrays. Directive's name aligns with "derived from facts." |
+| **action**, **dispatch**, **reducer**, **command**, **intent** | Redux, Redux Toolkit, CQRS | **events** + **resolvers** | Events are the user-facing trigger; resolvers fulfill them. Reducers are split into the two halves Directive cares about. |
+| **thunk**, **saga**, **effect**, **middleware**, **listener** | Redux Toolkit, redux-saga, redux-observable, NgRx | **resolvers** | Async logic that mutates state in response to a requirement. Same role as a thunk; declared once, run by the runtime. |
+| **rule**, **condition**, **guard**, **trigger**, **policy** | XState guards, Cerbos, OPA, business-rule engines | **constraints** | Declarative "when X is true, Y must happen." Constraints emit requirements; resolvers fulfill them. |
+| **request**, **query**, **side-effect spec** | React Query / TanStack Query queries, Apollo queries | **requirements** | The object a constraint emits. The runtime dedupes them, dispatches to resolvers, tracks status. |
+| **subscription**, **listener**, **reaction**, **watcher** | Zustand subscribe, MobX reactions, Redux subscriptions | **effects** | Side-effects that run when watched facts change. Cleaner than `subscribe()` callbacks because effects auto-track. |
+| **slice**, **feature**, **domain**, **bounded context** | Redux Toolkit slices, NgRx feature modules | **modules** | Encapsulates facts + derivations + constraints + resolvers + events for one bounded slice of the system. |
+| **store**, **container**, **context**, **app state** | Redux Store, Pinia, React Context, NgRx Store | **system** | The runtime that wires modules together, evaluates constraints, dispatches resolvers, and exposes observation. |
+| **state machine**, **statechart**, **xstate machine** | XState | (closest: **module** + **constraints**) | Directive isn't a state machine — but if your XState `states` model business rules (not UI flow), constraints + facts express the same logic declaratively with no transition functions. |
+| **cache**, **query cache**, **stale-while-revalidate** | TanStack Query, SWR, Apollo cache | (closest: `@directive-run/query` + **constraints**) | Use `@directive-run/query` for the cache; constraints decide when refetches fire. Directive doesn't replace TanStack Query — it composes with it. |
+| **agent**, **chain**, **graph**, **workflow** | LangChain, LangGraph, OpenAI Assistants | **agent** + **orchestrator** | `@directive-run/ai` keeps the names — agents are agents, orchestrators are orchestrators — but they run under the same constraint engine as the rest of Directive. |
+| **guardrail**, **filter**, **safety check**, **moderation** | OpenAI moderation API, NVIDIA NeMo Guardrails | **guardrails** | Same name, same role; declarative input/output/tool-call checks. |
+
+If your term isn't in the table, search the canonical name in this doc's [Terminology quick reference](#terminology-quick-reference) — both directions are listed.
+
+## Canonical terms (non-negotiable for code Directive ships)
+
+Above is the bridge from your existing vocabulary. Below are the canonical names — the only ones that should appear in `@directive-run/*` source, tests, docs, and generated AI rules.
+
+### `facts` — the value bag
+
+Not state, not store, not atoms. **Facts.** Accessed at `system.facts.x`. Mutated through events and resolvers. Read through derivations, hooks, and `system.facts.$store`.
+
+### `derivations` — auto-tracked computed values
+
+Declared via `derive: { name: (facts) => … }`. Read at `system.derive.name`. The hook is `useDerived` (not `useComputed`, not `useSelector` — Directive's `useSelector` is a different, broader primitive that takes a selector function).
+
+### `constraints` — when-then declarations
+
+Declared via `constraints: { name: { when: …, require: … } }`. The `when` returns a boolean; the `require` returns a requirement.
+
+### `resolvers` — requirement fulfillment
+
+Declared via `resolvers: { name: { requirement: …, resolve: async (req, context) => … } }`. Mutate `context.facts`; never return data from `resolve`.
+
+### `requirements` — what constraints emit
+
+Tagged union `{ type: "FETCH_USER", … }`. Constraints emit them; the runtime dedupes by `type` + `key()`; resolvers fulfill them.
+
+### `effects` — side effects from watched changes
+
+Declared via `effects: { name: { run: (facts, prev) => … } }`. Run on relevant fact changes. The auto-tracking dependency model means no `deps` array unless you specifically need a partial dep set.
+
+### `events` — typed mutation entry points
+
+Declared via `events: { name: (facts, payload) => … }`. Called as `system.events.name(payload)`. The typed events accessor is the canonical way to dispatch — `system.dispatch({type, ...payload})` works but the typed accessor carries autocomplete.
+
+### `module` — bounded slice
+
+Created via `createModule(name, { schema, init, derive, effects, events, constraints, resolvers })`. Composes into systems.
+
+### `system` — the runtime
+
+Created via `createSystem({ module })` or `createSystem({ modules: { x, y } })`. Hosts the reconciliation loop.
+
+## Parameter naming
+
+### `req` = requirement (NOT request)
+
+The `req` parameter in resolvers and constraint `key()` functions is short for **requirement** — the object emitted by a constraint's `require` property.
+
+```typescript
+// CORRECT — req is a requirement
+resolvers: {
+  fetchUser: {
+    requirement: "FETCH_USER",
+    key: (req) => `fetch-${req.userId}`,
+    resolve: async (req, context) => {
+      // req.type === "FETCH_USER"
+      const user = await fetchUser(req.userId);
+      context.facts.user = user;
+    },
+  },
+},
+
+// WRONG — never "request" or "r"
+resolve: async (request, context) => { /* ... */ },
+resolve: async (r, context) => { /* ... */ },
+```
+
+### `context` is never abbreviated
+
+```typescript
+// CORRECT
+resolve: async (req, context) => {
+  context.facts.status = "loaded";
+  context.signal;       // AbortSignal
+  context.snapshot();   // facts snapshot
+},
+
+// WRONG — never abbreviate to ctx
+resolve: async (req, ctx) => { /* ... */ },
+```
+
+## Return style
+
+### Braces for `if` blocks with `return` (NOT for arrow expressions)
+
+The brace rule applies to control-flow blocks — not to arrow-expression bodies.
+
+**Arrow expressions** (single-line derivations, predicates, computed requirements): the concise form is preferred. No braces, no explicit `return`.
+
+```typescript
+// CORRECT — single-line arrow expressions stay concise
+derive: {
+  isReady: (facts) => facts.phase === "ready",
+  greeting: (facts) => `Hi, ${facts.name}!`,
+},
+
+constraints: {
+  check: {
+    when: (facts) => facts.count > 10,
+    require: { type: "PROCESS" },
+  },
+},
+```
+
+**Control-flow statements** (`if`, `for`, `while`): braces required, even for single-line bodies. Single-line `if (x) return y` shapes are never used.
+
+```typescript
+// WRONG — single-line if return
+if (facts.user) return "ready";
+
+// CORRECT — always wrap the body in braces
+if (facts.user) {
+  return "ready";
+}
+```
+
+### Blank line before `return`
+
+Add a blank line before `return` when there is code above it. Skip the blank line when `return` is the first statement in a block.
+
+```typescript
+// CORRECT — blank line before return when code precedes it
+function getStatus(facts) {
+  const phase = facts.phase;
+  const hasUser = facts.user !== null;
+
+  return phase === "ready" && hasUser;
+}
+
+// CORRECT — no blank line when return is first statement
+function isReady(facts) {
+  return facts.phase === "ready";
+}
+
+// CORRECT — blank line after brace-style return block
+function process(facts) {
+  if (!facts.ready) {
+    return null;
+  }
+
+  const result = computeResult(facts);
+
+  return result;
+}
+```
+
+## Multi-line code formatting
+
+Never put properties or statements on a single line inside braces. Always expand to one item per line with proper indentation. This applies everywhere: schema definitions, init functions, events, effects, requirement types, and any other object or block.
+
+```typescript
+// WRONG — properties crammed on one line
+schema: {
+  facts: { phase: t.string(), count: t.number() },
+  requirements: { FETCH_USER: { id: t.string() }, RESET: {} },
+},
+
+// CORRECT — one property per line, always expanded
+schema: {
+  facts: {
+    phase: t.string(),
+    count: t.number(),
+  },
+  requirements: {
+    FETCH_USER: {
+      id: t.string(),
+    },
+    RESET: {},
+  },
+},
+
+// WRONG — statements crammed on one line
+init: (facts) => { facts.phase = "idle"; facts.count = 0; },
+
+// CORRECT — one statement per line
+init: (facts) => {
+  facts.phase = "idle";
+  facts.count = 0;
+},
+```
+
+Single-expression arrows (no braces) are fine on one line. Empty objects `{}` are fine inline.
+
+```typescript
+// OK — single expression, no braces
+derive: {
+  isReady: (facts) => facts.phase === "ready",
+},
+
+// OK — empty object
+RESET: {},
+```
+
+## Multi-module naming
+
+### `facts.self.*` for own module
+
+In multi-module systems, constraints, effects, and derivations with `crossModuleDeps` receive namespaced facts. Own module facts are always at `facts.self.*`.
+
+```typescript
+// CORRECT
+constraints: {
+  loadWhenAuth: {
+    when: (facts) => facts.auth.isAuthenticated && !facts.self.loaded,
+    require: { type: "LOAD_DATA" },
+  },
+},
+
+// WRONG — bare facts.* in multi-module context
+constraints: {
+  loadWhenAuth: {
+    when: (facts) => facts.isAuthenticated && !facts.loaded,
+    require: { type: "LOAD_DATA" },
+  },
+},
+```
+
+### System-level access uses dot notation
+
+```typescript
+// CORRECT — dot notation through namespace proxy
+system.facts.auth.token;
+system.facts.cart.items;
+system.derive.auth.isLoggedIn;
+system.events.auth.login({ token: "..." });
+
+// WRONG — bracket notation with internal separator
+system.facts["auth::token"];
+system.facts["auth_token"];
+```
+
+## Type casting rules
+
+### Never cast when reading
+
+The schema provides all types. Do not add `as` casts when reading facts or derivations from the system.
+
+```typescript
+// CORRECT — schema provides the type
+const profile = system.facts.profile;
+const isReady = system.derive.isReady;
+
+// WRONG — unnecessary cast
+const profile = system.facts.profile as UserProfile;
+const isReady = system.derive.isReady as boolean;
+```
+
+### Cast only in schema definition
+
+Type assertions are only valid in schema definition using the `{} as {}` pattern, or via the `t.*` builders (preferred):
+
+```typescript
+// CORRECT — cast in schema definition
+schema: {
+  facts: {} as { profile: UserProfile; settings: AppSettings },
+  derivations: {} as { displayName: string },
+},
+
+// PREFERRED — t.* builders
+schema: {
+  facts: {
+    profile: t.object<UserProfile>(),
+    settings: t.object<AppSettings>(),
+  },
+  derivations: {
+    displayName: t.string(),
+  },
+},
+```
+
+## Terminology quick reference
+
+Two-way lookup. Search the term you know.
+
+| Directive term | Cross-paradigm aliases (use these to search) |
+|---|---|
+| **facts** | state, store, atoms, signals, observables, model |
+| **derivations** / `derive` | computed, selectors, getters, memos, derived stores, $: blocks (Svelte) |
+| **constraints** | rules, conditions, triggers, guards, policies, invariants |
+| **resolvers** | handlers, actions, reducers, sagas, thunks, effects (Redux), middleware, listeners |
+| **requirements** | requests, commands, intents, queries (TanStack), tasks |
+| **effects** | watchers, subscriptions, reactions, autoruns, listeners |
+| **events** | actions, intents, commands, methods (Pinia), signals (NgRx) |
+| **module** | slice, feature, domain, bounded context, NgRx feature module |
+| **system** | store, container, context, app state, app shell |
+| **`req`** (parameter) | request, r, requirement (spelled out) |
+| **`context`** (parameter) | ctx, c, resolverContext |
+
+The forbidden direction is also non-negotiable: in code Directive ships, the columns reverse. Do NOT use `state`, `store`, `selectors`, `computed`, `actions`, `reducers`, `subscriptions`, `slices`, `request`, or `ctx` in `@directive-run/*` source. The alias map is for retrieval — the canonical names are for code.
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — the actual code shapes every naming rule here applies to
+- [`multi-module.md`](./multi-module.md) — `facts.self.*` convention and dot-notation rules
+- [`anti-patterns.md`](./anti-patterns.md) — naming-shaped mistakes (`request` for `req`, `ctx` for `context`, hallucinated TS schema types)

package/skills/writing-directive-modules/schema-types.md

@@ -0,0 +1,273 @@
+# Schema Types
+
+> Covers `@directive-run/core` — schema builders (`t.string` / `t.number` / `t.array` / etc.) and inference helpers.
+
+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>()
+└── Any type + metadata → t.string().meta({ label: "Email", tags: ["pii"] })
+```
+
+All builders support `.meta({ label, description, category, color, tags })` for devtools/AI annotations. Chains with other methods: `t.string().meta({...}).nullable()`.
+
+## 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.
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — where the schemas these builders define get attached (modules)
+- [`system-api.md`](./system-api.md) — schema flows through `createSystem` and shows up on `system.facts.*`
+- [`anti-patterns.md`](./anti-patterns.md) — hallucinated schema types (`t.map`, `t.set`, `t.date`, `t.promise`, `t.tuple`, `t.record`, `t.any`) that don't exist