@directive-run/claude-plugin 1.17.1 → 1.18.0

package/skills/migrating-to-directive/anti-patterns.md

@@ -2,7 +2,7 @@
 
 > Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
 
-19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+21 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
 
 ## 1. Unnecessary Type Casting on Facts/Derivations
 
@@ -357,6 +357,97 @@ const system = createSystem({
 });
 ```
 
+## 20. Hand-Rolled External Subscriptions Inside React/`useEffect`
+
+When wrapping an external event stream (Supabase realtime, WebSocket, polling timer, browser listener) into a Directive system, do NOT write a React `useEffect` that owns the subscription and dispatches `sys.events.X()` from the callback — declare a `source` on the module instead. The runtime owns the mount / unmount lifecycle and observability. The component collapses to fact reads.
+
+```typescript
+// WRONG – subscription lives in component code; module never knows about it.
+// On every remount you get duplicate channels; on unmount you can leak.
+function Game({ system, gameId }: Props) {
+  useEffect(() => {
+    const ch = supabase
+      .channel(`game:${gameId}`)
+      .on('postgres_changes', { event: 'UPDATE', table: 'games' }, (payload) => {
+        system.events.realtimeUpdate({ snapshot: mapRow(payload.new) });
+      })
+      .subscribe();
+    return () => { supabase.removeChannel(ch); };
+  }, [gameId]);
+  return <Board snapshot={useFact(system, 'snapshot')} />;
+}
+
+// CORRECT – declare a `source` on the module. The runtime owns the
+// mount / unmount lifecycle and observability. The component collapses
+// to fact reads.
+const gameModule = createModule('game', {
+  schema: {
+    facts: { snapshot: t.object<GameSnapshot>().nullable() },
+    events: { realtimeUpdate: { snapshot: t.object<GameSnapshot>() } },
+  },
+  sources: {
+    realtime: {
+      attach: (publish) => {
+        const ch = supabase
+          .channel(`game:${gameId}`)
+          .on('postgres_changes', { event: 'UPDATE', table: 'games' },
+            (p) => publish('realtimeUpdate', { snapshot: mapRow(p.new) }))
+          .subscribe();
+        return () => { supabase.removeChannel(ch); };
+      },
+    },
+  },
+  on: { realtimeUpdate: (f, p) => { f.snapshot = p.snapshot; } },
+});
+```
+
+**Why:** the hook-as-bridge pattern duplicates lifecycle code at every call site. Cleanup correctness drifts. `system.observe()` can't see the subscription. With a `source`, the engine attaches at `start()`, detaches at `stop()`, isolates failures, and emits `source.attach` / `.publish` / `.detach` / `.error` observation events for plugins.
+
+**Don't subscribe in both an effect AND a source on the same channel** — the effect re-runs on fact changes, the source mounts once, you'll get 2× messages with silent duplicates. Pick one.
+
+See [`sources.md`](./sources.md) for the full decision tree, recipes (Supabase / WebSocket / browser events / polling), and the typed-publish factory pattern.
+
+## 21. Abbreviating Type Names (`*Def` instead of `*Definition`)
+
+```typescript
+// WRONG – `Def` is short for `Definition`. Same anti-pattern as `ctx`
+// → `context` (entry #5). Source code reads better with spelled-out
+// names; the minifier handles the bytes either way.
+import type { ModuleDef, SourceDef, ResolverDef } from "@directive-run/core";
+
+// CORRECT – use the spelled-out aliases. `*Def` stays canonical in 1.x
+// for back-compat; consumers can migrate today.
+import type {
+  ModuleDefinition,
+  SourceDefinition,
+  ResolverDefinition,
+} from "@directive-run/core";
+```
+
+The `*Definition` aliases ship in 1.x via `export type { X as XDefinition }`
+in `packages/core/src/core/types/index.ts`, so generic forwarding +
+TS inference rules (mapped types, conditional distribution, tagged-
+union discrimination, barrel re-exports) match the canonical `*Def`
+form bit-for-bit. **2.0 swaps:** `*Definition` becomes canonical and
+`*Def` becomes the deprecated alias. Start writing `*Definition` in
+new code today so the 2.0 migration is a no-op.
+
+Per RFC 0006, this applies to:
+
+- `ModuleDef` → `ModuleDefinition`
+- `ConstraintDef` / `ConstraintsDef` → `ConstraintDefinition` / `ConstraintsDefinition`
+- `ResolverDef` / `ResolversDef` → `ResolverDefinition` / `ResolversDefinition`
+- `DerivationDef` / `DerivationsDef` → `DerivationDefinition` / `DerivationsDefinition`
+- `EffectDef` / `EffectsDef` → `EffectDefinition` / `EffectsDefinition`
+- `EventsDef` → `EventsDefinition`
+- `SourceDef` / `SourcesDef` → `SourceDefinition` / `SourcesDefinition`
+- `SourcePublish` → `SourcePublishFn`, `SourceUnsubscribe` → `SourceUnsubscribeFn`
+- Plus all `Typed*Def`, `CrossModule*Def`, `Dynamic*Def` variants.
+
+`EffectCleanup`, `MetaAccessor`, `EventsAccessor`, `DeriveAccessor`,
+`Snapshot` are explicitly kept as-is (each has reasoning recorded in
+RFC 0006).
+
 ## Quick Reference Checklist
 
 Before generating any Directive code, verify:
@@ -371,10 +462,12 @@ Before generating any Directive code, verify:
 8. Multi-module uses `facts.self.*` for own facts
 9. Imports from `@directive-run/core`, not deep paths
 10. `await system.settle()` after `system.start()`
+11. External event subscriptions live in `sources:`, not in `useEffect` or `onMount`
 
 ## See also
 
 - [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`sources.md`](./sources.md) — the source primitive (the right answer for #20)
 - [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
 - [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't

package/skills/migrating-to-directive/core-patterns.md

@@ -11,6 +11,8 @@ User wants to...
 ├── Store state → schema.facts + init()
 ├── Compute derived values → schema.derivations + derive
 ├── React to state changes → effects
+├── Subscribe to an external event stream (WebSocket, Supabase realtime,
+│   browser events, MCP server lifecycle) → sources
 ├── Trigger side effects when conditions are met → constraints + resolvers
 ├── Handle user actions → schema.events + events handlers
 └── Coordinate multiple modules → createSystem({ modules: {} })
@@ -233,6 +235,7 @@ const typed = createModule("typed", {
 
 - [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
 - [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`sources.md`](./sources.md) — typed external event sources (the inbound dual of effects)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
 - [`multi-module.md`](./multi-module.md) — when a single module isn't enough
 - [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined

package/skills/reviewing-directive-code/anti-patterns.md

@@ -2,7 +2,7 @@
 
 > Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
 
-19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+21 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
 
 ## 1. Unnecessary Type Casting on Facts/Derivations
 
@@ -357,6 +357,97 @@ const system = createSystem({
 });
 ```
 
