@directive-run/knowledge 0.2.0

package/core/multi-module.md

@@ -0,0 +1,315 @@
+# Multi-Module Systems
+
+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()],
+  debug: { timeTravel: 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 but dispatched through the events accessor:
+
+```typescript
+// Multi-module events
+system.events.auth.login({ token: "abc" });
+system.events.cart.addItem({ id: "item-1", qty: 1 });
+
+// dispatch() also works with type discriminator
+system.dispatch({ type: "login", token: "abc" });
+```

package/core/naming.md

@@ -0,0 +1,283 @@
+# Naming Conventions
+
+Directive naming rules that AI coding assistants must follow. These are non-negotiable project conventions.
+
+## Decision Tree: "What do I call this?"
+
+```
+Resolver parameter names?
+  → (req, context)     req = requirement, NEVER "request"
+  → NEVER (req, ctx)   context is NEVER abbreviated
+
+Computed values?
+  → "derivations" / derive   NEVER "computed", "selectors", "getters"
+  → system.derive.myValue    NEVER system.computed.myValue
+
+State values?
+  → "facts"                  NEVER "state", "store", "atoms"
+  → system.facts.count       NEVER system.state.count
+
+Conditional triggers?
+  → "constraints"            NEVER "rules", "conditions", "triggers"
+  → when() + require()       NEVER if/then, trigger/action
+
+Fulfillment logic?
+  → "resolvers"              NEVER "handlers", "actions", "reducers"
+  → resolve(req, context)    NEVER handle(req, ctx)
+```
+
+## 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"
+      // req.userId from the requirement payload
+      const user = await fetchUser(req.userId);
+      context.facts.user = user;
+    },
+  },
+},
+
+// WRONG — never use "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
+
+### Always Use Braces
+
+No single-line returns. Always wrap in braces.
+
+```typescript
+// WRONG
+derive: {
+  isReady: (facts) => facts.phase === "ready",
+},
+
+constraints: {
+  check: {
+    when: (facts) => facts.count > 10,
+    require: { type: "PROCESS" },
+  },
+},
+
+// Wait -- the above IS correct for one-line arrow expressions.
+// The brace rule applies to if/return blocks:
+
+// WRONG — single-line if return
+if (facts.user) return "ready";
+
+// CORRECT — always use 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;
+}
+
+// WRONG — no blank line before return after code
+function getStatus(facts) {
+  const phase = facts.phase;
+  return phase === "ready"; // Missing blank line
+}
+```
+
+## 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;
+},
+
+// WRONG
+events: { reset: (facts) => { facts.count = 0; facts.phase = "idle"; } },
+
+// CORRECT
+events: {
+  reset: (facts) => {
+    facts.count = 0;
+    facts.phase = "idle";
+  },
+},
+```
+
+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:
+
+```typescript
+// CORRECT — cast in schema definition
+schema: {
+  facts: {} as { profile: UserProfile; settings: AppSettings },
+  derivations: {} as { displayName: string },
+},
+
+// OR use t.* builders (preferred)
+schema: {
+  facts: {
+    profile: t.object<UserProfile>(),
+    settings: t.object<AppSettings>(),
+  },
+  derivations: {
+    displayName: t.string(),
+  },
+},
+```
+
+## Terminology Quick Reference
+
+| Directive Term | NEVER Use |
+|---|---|
+| facts | state, store, atoms, signals |
+| derivations / derive | computed, selectors, getters, memos |
+| constraints | rules, conditions, triggers, guards |
+| resolvers | handlers, actions, reducers, sagas |
+| requirements | requests, commands, intents |
+| effects | watchers, subscriptions, reactions |
+| module | slice, feature, domain |
+| system | store, container, context |
+| `req` (parameter) | request, r, requirement (spelled out) |
+| `context` (parameter) | ctx, c, resolverContext |