@directive-run/knowledge 1.17.2 → 1.19.0

package/ai/ai-security.md

@@ -380,6 +380,62 @@ createCompliance({
 })
 ```
 
+## Sources × PII — closing the fact-injection bypass
+
+`createPIIGuardrail` and `createEnhancedPIIGuardrail` only inspect the
+`data.input` argument passed to `runStream(agent, input, ...)`. When a
+source publishes PII into a fact and the agent's prompt template embeds
+that fact (`"Hello ${facts.email}..."`), the PII reaches the LLM call
+without hitting the input guardrail chain.
+
+This is the documented R5 audit finding (red team, privacy, AI-integration
+reviewers independently flagged it). The Tier 0 fix:
+
+```ts
+import { createSystem, createModule, t } from "@directive-run/core";
+import { createFactPIIGuardrail } from "@directive-run/ai/guardrails";
+
+const customer = createModule("customer", {
+  schema: {
+    facts: {
+      email: t.string().meta({ tags: ["pii"] }),  // ← tag pii-bearing facts
+      ssn: t.string().meta({ tags: ["pii"] }),
+    },
+  },
+  sources: { /* Supabase realtime, webhook, ... */ },
+});
+
+const system = createSystem({
+  module: customer,
+  plugins: [
+    createFactPIIGuardrail({
+      mode: "redact",            // 'redact' (safe default) | 'alert'
+      onBlocked: (key, detected) =>
+        Sentry.captureMessage(`pii redacted: ${key}`, {
+          extra: { count: detected.length },
+        }),
+    }),
+  ],
+});
+```
+
+The plugin scans every write to a `pii`-tagged fact (auto-discovered via
+`meta.byTag("pii")` at `onInit`) and either redacts the value (default —
+rewrites via a follow-up store write so the next read sees the redacted
+form) or alerts (fires `onBlocked` without mutating). Together with the
+input-guardrail chain on `runStream`, this closes the source → fact →
+prompt PII path.
+
+**Limitation:** hard rejection at the write boundary requires a
+pre-commit transform hook on the source primitive itself (Directive
+plugin hooks are wrapped by `safeCall` and a thrown error is
+swallowed). Tracked as a future RFC; today's `"redact"` mode is the
+safe-shipping posture.
+
+See [`ai-sources.md`](./ai-sources.md) for the full source primitive
+integration recipes, including the live-context pattern that
+`createFactPIIGuardrail` gates.
+
 ## Quick reference
 
 | API | Import path | Returns | Purpose |
@@ -387,6 +443,7 @@ createCompliance({
 | `createPIIGuardrail` | `@directive-run/ai/guardrails` | `GuardrailFn<InputGuardrailData>` | Basic input PII detection (block or redact) |
 | `createEnhancedPIIGuardrail` | `@directive-run/ai/guardrails` | guardrail | Context-aware input PII |
 | `createOutputPIIGuardrail` | `@directive-run/ai/guardrails` | guardrail | Output PII coverage |
+| `createFactPIIGuardrail` | `@directive-run/ai/guardrails` | `Plugin` | **Fact-boundary PII guardrail — closes the source → fact → prompt bypass. Wire at `createSystem({ plugins })`.** |
 | `createPromptInjectionGuardrail` | `@directive-run/ai/guardrails` | guardrail | Risk-scored injection defense (`strictMode`, `blockThreshold`) |
 | `createAuditTrail` | `@directive-run/ai` | `AuditInstance` | Hash-chained audit log w/ signing + PII masking + async export |
 | `createCompliance` | `@directive-run/ai` | `ComplianceInstance` | GDPR exportData / deleteData / consent + retention enforcement |

package/ai/ai-sources.md

@@ -0,0 +1,433 @@
+# AI × Sources
+
+> Wire `@directive-run/core`'s `source` primitive into `@directive-run/ai`
+> agents and orchestrators. Sources are how external event streams
+> (Supabase realtime, WebSockets, Cloudflare DO alarms, MCP server lifecycle)
+> publish into facts that agents reason over.
+
+The source primitive's full semantics live at
+[`../core/sources.md`](../core/sources.md). This doc covers the AI-specific
+patterns: which external streams to wire as a source vs. as an
+`AsyncIterable` (anti-pattern), how `runStream` reacts to live fact
+changes, how to keep PII out of agent prompts, and which existing
+adapter (`@directive-run/sources/*`) covers the common vendors.
+
+---
+
+## Decision: source vs AsyncIterable
+
+A long-running external stream can show up as a Directive **source** OR
+as a per-call **AsyncIterable**. The boundary is durable.
+
+| Use a **source** when... | Use an **AsyncIterable** when... |
+|---|---|
+| The stream's lifetime is the **system's lifetime** (Supabase realtime channel, WebSocket message stream, MCP server connection) | The stream's lifetime is **one agent generation** (LLM token stream from `runStream`, per-call SSE response) |
+| You want every message to update **facts** the agent reasons over | You want the LLM's output tokens delivered to a single caller |
+| The publisher cannot read facts | The consumer needs to act on each chunk synchronously |
+
+**Three-tier lifetime ladder:**
+
+1. **System source** (outermost): Supabase channel, MCP server, DO alarm,
+   WebSocket message stream. Mount at `system.start()`, tear down at
+   `system.stop()`.
+2. **Conversation subscription** (middle): per-agent message bus
+   subscription, PubSub topic subscription, per-agent breakpoint waiter.
+   Created in the orchestrator's constructor, cleaned up on
+   destroy. Lives across many generations.
+3. **Generation iterable** (innermost): the actual LLM token AsyncIterable
+   returned by `runStream`. Created per `runStream` call, ends when the
+   model finishes or `abort()` fires.
+
+Sources own the outermost ring; AsyncIterable owns the innermost; the
+middle ring is what `@directive-run/ai/communication` covers today.
+
+---
+
+## Recipes by user intent
+
+### "I want my agent to react to external lifecycle events"
+
+Wire the lifecycle as a source on the orchestrator's module. The agent
+sees fact-change reactions through its bound-facts view; resolvers can
+gate execution on `facts.<lifecycle>.healthy` derivations.
+
+- **MCP server connect/disconnect** → see "MCP Lifecycle" below.
+- **Health checks** → poll inside the source's `attach`; publish
+  `health_changed` events as the upstream service responds.
+- **WebSocket open / close** → `sourceFromWebSocket()` (sources/websocket).
+
+### "I want my agent's facts to update from a live external feed"
+
+This is the **live-context** pattern — the differentiator nobody in the
+agent-framework space has. See `runStream({ liveContext })` below for the
+full recipe. tl;dr: sources publish into facts; `liveContext` re-renders
+the agent's system prompt on each change AND can interrupt the stream
+when conditions warrant.
+
+### "I want to bridge a callback-based SDK into Directive"
+
+Wrap the SDK's `subscribe()` / `on('event')` API inside `attach(publish)`,
+forward the unsubscribe. Direct generalization of the source primitive —
+no AI-specific machinery required.
+
+### "I want to multiplex agent messages into the system"
+
+Use `createMessageBus` from `@directive-run/ai/communication` for
+per-agent messaging. The bus is a conversation-tier subscription (tier 2
+above), not a source. Wire it inside the orchestrator's constructor.
+
+---
+
+## `runStream({ liveContext })` — Reactive Agents
+
+> The killer demo: the agent is mid-generation, a source publishes a fact
+> update, the agent's NEXT token reflects the new state — or interrupts
+> the stream and re-prompts with fresh context. No external orchestration
+> required.
+
+### When to use
+
+- A market-data agent whose recommendation depends on live prices.
+- A coding agent reviewing a PR while commits keep landing.
+- A customer-support agent whose context updates when Stripe confirms a
+  refund mid-conversation.
+
+### Signature
+
+```ts
+const result = orchestrator.runStream(agent, input, {
+  signal,                                     // existing AbortSignal — terminates stream
+  liveContext: {
+    system,                                   // the Directive system whose facts feed the agent
+    keys: ["pr.headSha", "pr.state"],         // REQUIRED — fact keys to watch
+    interruptWhen: (facts, changedKeys) => boolean,  // optional; default: () => true
+    notifyOn: "interrupt-only",               // default; "all-changes" emits chunk per watched change
+    onContextUpdate: (changedKeys) => void,   // optional logging hook
+  },
+});
+
+// New methods on the returned result:
+result.interrupt(reason?);  // cancel in-flight LLM run, KEEP liveContext alive
+result.abort();             // tear down stream + detach liveContext
+```
+
+Two new chunk variants land on the stream:
+
+```ts
+| { type: "context_updated"; changedKeys: readonly string[] }
+| {
+    type: "interrupted";
+    reason: string;
+    partialOutput: string;
+    changedKeys: readonly string[];
+  }
+```
+
+### Anatomy
+
+- The orchestrator subscribes to `system.facts.$store.subscribe(keys, ...)`
+  for the keys it depends on — the same bridge primitive that powers
+  breakpoints and approvals elsewhere in `agent-orchestrator.ts`.
+- The subscription wires up BEFORE the LLM run's IIFE starts, so a fact
+  change during the input-guardrail phase is observed correctly.
+- On each batch of fact changes that touches the watched keys:
+  - `liveContext.onContextUpdate(changedKeys)` fires (logging hook).
+  - `interruptWhen(facts, changedKeys)` runs.
+  - If it returns `true`, the orchestrator emits an `interrupted` chunk
+    with the partial output captured so far + the changed keys, then
+    aborts the in-flight LLM stream. The consumer's `for await` sees
+    the `interrupted` chunk before the final `error` chunk lands.
+  - If it returns `false` and `notifyOn === "all-changes"`, a
+    `context_updated` chunk is emitted. With the default
+    `"interrupt-only"`, no chunk is emitted for non-interrupting
+    changes.
+- `result.interrupt(reason?)` is the CALLER-driven counterpart: same
+  `interrupted` chunk, same abort, but the subscription stays attached
+  so the next caller-driven `runStream` continues against the live
+  fact stream without re-subscribing.
+
+### Status — shipped
+
+`runStream({ liveContext })` is the dedicated subject of
+[RFC 0005](../../docs/rfcs/0005-live-context-agent.md). Today's
+implementation is **231 LOC in `agent-orchestrator.ts`** — under the
+RFC's 300-LOC scope guard. The `mode: "restart"` automatic
+re-invocation is reserved for a follow-up minor; today both `mode`
+values produce identical behavior (the chunk-emission contract +
+abort wiring; consumers re-prompt via a fresh `runStream` call).
+
+**Security companion (mandatory when watched facts may carry PII):**
+wire `createFactPIIGuardrail` on the same Directive system. Without
+it, `liveContext` expands the source → fact → prompt PII bypass
+surface into mid-stream context updates. See the
+["Sources × Security"](#sources--security) section below for the full
+threat model.
+
+---
+
+## MCP Lifecycle as a Source
+
+`@directive-run/ai/mcp` exposes `MCPAdapterConfig.events`
+(`onConnect`, `onDisconnect`, `onToolCall`, `onError`, ...) as a single
+bag of callbacks set at adapter-construction time. To bridge the
+adapter's lifecycle into a Directive source the recipe is: declare a
+holder that the source's `attach` populates with the live `publish`,
+then point the adapter's `events.onConnect` / `onDisconnect` at the
+holder. The holder pattern lets you construct the adapter and the
+source in either order — the source's mount/unmount drives which
+publish closure (if any) receives lifecycle events.
+
+```ts
+import { createSystem, createModule, t } from "@directive-run/core";
+import type { SourcePublish } from "@directive-run/core";
+import { createMCPAdapter } from "@directive-run/ai/mcp";
+
+// Holder that the source's `attach` populates. The adapter's events
+// forward through this — when the source is detached (`attach`'s
+// unsubscribe runs), the holder goes null and the adapter callbacks
+// no-op. This guarantees post-stop lifecycle events from the MCP
+// transport can't write into a torn-down system.
+let publishRef: SourcePublish | null = null;
+
+const adapter = createMCPAdapter({
+  servers: [/* ... */],
+  events: {
+    onConnect: (name) => publishRef?.("MCP_SERVER_CONNECTED", { name }),
+    onDisconnect: (name) => publishRef?.("MCP_SERVER_DISCONNECTED", { name }),
+  },
+});
+
+const orchestrator = createModule("orchestrator", {
+  schema: {
+    facts: {
+      mcp: t.object<{
+        servers: Record<string, "connected" | "disconnected">;
+      }>(),
+    },
+    events: {
+      MCP_SERVER_CONNECTED: { name: t.string() },
+      MCP_SERVER_DISCONNECTED: { name: t.string() },
+    },
+    derivations: {
+      allServersHealthy: t.boolean(),
+    },
+  },
+  init: (f) => {
+    f.mcp = { servers: {} };
+  },
+  events: {
+    MCP_SERVER_CONNECTED: (f, p) => {
+      f.mcp = {
+        ...f.mcp,
+        servers: { ...f.mcp.servers, [p.name]: "connected" },
+      };
+    },
+    MCP_SERVER_DISCONNECTED: (f, p) => {
+      f.mcp = {
+        ...f.mcp,
+        servers: { ...f.mcp.servers, [p.name]: "disconnected" },
+      };
+    },
+  },
+  derive: {
+    allServersHealthy: (facts) =>
+      Object.values(facts.mcp.servers).every((s) => s === "connected"),
+  },
+  sources: {
+    mcpLifecycle: {
+      attach: (publish) => {
+        publishRef = publish;
+        // Kick the adapter's connection lifecycle once the source is
+        // attached so the first `onConnect` flows into our publish.
+        void adapter.connect();
+        return async () => {
+          publishRef = null;
+          await adapter.disconnect();
+        };
+      },
+    },
+  },
+});
+```
+
+Constraints can now gate agent execution on
+`facts.allServersHealthy` — no separate health-check loop needed.
+
+> The holder + closure pattern is the canonical bridge from any
+> single-callback-bag third-party SDK (MCP, telemetry SDKs that take an
+> `onEvent` config at construction) into a Directive source. The
+> alternative — passing `publish` from inside `attach` into the
+> adapter's events — requires the adapter to be constructed AFTER the
+> source is created, which is awkward when the adapter is used outside
+> Directive too.
+
+---
+
+## Sources × Security
+
+> A source can publish PII into a fact BEFORE any input guardrail runs.
+> The pattern is real and exploitable. ALWAYS wire `createFactPIIGuardrail`
+> when sources feed facts the agent will reason over.
+
+### The bypass chain
+
+1. Source wraps Supabase realtime: `subscribe('users', row => publish('USER_UPDATED', { email: row.email, ssn: row.ssn }))`.
+2. Event handler writes: `f.email = payload.email; f.ssn = payload.ssn;`.
+3. Agent prompt template embeds: `"Hello ${facts.email}, your record shows ${facts.ssn}..."`.
+4. `createPIIGuardrail` (input guardrail) only inspects the `input` argument
+   passed to `runStream(agent, input, ...)`. The facts injected into the
+   prompt are **not in `input`** — they flow through the resolver's
+   templating layer.
+5. The LLM call ships the PII. The audit ledger's `fact.change` entry
+   carries it. Devtools / breakpoint snapshots see it. Operators see it.
+
+### The fix — `createFactPIIGuardrail`
+
+A Directive plugin that scans every write to a `pii`-tagged fact and
+either redacts (default) or alerts:
+
+```ts
+import { createSystem } from "@directive-run/core";
+import { createFactPIIGuardrail } from "@directive-run/ai/guardrails";
+
+const system = createSystem({
+  module: customer,                 // schema tags `email` + `ssn` with `tags: ['pii']`
+  plugins: [
+    createFactPIIGuardrail({
+      mode: "redact",               // 'redact' (default) | 'alert'
+      types: ["ssn", "credit_card", "email"],
+      onBlocked: (key, detected) => {
+        Sentry.captureMessage(`pii redacted: ${key}`, { extra: { count: detected.length } });
+      },
+    }),
+  ],
+});
+```
+
+**Modes:**
+
+- `"redact"` (default, safest): rewrites the fact value via a follow-up
+  store write. The raw value briefly exists for one microtask while the
+  redaction lands; downstream subscribers that snapshot at that instant
+  see it; the LLM call after the next settle does not.
+- `"alert"`: fires `onBlocked` but does NOT mutate the fact. Use for
+  monitoring-only deployments where the source's transport is already
+  trusted and you want to page on every match without modifying state.
+
+The plugin scans `pii`-tagged facts auto-detected via `meta.byTag("pii")`,
+plus any `includeKeys` you list explicitly. The built-in regex matches
+SSN, credit card, and email; pass a `customDetector` for domain-specific
+patterns (internal account numbers, partner IDs).
+
+### Limitation — hard rejection needs an RFC
+
+Plugin hooks (`onFactSet`, `onFactsBatch`) are wrapped by the plugin
+manager's `safeCall`, so a `throw` from the guardrail can't actually
+reject the write. The `"redact"` mode handles this with a follow-up write;
+the `"alert"` mode is observation-only. Hard rejection at the publish
+boundary requires a pre-commit transform hook on the source primitive
+itself — that's tracked as a future RFC. For now: wire `"redact"` for
+safety, `"alert"` for monitoring.
+
+See also: [`ai-security.md`](./ai-security.md) — "Sources × PII" section
+for the full threat model and the additional output-side mitigations
+that should accompany this plugin in regulated deployments.
+
+---
+
+## Adapter packages
+
+The canonical bridges live in **`@directive-run/sources`** as subpath
+exports. One install, optional peerDependencies per vendor.
+
+| Subpath | Source factory | Wraps |
+|---|---|---|
+| `@directive-run/sources/supabase` | `sourceFromSupabaseChannel()` | Supabase realtime channel |
+| `@directive-run/sources/cloudflare` | `sourceFromDOAlarm()` | Cloudflare Durable Object alarm |
+| `@directive-run/sources/websocket` | `sourceFromWebSocket()` | (future RFC) raw WebSocket |
+| `@directive-run/sources/sentry` | `sourceFromSentryHook()` | (future RFC) Sentry production-error stream |
+
+Install only the umbrella; the vendor peerDeps are optional and pull in
+only when the corresponding subpath is imported.
+
+---
+
+## Anti-patterns
+
+### Anti-pattern A — Don't use a source for token streaming
+
+LLM tokens are a per-generation hot stream. Wrap them in an
+`AsyncIterable` (the existing `runStream` contract), not a source.
+
+```ts
+// WRONG — sources are mount-once; tokens are per-call
+sources: {
+  llmTokens: {
+    attach: (publish) => {
+      const stream = openai.chat.completions.create({ stream: true });
+      for await (const chunk of stream) {
+        publish("TOKEN", { content: chunk.choices[0].delta.content });
+      }
+      return () => stream.abort();
+    },
+  },
+},
+
+// RIGHT — tokens flow through the runStream AsyncIterable
+const result = orchestrator.runStream(agent, input);
+for await (const chunk of result.stream) {
+  if (chunk.type === "token") render(chunk.content);
+}
+```
+
+The rule: **source per connection; AsyncIterable per generation.**
+
+### Anti-pattern B — Don't poll an external system from a constraint
+
+Constraints model declarative when-then rules over facts. A
+`setInterval` inside a constraint smuggles a long-running subscription
+into a non-lifecycle hook.
+
+```ts
+// WRONG — constraint kicks off polling that lives forever
+constraints: {
+  pollLatest: {
+    when: (facts) => true,
+    require: { type: "POLL_INVENTORY" },
+  },
+},
+resolvers: {
+  pollInventory: {
+    requirement: "POLL_INVENTORY",
+    resolve: async (req, context) => {
+      setInterval(async () => {
+        const latest = await fetch("/api/inventory");
+        context.facts.inventory = await latest.json();
+      }, 5000);
+    },
+  },
+},
+
+// RIGHT — declare a source; the engine owns the lifecycle
+sources: {
+  inventoryPoll: {
+    attach: (publish) => {
+      const id = setInterval(async () => {
+        const latest = await fetch("/api/inventory");
+        publish("INVENTORY_LATEST", await latest.json());
+      }, 5000);
+      return () => clearInterval(id);
+    },
+  },
+},
+```
+
+---
+
+## Related
+
+- [`../core/sources.md`](../core/sources.md) — full source primitive semantics, lifecycle, recipes
+- [`ai-security.md`](./ai-security.md) — PII detection, prompt-injection, output guardrails (see "Sources × PII" section)
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `createAgentOrchestrator` + `runStream`
+- [`ai-mcp-rag.md`](./ai-mcp-rag.md) — MCP adapter
+- [`ai-communication.md`](./ai-communication.md) — agent message bus + PubSub

package/core/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/core/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/core/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/core/sources.md

@@ -0,0 +1,424 @@
+# Sources
+
+> Covers `@directive-run/core` — `source` primitive: typed external event sources, the inbound dual of effects. Use for Supabase realtime channels, WebSocket message streams, polling timers, browser event listeners — any inbound external event that maps into the module's own event dispatch surface.
+
+Sources sit on the same lifecycle plane as effects but mount once per system instance instead of on every fact change. `attach(publish)` runs at `system.start()`; the returned unsubscribe runs at `system.stop()`.
+
+## When to use `source` vs `effect`
+
+| Use a **source** when... | Use an **effect** when... |
+|---|---|
+| You're subscribing to an external event stream (WebSocket, Supabase realtime, browser `addEventListener`, polling timer) | You're updating an external system based on fact changes (logging, DOM mutation, analytics ping) |
+| The subscription is **mount-once** for the system's lifetime | You need to re-run when a fact changes (`deps` or `on` predicate) |
+| You want to publish events INTO the system | You only need to react to fact changes |
+| You don't read facts inside the handler | You read facts (`facts.someValue`) inside `run` |
+
+If you're hand-rolling `useEffect(() => { const ch = supabase.channel(...).subscribe(); return () => ch.unsubscribe(); }, [])` in React and dispatching `sys.events.X(payload)` from the callback — that's the signature pattern sources replace. Move the subscription into the module declaration; the React hook collapses to `useFact` reads.
+
+## Decision Tree: "How should this subscription work?"
+
+```
+Do I need to subscribe to an external event stream?
+├── Yes
+│   │
+│   ├─ Does the subscription depend on a fact (e.g. "subscribe when status = active")?
+│   │  ├── Yes → Use `effect` with `deps` or `on` predicate. Effects re-run when facts change.
+│   │  └── No  → Use `source`. Mount once at system.start(); tear down at system.stop().
+│   │
+│   ├─ Does the subscription need to read facts inside the callback?
+│   │  ├── Yes → Consider hoisting the fact read up + using `effect`. Sources never read facts.
+│   │  └── No  → Use `source`. Pass any static config via closure.
+│   │
+│   └─ Do I need to publish events INTO the system from external input?
+│      └── Yes → Use `source`. The `publish` callback dispatches into the same queue as `system.events.X()`.
+│
+└── No → You probably want an effect, resolver, or event handler instead.
+```
+
+## Basic Source
+
+```typescript
+import { createModule, t } from '@directive-run/core';
+
+const counter = createModule('counter', {
+  schema: {
+    facts: { count: t.number() },
+    events: { TICK: { delta: t.number() } },
+  },
+  init: (f) => { f.count = 0; },
+  events: {
+    TICK: (f, payload) => { f.count = f.count + payload.delta; },
+  },
+  sources: {
+    heartbeat: {
+      attach: (publish) => {
+        // Subscribe to the external source. The `publish` callback dispatches
+        // into the system's event queue (same path as system.events.X()).
+        const id = setInterval(() => publish('TICK', { delta: 1 }), 1000);
+        // ALWAYS return a cleanup function. The engine calls it at system.stop().
+        return () => clearInterval(id);
+      },
+    },
+  },
+});
+```
+
+## Supabase realtime channel
+
+```typescript
+import { createModule, t } from '@directive-run/core';
+import { createClient } from '@supabase/supabase-js';
+
+interface GameUpdateModuleDeps {
+  readonly gameId: string;
+  readonly subscribeToGameUpdates: (
+    onUpdate: (snapshot: GameSnapshot) => void,
+  ) => () => void;
+}
+
+export function createGameUpdateModule(deps: GameUpdateModuleDeps) {
+  return createModule('gameUpdate', {
+    schema: {
+      facts: { snapshot: t.object<GameSnapshot>().nullable() },
+      events: { REALTIME_UPDATE: { snapshot: t.object<GameSnapshot>() } },
+    },
+    init: (f) => { f.snapshot = null; },
+    events: {
+      REALTIME_UPDATE: (f, payload) => { f.snapshot = payload.snapshot; },
+    },
+    sources: {
+      // apps/web supplies the Supabase channel via deps. The module
+      // declaration stays pure — the source just calls deps and threads
+      // the publish callback through.
+      gameUpdates: {
+        attach: (publish) =>
+          deps.subscribeToGameUpdates((snapshot) =>
+            publish('REALTIME_UPDATE', { snapshot }),
+          ),
+      },
+    },
+  });
+}
+
+// In your bootstrap (e.g. apps/web):
+const supabase = createClient(/* ... */);
+const module = createGameUpdateModule({
+  gameId: 'g-123',
+  subscribeToGameUpdates: (onUpdate) => {
+    const channel = supabase
+      .channel(`game:g-123`)
+      .on('postgres_changes', { event: 'UPDATE', table: 'games', filter: 'id=eq.g-123' },
+        (payload) => onUpdate(mapRow(payload.new)))
+      .subscribe();
+    return () => { supabase.removeChannel(channel); };
+  },
+});
+```
+
+## Browser event listener
+
+```typescript
+sources: {
+  online: {
+    attach: (publish) => {
+      const onOnline = () => publish('CONNECTIVITY_CHANGED', { online: true });
+      const onOffline = () => publish('CONNECTIVITY_CHANGED', { online: false });
+      window.addEventListener('online', onOnline);
+      window.addEventListener('offline', onOffline);
+      // Cleanup must remove BOTH listeners.
+      return () => {
+        window.removeEventListener('online', onOnline);
+        window.removeEventListener('offline', onOffline);
+      };
+    },
+  },
+}
+```
+
+## Lifecycle
+
+| Phase | What happens |
+|---|---|
+| `createSystem({ module })` | Sources are recorded in the manager but NOT attached yet |
+| `system.start()` | Each source's `attach(publish)` runs in registration order. Errors are isolated — one failed source does not block others |
+| `system.registerModule(newModule)` (system already running) | New module's sources attach IMMEDIATELY (no need to restart) |
+| `system.stop()` | Each source's returned unsubscribe runs in **reverse** registration order |
+| `system.destroy()` | Calls `stop()` first, so sources detach. After destroy, any stale publish callback the source closed over no-ops (the engine guards against post-destroy dispatch). |
+| `system.start()` again (after stop) | Sources re-attach cleanly. The manager handles the start → stop → start lifecycle without leaking subscriptions. |
+
+## Typed publish
+
+The raw `publish: (event: string, payload?: unknown) => void` deliberately uses unchecked string event names — sources don't see the module schema and shouldn't be type-coupled to it. If you want compile-time event-name + payload safety, wrap `publish` once per source:
+
+```typescript
+import type { SourcePublish } from '@directive-run/core';
+
+// Build a typed publisher up-front. Match the module's `events:` keys
+// + payload shapes exactly. The TS compiler now catches typos.
+function createPublisher(publish: SourcePublish) {
+  return {
+    TICK: (delta: number) => publish('TICK', { delta }),
+    HEARTBEAT: () => publish('HEARTBEAT'),
+  };
+}
+
+sources: {
+  ticker: {
+    attach: (publish) => {
+      const p = createPublisher(publish);
+      const id = setInterval(() => p.TICK(1), 1000); // ← typed
+      return () => clearInterval(id);
+    },
+  },
+}
+```
+
+The wrapper is purely a DX convention; the runtime path is unchanged. Recommended for any non-trivial source.
+
+## Observation
+
+Source lifecycle is fully observable. Subscribe via `system.observe()`:
+
+```typescript
+const unsub = system.observe((event) => {
+  switch (event.type) {
+    case 'source.attach': console.log(`${event.moduleId}::${event.id} attached`); break;
+    case 'source.publish': console.log(`${event.id} → ${event.eventName}`); break;
+    case 'source.detach': console.log(`${event.moduleId}::${event.id} detached`); break;
+    case 'source.error':
+      console.error(`${event.moduleId}::${event.id} ${event.phase} threw:`, event.error);
+      break;
+  }
+});
+```
+
+`system.inspect().sources` lists the declared sources + `system.inspect().attachedSourceCount` reports how many are currently bound.
+
+## Error handling — runtime errors via `reportError`
+
+Per RFC 0008, `attach` receives an optional second argument: a
+`reportError` callback. Authors route mid-flight errors from the
+underlying stream (WebSocket disconnect, Supabase channel goes stale,
+polling fetch throws) through this callback instead of inventing
+magic event names like `STREAM_ERROR`. The manager fires
+`onSourceError` with `phase: "runtime"` — distinct from `"attach"`
+(setup failed) and `"cleanup"` (unsubscribe threw) — so the audit
+ledger, logging plugin, and `inspect().sources[i].lastError`
+attribute mid-flight failures correctly.
+
+```typescript
+sources: {
+  socket: {
+    attach: (publish, reportError) => {
+      const sock = new WebSocket(url);
+      sock.addEventListener("message", (e) =>
+        publish("MSG", JSON.parse(e.data)),
+      );
+      sock.addEventListener("error", () =>
+        reportError?.(new Error("WebSocket lost connection")),
+      );
+      return () => sock.close();
+    },
+  },
+}
+```
+
+`reportError` is optional — short-lived transports that don't surface
+mid-flight errors can ignore it. The callback type is exported as
+`SourceReportError` from `@directive-run/core`. Error messages are
+truncated at 256 chars at the manager boundary so authors who embed
+payloads in error messages get a bounded leak surface.
+
+## Backpressure — `coalesce: "lastWriteWins"`
+
+Per RFC 0007, high-frequency sources (cursor moves, sensor telemetry,
+price ticks, Supabase channel storms) declare `coalesce:
+"lastWriteWins"` so the manager debounces same-event-name publishes
+within one microtask. Per-event-name keying means a `priceTick` storm
+coalesces while a one-shot `connected` event in the same tick still
+dispatches.
+
+```typescript
+sources: {
+  ticker: {
+    attach: (publish) => {
+      const id = setInterval(() => publish("TICK", { v: liveValue() }), 4);
+      return () => clearInterval(id);
+    },
+    coalesce: "lastWriteWins",  // 250 publishes/sec → 1 dispatch/microtask
+  },
+}
+```
+
+Coalesce-dropped publishes bump `dropCount` + record
+`lastDropReason: "coalesced"` on `inspect().sources` so operators
+verify the debouncing is firing on the right sources. The strategy
+is per-source (uniform across event names from that source) —
+splitting strategies per event name requires two source declarations.
+
+## Async-aware teardown — `system.stopAsync()` + DO `onEvict`
+
+Per RFC 0009, sources with async unsubscribes (Supabase realtime's
+`channel.unsubscribe()` returns a Promise; Cloudflare DO storage
+flushes return Promises) work with both sync and async teardown:
+
+- `system.stop()` (sync) — fires unsubscribes; awaits each one's
+  return synchronously (Promise returns are fire-and-forget).
+- `system.stopAsync()` (RFC 0009) — awaits each Promise-returning
+  unsubscribe. Use when the caller needs teardown to actually
+  complete (e.g. the external broker must drop the subscription
+  before the next call).
+- `system.evict(deadline?)` — Cloudflare DO eviction: fires each
+  source's optional `onEvict()` in registration order, then
+  `destroyAsync()`. Optional deadline races teardown against a
+  wall-clock cutoff so the runtime can evict the isolate even if
+  some sources hang.
+
+```typescript
+sources: {
+  channel: {
+    attach: (publish) => {
+      const ch = supabase.channel("game").subscribe();
+      ch.on("postgres_changes", { event: "UPDATE" }, (p) =>
+        publish("ROW_UPDATED", p),
+      );
+      return () => ch.unsubscribe();  // returns a Promise
+    },
+    onEvict: async () => {
+      // Cloudflare DO hibernate signal: close the channel actively
+      // so the broker drops the subscription before the isolate dies.
+      await supabase.removeChannel(ch);
+    },
+  },
+}
+```
+
+Inside a DO `alarm()` or `webSocketClose()` handler:
+`await system.evict(/* deadline */ Date.now() + 5000)`.
+
+## Common Patterns
+
+### Pattern: Source supplies inbound; resolver supplies outbound
+
+A Supabase realtime channel both INGESTS messages AND can SEND them back. The split is:
+
+```typescript
+// INGESTING — use a source. Mount once at system.start().
+sources: {
+  inbound: {
+    attach: (publish) => channel.on('postgres_changes', ..., (p) => publish('UPDATE', p)).subscribe(),
+  },
+},
+// SENDING — use a resolver. Fires on a constraint trigger.
+resolvers: {
+  sendMessage: {
+    requirement: 'SEND_MESSAGE',
+    resolve: async (req) => { await supabase.channel('chat').send(req); },
+  },
+}
+```
+
+### Pattern: Roster + reconnect
+
+A source for the channel + an effect keyed on `isReconnecting` for refresh logic:
+
+```typescript
+sources: {
+  channel: { attach: (publish) => connect(publish) },
+},
+effects: {
+  refreshOnReconnect: {
+    deps: ['isReconnecting'],
+    run: (facts) => { if (facts.isReconnecting) refetch(); },
+  },
+}
+```
+
+### Anti-pattern: subscribe twice
+
+Don't subscribe to the same channel inside BOTH an effect and a source. The effect re-runs on fact changes; the source mounts once. You'll get 2× messages with silent duplicates.
+
+```typescript
+// ❌ WRONG
+sources: { channel: { attach: (p) => connect(p) } },
+effects: {
+  reconnect: {
+    deps: ['userId'],
+    run: (f) => { connect(p); },  // ← second subscription!
+  },
+},
+
+// ✓ RIGHT — single source, key the resubscribe by re-registering the module
+sources: { channel: { attach: (p) => connect(p) } },
+// to change the channel, use system.registerModule() with a fresh module
+// whose source attaches with new parameters.
+```
+
+### Anti-pattern: async `attach`
+
+```typescript
+// ❌ WRONG — attach is sync. A returned Promise is discarded; the engine
+// has no cleanup function and any await result is unreachable.
+sources: {
+  bad: {
+    attach: async (publish) => {
+      const token = await getAuthToken();
+      const ch = subscribe(token, publish);
+      return () => ch.unsubscribe(); // ← never registered as cleanup
+    },
+  },
+},
+
+// ✓ RIGHT — do async work inside the subscription's own internals.
+sources: {
+  good: {
+    attach: (publish) => {
+      const ch = subscribe(publish); // sync subscribe stub
+      // The subscribe impl can await internally and start publishing once ready.
+      // The cleanup function is registered immediately.
+      return () => ch.unsubscribe();
+    },
+  },
+},
+```
+
+### Anti-pattern: forget the cleanup function
+
+```typescript
+// ❌ WRONG — returns undefined. The engine logs an error + skips the source.
+sources: {
+  bad: {
+    attach: (publish) => {
+      setInterval(() => publish('TICK'), 1000);
+      // ← missing return!
+    },
+  },
+},
+
+// ✓ RIGHT — always return a function, even if there's nothing to clean up.
+sources: {
+  good: {
+    attach: (publish) => {
+      const id = setInterval(() => publish('TICK'), 1000);
+      return () => clearInterval(id);
+    },
+  },
+  // Or if the source genuinely has no teardown:
+  fireAndForget: {
+    attach: (publish) => {
+      publish('READY');
+      return () => undefined;
+    },
+  },
+}
+```
+
+## Related
+
+- `core-patterns.md` — where sources sit in the constraint-driven module model (decision tree).
+- `multi-module.md` — declaring sources on multiple modules; collision rules.
+- `system-api.md` — `system.start()` / `system.stop()` / `system.inspect()` / `system.observe()`.
+- `anti-patterns.md` (#20) — "subscribe inside an effect / useEffect" anti-pattern; prefer sources.
+- `naming.md` — canonical-term entry for `sources` + cross-paradigm aliases (RxJS Observable, DOM EventTarget, XState callback actor, Supabase realtime).
+- [`../ai/ai-sources.md`](../ai/ai-sources.md) — AI integration: `runStream({ liveContext })`, MCP lifecycle as a source, the `@directive-run/sources/*` adapter subpaths.
+- [`../ai/ai-security.md`](../ai/ai-security.md#sources--pii--closing-the-fact-injection-bypass) — `createFactPIIGuardrail`: closes the source → fact → agent-prompt PII bypass. Wire whenever sources publish into facts the agent reads.

package/core/system-api.md

@@ -182,6 +182,34 @@ inspection.derivations; // [{ id: "doubled", meta: { ... } }]
 inspection.modules;     // [{ id: "auth", meta: { ... } }]
 inspection.events;      // [{ name: "increment", meta: { ... } }]
 
+// Sources with per-source telemetry. Operators read these to answer
+// "is this source publishing?" / "did it error?" / "is the engine
+// silently dropping its publishes?" without registering a custom
+// plugin. Counters reset at every system.start() cycle.
+inspection.sources;
+// [{
+//   id: "supabaseRealtime",
+//   moduleId: "messages",
+//   attached: true,
+//   attachedAt: 1709000000,
+//   detachedAt: null,
+//   publishCount: 47,
+//   lastPublishAt: 1709000123,
+//   // dropCount counts publishes the engine's dispatch guard rejected
+//   // (post-stop, BLOCKED_PROPS event name, empty / non-string name).
+//   dropCount: 0,
+//   lastDropReason: null,        // | "post-destroy" | "post-stop"
+//                                 // | "blocked-event-name"
+//                                 // | "invalid-event-name"
+//   lastDropAt: null,
+//   errorCount: 0,
+//   lastError: null,             // { phase, message (truncated), at } | null
+//   meta: { label: "Supabase channel" },
+// }]
+
+// Aggregate — number of sources currently attached (== count of `attached: true` rows).
+inspection.attachedSourceCount;  // 3
+
 // Unmet requirements (no matching resolver)
 inspection.unmet;
 
@@ -242,8 +270,10 @@ const unsub = system.observe((event: ObservationEvent) => {
   if (event.type === "fact.change") console.log(event.key, event.prev, "→", event.next);
 });
 
-// 18 event types: fact.change, constraint.evaluate/error, requirement.created/met/canceled,
-// resolver.start/complete/error, effect.run/error, derivation.compute,
+// 23 event types: fact.change, constraint.evaluate/error,
+// requirement.created/met/canceled, resolver.start/complete/error/write.rejected,
+// effect.run/error, derivation.compute,
+// source.attach/publish/detach/error,
 // reconcile.start/end, system.init/start/stop/destroy
 
 unsub(); // Stop observing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/knowledge",
-  "version": "1.17.2",
+  "version": "1.19.0",
   "description": "Knowledge files, examples, and validation for Directive — the constraint-driven TypeScript runtime.",
   "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
@@ -53,8 +53,8 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0",
-    "@directive-run/core": "1.17.2",
-    "@directive-run/ai": "1.17.2"
+    "@directive-run/core": "1.19.0",
+    "@directive-run/ai": "1.19.0"
   },
   "scripts": {
     "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/generate-sitemap.ts && tsx scripts/extract-examples.ts && tsup",

package/sitemap.md

@@ -29,6 +29,7 @@ Website: https://directive.run
 - [Constraints](https://directive.run/docs/constraints)
 - [Resolvers](https://directive.run/docs/resolvers)
 - [Effects](https://directive.run/docs/effects)
+- [Sources](https://directive.run/docs/sources)
 - [Events](https://directive.run/docs/events)
 - [Schema & Types](https://directive.run/docs/schema-overview)
 - [API Reference](https://directive.run/docs/api/core)