+## 20. Hand-Rolled External Subscriptions Inside React/`useEffect`
+
+When wrapping an external event stream (Supabase realtime, WebSocket, polling timer, browser listener) into a Directive system, do NOT write a React `useEffect` that owns the subscription and dispatches `sys.events.X()` from the callback — declare a `source` on the module instead. The runtime owns the mount / unmount lifecycle and observability. The component collapses to fact reads.
+
+```typescript
+// WRONG – subscription lives in component code; module never knows about it.
+// On every remount you get duplicate channels; on unmount you can leak.
+function Game({ system, gameId }: Props) {
+  useEffect(() => {
+    const ch = supabase
+      .channel(`game:${gameId}`)
+      .on('postgres_changes', { event: 'UPDATE', table: 'games' }, (payload) => {
+        system.events.realtimeUpdate({ snapshot: mapRow(payload.new) });
+      })
+      .subscribe();
+    return () => { supabase.removeChannel(ch); };
+  }, [gameId]);
+  return <Board snapshot={useFact(system, 'snapshot')} />;
+}
+
+// CORRECT – declare a `source` on the module. The runtime owns the
+// mount / unmount lifecycle and observability. The component collapses
+// to fact reads.
+const gameModule = createModule('game', {
+  schema: {
+    facts: { snapshot: t.object<GameSnapshot>().nullable() },
+    events: { realtimeUpdate: { snapshot: t.object<GameSnapshot>() } },
+  },
+  sources: {
+    realtime: {
+      attach: (publish) => {
+        const ch = supabase
+          .channel(`game:${gameId}`)
+          .on('postgres_changes', { event: 'UPDATE', table: 'games' },
+            (p) => publish('realtimeUpdate', { snapshot: mapRow(p.new) }))
+          .subscribe();
+        return () => { supabase.removeChannel(ch); };
+      },
+    },
+  },
+  on: { realtimeUpdate: (f, p) => { f.snapshot = p.snapshot; } },
+});
+```
+
+**Why:** the hook-as-bridge pattern duplicates lifecycle code at every call site. Cleanup correctness drifts. `system.observe()` can't see the subscription. With a `source`, the engine attaches at `start()`, detaches at `stop()`, isolates failures, and emits `source.attach` / `.publish` / `.detach` / `.error` observation events for plugins.
+
+**Don't subscribe in both an effect AND a source on the same channel** — the effect re-runs on fact changes, the source mounts once, you'll get 2× messages with silent duplicates. Pick one.
+
+See [`sources.md`](./sources.md) for the full decision tree, recipes (Supabase / WebSocket / browser events / polling), and the typed-publish factory pattern.
+
+## 21. Abbreviating Type Names (`*Def` instead of `*Definition`)
+
+```typescript
+// WRONG – `Def` is short for `Definition`. Same anti-pattern as `ctx`
+// → `context` (entry #5). Source code reads better with spelled-out
+// names; the minifier handles the bytes either way.
+import type { ModuleDef, SourceDef, ResolverDef } from "@directive-run/core";
+
+// CORRECT – use the spelled-out aliases. `*Def` stays canonical in 1.x
+// for back-compat; consumers can migrate today.
+import type {
+  ModuleDefinition,
+  SourceDefinition,
+  ResolverDefinition,
+} from "@directive-run/core";
+```
+
+The `*Definition` aliases ship in 1.x via `export type { X as XDefinition }`
+in `packages/core/src/core/types/index.ts`, so generic forwarding +
+TS inference rules (mapped types, conditional distribution, tagged-
+union discrimination, barrel re-exports) match the canonical `*Def`
+form bit-for-bit. **2.0 swaps:** `*Definition` becomes canonical and
+`*Def` becomes the deprecated alias. Start writing `*Definition` in
+new code today so the 2.0 migration is a no-op.
+
+Per RFC 0006, this applies to:
+
+- `ModuleDef` → `ModuleDefinition`
+- `ConstraintDef` / `ConstraintsDef` → `ConstraintDefinition` / `ConstraintsDefinition`
+- `ResolverDef` / `ResolversDef` → `ResolverDefinition` / `ResolversDefinition`
+- `DerivationDef` / `DerivationsDef` → `DerivationDefinition` / `DerivationsDefinition`
+- `EffectDef` / `EffectsDef` → `EffectDefinition` / `EffectsDefinition`
+- `EventsDef` → `EventsDefinition`
+- `SourceDef` / `SourcesDef` → `SourceDefinition` / `SourcesDefinition`
+- `SourcePublish` → `SourcePublishFn`, `SourceUnsubscribe` → `SourceUnsubscribeFn`
+- Plus all `Typed*Def`, `CrossModule*Def`, `Dynamic*Def` variants.
+
+`EffectCleanup`, `MetaAccessor`, `EventsAccessor`, `DeriveAccessor`,
+`Snapshot` are explicitly kept as-is (each has reasoning recorded in
+RFC 0006).
+
 ## Quick Reference Checklist
 
 Before generating any Directive code, verify:
@@ -371,10 +462,12 @@ Before generating any Directive code, verify:
 8. Multi-module uses `facts.self.*` for own facts
 9. Imports from `@directive-run/core`, not deep paths
 10. `await system.settle()` after `system.start()`
+11. External event subscriptions live in `sources:`, not in `useEffect` or `onMount`
 
 ## See also
 
 - [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`sources.md`](./sources.md) — the source primitive (the right answer for #20)
 - [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
 - [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't

package/skills/reviewing-directive-code/core-patterns.md

@@ -11,6 +11,8 @@ User wants to...
 ├── Store state → schema.facts + init()
 ├── Compute derived values → schema.derivations + derive
 ├── React to state changes → effects
+├── Subscribe to an external event stream (WebSocket, Supabase realtime,
+│   browser events, MCP server lifecycle) → sources
 ├── Trigger side effects when conditions are met → constraints + resolvers
 ├── Handle user actions → schema.events + events handlers
 └── Coordinate multiple modules → createSystem({ modules: {} })
@@ -233,6 +235,7 @@ const typed = createModule("typed", {
 
 - [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
 - [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`sources.md`](./sources.md) — typed external event sources (the inbound dual of effects)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
 - [`multi-module.md`](./multi-module.md) — when a single module isn't enough
 - [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined

package/skills/reviewing-directive-code/naming.md

@@ -16,7 +16,8 @@ This file is both the rules and the bridge. Search for the term you already know
 | **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. |
+| **subscription**, **listener**, **reaction**, **watcher** | Zustand subscribe, MobX reactions, Redux subscriptions | **effects** (for fact-change reactions) or **sources** (for external event streams) | Reacting to facts → **effects**; subscribing to an external stream that publishes INTO facts → **sources**. Both replace ad-hoc `subscribe()`/`useEffect` patterns. |
+| **observable**, **subject**, **event source**, **WebSocket/SSE subscription** | RxJS, DOM `addEventListener`, EventSource, Supabase Realtime | **sources** | The inbound dual of effects. Mount-once external event stream the runtime owns. Declared on a module; auto-detached on `system.stop()`. |
 | **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. |
@@ -54,6 +55,10 @@ Tagged union `{ type: "FETCH_USER", … }`. Constraints emit them; the runtime d
 
 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.
 
+### `sources` — typed external event subscriptions
+
+The inbound dual of effects. Declared via `sources: { name: { attach: (publish) => cleanup } }`. The runtime mounts each source once at `system.start()` and unmounts at `system.stop()`. Inside `attach`, the source subscribes to an external event stream (WebSocket, Supabase realtime, browser events, MCP server lifecycle) and calls `publish(eventName, payload)` to dispatch into the system's event queue. Sources are the canonical replacement for `useEffect(() => subscribe(); return unsubscribe)` patterns. See [`sources.md`](./sources.md).
+
 ### `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.

package/skills/scaffolding-directive-modules/core-patterns.md

@@ -11,6 +11,8 @@ User wants to...
 ├── Store state → schema.facts + init()
 ├── Compute derived values → schema.derivations + derive
 ├── React to state changes → effects
+├── Subscribe to an external event stream (WebSocket, Supabase realtime,
+│   browser events, MCP server lifecycle) → sources
 ├── Trigger side effects when conditions are met → constraints + resolvers
 ├── Handle user actions → schema.events + events handlers
 └── Coordinate multiple modules → createSystem({ modules: {} })
@@ -233,6 +235,7 @@ const typed = createModule("typed", {
 
 - [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
 - [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`sources.md`](./sources.md) — typed external event sources (the inbound dual of effects)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
 - [`multi-module.md`](./multi-module.md) — when a single module isn't enough
 - [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined

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

@@ -16,7 +16,8 @@ This file is both the rules and the bridge. Search for the term you already know
 | **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. |
+| **subscription**, **listener**, **reaction**, **watcher** | Zustand subscribe, MobX reactions, Redux subscriptions | **effects** (for fact-change reactions) or **sources** (for external event streams) | Reacting to facts → **effects**; subscribing to an external stream that publishes INTO facts → **sources**. Both replace ad-hoc `subscribe()`/`useEffect` patterns. |
+| **observable**, **subject**, **event source**, **WebSocket/SSE subscription** | RxJS, DOM `addEventListener`, EventSource, Supabase Realtime | **sources** | The inbound dual of effects. Mount-once external event stream the runtime owns. Declared on a module; auto-detached on `system.stop()`. |
 | **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. |
@@ -54,6 +55,10 @@ Tagged union `{ type: "FETCH_USER", … }`. Constraints emit them; the runtime d
 
 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.
 
+### `sources` — typed external event subscriptions
+
+The inbound dual of effects. Declared via `sources: { name: { attach: (publish) => cleanup } }`. The runtime mounts each source once at `system.start()` and unmounts at `system.stop()`. Inside `attach`, the source subscribes to an external event stream (WebSocket, Supabase realtime, browser events, MCP server lifecycle) and calls `publish(eventName, payload)` to dispatch into the system's event queue. Sources are the canonical replacement for `useEffect(() => subscribe(); return unsubscribe)` patterns. See [`sources.md`](./sources.md).
+
 ### `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.

package/skills/writing-directive-modules/anti-patterns.md

@@ -2,7 +2,7 @@
 
 > Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
 
-19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+21 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
 
 ## 1. Unnecessary Type Casting on Facts/Derivations
 
@@ -357,6 +357,97 @@ const system = createSystem({
 });
 ```
 
+## 20. Hand-Rolled External Subscriptions Inside React/`useEffect`
+
+When wrapping an external event stream (Supabase realtime, WebSocket, polling timer, browser listener) into a Directive system, do NOT write a React `useEffect` that owns the subscription and dispatches `sys.events.X()` from the callback — declare a `source` on the module instead. The runtime owns the mount / unmount lifecycle and observability. The component collapses to fact reads.
+
+```typescript
+// WRONG – subscription lives in component code; module never knows about it.
+// On every remount you get duplicate channels; on unmount you can leak.
+function Game({ system, gameId }: Props) {
+  useEffect(() => {
+    const ch = supabase
+      .channel(`game:${gameId}`)
+      .on('postgres_changes', { event: 'UPDATE', table: 'games' }, (payload) => {
+        system.events.realtimeUpdate({ snapshot: mapRow(payload.new) });
+      })
+      .subscribe();
+    return () => { supabase.removeChannel(ch); };
+  }, [gameId]);
+  return <Board snapshot={useFact(system, 'snapshot')} />;
+}
+
+// CORRECT – declare a `source` on the module. The runtime owns the
+// mount / unmount lifecycle and observability. The component collapses
+// to fact reads.
+const gameModule = createModule('game', {
+  schema: {
+    facts: { snapshot: t.object<GameSnapshot>().nullable() },
+    events: { realtimeUpdate: { snapshot: t.object<GameSnapshot>() } },
+  },
+  sources: {
+    realtime: {
+      attach: (publish) => {
+        const ch = supabase
+          .channel(`game:${gameId}`)
+          .on('postgres_changes', { event: 'UPDATE', table: 'games' },
+            (p) => publish('realtimeUpdate', { snapshot: mapRow(p.new) }))
+          .subscribe();
+        return () => { supabase.removeChannel(ch); };
+      },
+    },
+  },
+  on: { realtimeUpdate: (f, p) => { f.snapshot = p.snapshot; } },
+});
+```
+
+**Why:** the hook-as-bridge pattern duplicates lifecycle code at every call site. Cleanup correctness drifts. `system.observe()` can't see the subscription. With a `source`, the engine attaches at `start()`, detaches at `stop()`, isolates failures, and emits `source.attach` / `.publish` / `.detach` / `.error` observation events for plugins.
+
+**Don't subscribe in both an effect AND a source on the same channel** — the effect re-runs on fact changes, the source mounts once, you'll get 2× messages with silent duplicates. Pick one.
+
+See [`sources.md`](./sources.md) for the full decision tree, recipes (Supabase / WebSocket / browser events / polling), and the typed-publish factory pattern.
+
+## 21. Abbreviating Type Names (`*Def` instead of `*Definition`)
+
+```typescript
+// WRONG – `Def` is short for `Definition`. Same anti-pattern as `ctx`
+// → `context` (entry #5). Source code reads better with spelled-out
+// names; the minifier handles the bytes either way.
+import type { ModuleDef, SourceDef, ResolverDef } from "@directive-run/core";
+
+// CORRECT – use the spelled-out aliases. `*Def` stays canonical in 1.x
+// for back-compat; consumers can migrate today.
+import type {
+  ModuleDefinition,
+  SourceDefinition,
+  ResolverDefinition,
+} from "@directive-run/core";
+```
+
+The `*Definition` aliases ship in 1.x via `export type { X as XDefinition }`
+in `packages/core/src/core/types/index.ts`, so generic forwarding +
+TS inference rules (mapped types, conditional distribution, tagged-
+union discrimination, barrel re-exports) match the canonical `*Def`
+form bit-for-bit. **2.0 swaps:** `*Definition` becomes canonical and
+`*Def` becomes the deprecated alias. Start writing `*Definition` in
+new code today so the 2.0 migration is a no-op.
+
+Per RFC 0006, this applies to:
+
+- `ModuleDef` → `ModuleDefinition`
+- `ConstraintDef` / `ConstraintsDef` → `ConstraintDefinition` / `ConstraintsDefinition`
+- `ResolverDef` / `ResolversDef` → `ResolverDefinition` / `ResolversDefinition`
+- `DerivationDef` / `DerivationsDef` → `DerivationDefinition` / `DerivationsDefinition`
+- `EffectDef` / `EffectsDef` → `EffectDefinition` / `EffectsDefinition`
+- `EventsDef` → `EventsDefinition`
+- `SourceDef` / `SourcesDef` → `SourceDefinition` / `SourcesDefinition`
+- `SourcePublish` → `SourcePublishFn`, `SourceUnsubscribe` → `SourceUnsubscribeFn`
+- Plus all `Typed*Def`, `CrossModule*Def`, `Dynamic*Def` variants.
+
+`EffectCleanup`, `MetaAccessor`, `EventsAccessor`, `DeriveAccessor`,
+`Snapshot` are explicitly kept as-is (each has reasoning recorded in
+RFC 0006).
+
 ## Quick Reference Checklist
 
 Before generating any Directive code, verify:
@@ -371,10 +462,12 @@ Before generating any Directive code, verify:
 8. Multi-module uses `facts.self.*` for own facts
 9. Imports from `@directive-run/core`, not deep paths
 10. `await system.settle()` after `system.start()`
+11. External event subscriptions live in `sources:`, not in `useEffect` or `onMount`
 
 ## See also
 
 - [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`sources.md`](./sources.md) — the source primitive (the right answer for #20)
 - [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
 - [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't

package/skills/writing-directive-modules/core-patterns.md

@@ -11,6 +11,8 @@ User wants to...
 ├── Store state → schema.facts + init()
 ├── Compute derived values → schema.derivations + derive
 ├── React to state changes → effects
+├── Subscribe to an external event stream (WebSocket, Supabase realtime,
+│   browser events, MCP server lifecycle) → sources
 ├── Trigger side effects when conditions are met → constraints + resolvers
 ├── Handle user actions → schema.events + events handlers
 └── Coordinate multiple modules → createSystem({ modules: {} })
@@ -233,6 +235,7 @@ const typed = createModule("typed", {
 
 - [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
 - [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`sources.md`](./sources.md) — typed external event sources (the inbound dual of effects)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
 - [`multi-module.md`](./multi-module.md) — when a single module isn't enough
 - [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined

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

@@ -16,7 +16,8 @@ This file is both the rules and the bridge. Search for the term you already know
 | **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. |
+| **subscription**, **listener**, **reaction**, **watcher** | Zustand subscribe, MobX reactions, Redux subscriptions | **effects** (for fact-change reactions) or **sources** (for external event streams) | Reacting to facts → **effects**; subscribing to an external stream that publishes INTO facts → **sources**. Both replace ad-hoc `subscribe()`/`useEffect` patterns. |
+| **observable**, **subject**, **event source**, **WebSocket/SSE subscription** | RxJS, DOM `addEventListener`, EventSource, Supabase Realtime | **sources** | The inbound dual of effects. Mount-once external event stream the runtime owns. Declared on a module; auto-detached on `system.stop()`. |
 | **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. |
@@ -54,6 +55,10 @@ Tagged union `{ type: "FETCH_USER", … }`. Constraints emit them; the runtime d
 
 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.
 
+### `sources` — typed external event subscriptions
+
+The inbound dual of effects. Declared via `sources: { name: { attach: (publish) => cleanup } }`. The runtime mounts each source once at `system.start()` and unmounts at `system.stop()`. Inside `attach`, the source subscribes to an external event stream (WebSocket, Supabase realtime, browser events, MCP server lifecycle) and calls `publish(eventName, payload)` to dispatch into the system's event queue. Sources are the canonical replacement for `useEffect(() => subscribe(); return unsubscribe)` patterns. See [`sources.md`](./sources.md).
+
 ### `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.