@directive-run/claude-plugin 1.19.3 → 1.19.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/claude-plugin",
-  "version": "1.19.3",
+  "version": "1.19.4",
   "description": "Claude Code plugin for Directive — 12 skills covering modules, constraints, resolvers, derivations, AI orchestration, and adapters. Installable via Claude Code's plugin marketplace or consumable programmatically as an npm package.",
   "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
@@ -52,7 +52,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0",
-    "@directive-run/knowledge": "1.19.3"
+    "@directive-run/knowledge": "1.19.4"
   },
   "scripts": {
     "build": "tsx scripts/build-skills.ts && tsup",

package/skills/building-ai-agents/ai-sources.md

@@ -82,6 +82,30 @@ above), not a source. Wire it inside the orchestrator's constructor.
 
 ---
 
+## What other agent frameworks have (and don't)
+
+The closest comparable surfaces today, and what they cover:
+
+| Capability | Directive `runStream({ liveContext })` | LangChain / LangGraph | Vercel AI SDK | LlamaIndex |
+|---|---|---|---|---|
+| **Mid-generation fact updates from an external stream** | ✅ source primitive bridges the transport; `liveContext` watches fact keys; predicate decides interrupt vs. notify | partial — `Tool` callbacks can be invoked but no "fact store the LLM sees through" surface | partial — `streamText` exposes `onChunk` for the consumer but no mid-stream re-prompt | partial — `QueryEngine` re-runs are caller-driven |
+| **Declarative source / inbound subscription** | ✅ `source` primitive — engine owns mount/unmount; lifecycle observable | hand-rolled per integration (LangChain runnables don't own subscriptions) | n/a — Vercel AI is a streaming SDK, not a state engine | n/a — LlamaIndex is a retrieval framework |
+| **Interrupt + resume against the same subscription** | ✅ `result.interrupt(reason?)` keeps the fact subscription alive; caller re-prompts | callback orchestration on the consumer | abort signal only — no "resume against the same context" affordance | re-query each time |
+| **Tier 0 PII guard at the publish→fact boundary** | ✅ `createFactPIIGuardrail` — wired at `createSystem`; runs on every fact write | callback pattern; consumer wires per chain | input/output guardrails on the call; nothing at the fact-store / state-update boundary | Pydantic schema validation at the retrieval boundary |
+| **Source × OTel out of the box** | ✅ `attachSourcesToOtel` — one long-lived span per `(sourceId, moduleId)` | manual `with_config(callbacks=...)` plumbing | consumer wires `onChunk` into their tracer | manual |
+| **Multi-system reactive composition** | ✅ `liveContext.system` accepts ANY Directive system, even one not owned by the orchestrator | n/a — single-graph model | n/a | n/a |
+
+Directive's pitch is not "we're a better LangChain" — it's **"your
+state engine and your agent runtime share one fact store, so the agent
+sees the world change without you wiring callbacks."** The shipped
+1.x surface delivers that for inbound sources + abort-and-emit
+interruption; the queued follow-up RFC adds automatic re-prompt with
+merge strategies. See
+[RFC 0005's "Demo" section](../../docs/rfcs/0005-live-context-agent.md#demo-the-launch-video)
+for the 6-second launch GIF concept.
+
+---
+
 ## `runStream({ liveContext })` — Reactive Agents
 
 > The killer demo: the agent is mid-generation, a source publishes a fact

package/skills/getting-started-with-directive/choosing-primitives.md

@@ -0,0 +1,163 @@
+# Choosing the right primitive
+
+Directive ships six core primitives. Picking the wrong one — modeling
+business state as a derivation, or running a side effect inside a
+resolver — is the most common source of "Directive feels heavy"
+complaints. The framework rewards getting this right; this page is the
+decision matrix.
+
+## The six primitives
+
+| Primitive | Purpose | Reads | Writes | Triggers when |
+|---|---|---|---|---|
+| **`facts`** | Owned, mutable state | n/a | event handlers, `init`, resolvers, plugin pre-emit | the consumer writes to it |
+| **`derivations`** | Pure, cached read-only views of facts | facts + other derivations | nothing | watched dependency changes |
+| **`events`** | Typed mutation entry points | facts (via `f`) | facts (via `f`) | `system.events.name(payload)` or a source `publish` |
+| **`constraints`** | Declarative "when X, require Y" rules | facts + derivations | NOTHING (emits requirements) | watched dependency changes |
+| **`resolvers`** | Async work that fulfills a constraint's requirement | facts + derivations + `req.payload` | facts (via the resolver's `ctx.set`) | matched requirement enters the inflight queue |
+| **`effects`** | Side effects that fire on fact change | facts + derivations | nothing inside Directive (writes to the outside world) | watched dependency changes |
+| **`sources`** | External event streams mounted by the runtime | nothing | facts (via `publish` → event handler) | the external transport calls `publish(...)` |
+
+## Decision tree
+
+```
+Does this thing belong to my system's state?
+├── No  → it's external. Inbound or outbound?
+│        ├── Inbound (something happens out there, I want to react)
+│        │   ├── Once per ingest event (channel.on, addEventListener,
+│        │   │   setInterval poll, MCP notification) → `source`
+│        │   └── Continuous LLM token stream → AsyncIterable / runStream;
+│        │       NOT a source (the source owns the connection; the
+│        │       iterable owns the per-generation token sequence)
+│        └── Outbound (state changed, I want to tell the world)
+│            ├── Async work I want to retry / cancel / dedupe →
+│            │   `resolver` (paired with a `constraint`)
+│            └── Fire-and-forget side effect (log, ping, animate) →
+│                `effect`
+└── Yes → does it change over time?
+         ├── Yes  → `fact` (declare in `schema.facts`, mutate via
+         │         `events:` handlers and resolver `ctx.set`)
+         └── No  → it's computed from other facts → `derivation`
+                  (declare in `schema.derivations`, compute in `derive:`)
+
+Then: does anything need to RUN when this changes?
+├── A rule must trigger and require async work → `constraint`
+│   (declarative `when`; emits a requirement; a `resolver` fulfills it)
+├── A side effect that just runs → `effect`
+└── Nothing — the LLM / hook / view just reads it next time → done
+```
+
+## Side-by-side comparisons
+
+### `effect` vs `source`
+
+The most common confusion. Both wrap something that fires "when
+something changes."
+
+| | `effect` | `source` |
+|---|---|---|
+| Direction | **Outbound** — your state changes, code runs | **Inbound** — the world changes, your state updates |
+| Trigger | watched facts / derivations change | external transport calls `publish` |
+| Body | imperative side effect | call `publish(eventName, payload)` |
+| Lifecycle | per fact change | mount-once at `start`, detach at `stop` |
+| Owner | tied to a fact/derivation watcher | owns its external transport (channel, socket, listener) |
+| Replaces | hand-rolled `useEffect(() => { /* writes elsewhere */ }, [factA])` | hand-rolled `useEffect(() => { subscribe(); return unsub; }, [])` |
+
+If the `useEffect` body is `subscribe + return unsubscribe`, declare a
+source. If the `useEffect` body is `do something external because some
+fact changed`, declare an effect.
+
+### `derivation` vs `resolver` vs `effect`
+
+All three "react to fact changes." Pick by what they OWN:
+
+| | `derivation` | `resolver` | `effect` |
+|---|---|---|---|
+| Owns a **value** | YES (the computed result) | NO | NO |
+| Owns a **promise** | NO | YES (retries, cancels, dedupes) | NO (fire-and-forget) |
+| Owns a **side effect** | NO (pure) | NO (writes facts via `ctx.set`) | YES |
+| Reruns on input change | always (cached) | NEVER automatically — only when the constraint emits a new requirement | always |
+| Can be `await`-ed externally | n/a (read synchronously) | YES (constraints + `system.settle()`) | NO |
+| Wrong-choice symptom | "I want a fact but it's always derived" → fact; "I want side effects" → effect | "I want this to retry but it doesn't" → likely should be an effect; "I want this to run every render" → likely should be a derivation | "I want to write a fact based on the change" → likely should be a resolver |
+
+### `event` vs `resolver`
+
+Both can write facts. Pick by who calls them:
+
+| | `event` | `resolver` |
+|---|---|---|
+| Caller | external code (`system.events.name(payload)`) OR a source's `publish` | the engine, when a constraint emits a matching requirement |
+| Body | synchronous mutation via `f` accessor | async, can retry, can await |
+| Best for | user actions, source-driven mutations, deterministic state transitions | async work whose result is a fact update |
+
+A typical pattern: `event` ingests raw data, `derivation` computes a
+"needs sync?" flag, `constraint` triggers when the flag is true,
+`resolver` does the async work, on success writes the result back via
+another `event`. The same fact pipeline doesn't mix `events` and
+`resolvers` for the SAME write — events are user/source-driven; resolvers
+are engine-driven.
+
+### `constraint` vs `derivation` (predicates)
+
+Both can hold `when` predicates. Different jobs:
+
+- **`derivation`** evaluates an expression against the current facts
+  and returns a value. It's a noun. Other constraints / effects can
+  watch it.
+- **`constraint`** evaluates a `when` predicate and, when it matches,
+  emits a `requirement` object that a resolver pattern-matches and
+  fulfills. It's a verb. Constraints never write — they describe what
+  the world MUST do.
+
+The constraint's `when` may reference a derivation; that's the canonical
+pattern (compute the condition cheaply once; multiple constraints share
+it).
+
+## Worked example
+
+You're building a chat app that mirrors a Supabase realtime channel,
+calls a moderation API on each message, and displays the result.
+
+| Layer | Primitive | Why |
+|---|---|---|
+| `messages: t.array<Message>()` | `fact` | mutable list owned by this module |
+| `unmoderated: t.array<Id>()` | `derivation` | filtered view of `messages` where `verdict === null` |
+| `realtime` (the broker subscription) | `source` | mount-once external event stream → `publish('MESSAGE_RECEIVED', row)` |
+| `MESSAGE_RECEIVED` handler | `event` | source-driven mutation; writes the row into `messages` |
+| `moderateUnverified` | `constraint` + `resolver` | constraint emits `MODERATE` requirements for each `unmoderated` id; resolver calls the moderation API + writes `MODERATION_COMPLETE` |
+| `MODERATION_COMPLETE` handler | `event` | engine-driven mutation; sets `verdict` on the message |
+| `announceFlag` | `effect` | watches `unmoderated`, posts to #alerts when count crosses a threshold |
+| `mcpHealthCheck` | `source` | the moderation API has a status SSE; mount once, publish health changes |
+
+Every external touch is a `source` or a `resolver`. Every state field
+is a `fact` or a `derivation`. Every "must-happen rule" is a
+`constraint`. Every "do this when X" is an `effect`. Six primitives,
+seven pieces of work, zero `useEffect` hooks.
+
+## When you find yourself wanting to break the model
+
+- "I want to call `set` from inside a derivation" — you wanted a
+  resolver (the work has a result that's a fact update).
+- "I want my effect to retry" — you wanted a resolver (resolvers
+  have retry config; effects don't).
+- "I want my source to write multiple facts at once" — declare an
+  event whose handler does the batch write; the source publishes the
+  event with the batch payload.
+- "I want to write a fact from a constraint" — you wanted a
+  resolver. Constraints declare; resolvers do.
+- "I have a value that's derived from outside state (URL, env, time)"
+  — declare it as a `fact` whose `init` reads the external value,
+  and use a `source` if it changes (e.g. `popstate` listener).
+
+## Related
+
+- [`core-patterns.md`](./core-patterns.md) — module composition and
+  the recommended structure of a module file.
+- [`sources.md`](./sources.md) — the source primitive's full lifecycle
+  and recipes.
+- [`constraints.md`](./constraints.md) — `when` predicates, requirement
+  shapes, and the `bind` / `owns` field-scoped CAS contract.
+- [`resolvers.md`](./resolvers.md) — retry config, batch semantics, and
+  the `ctx.set` write contract.
+- [`anti-patterns.md`](./anti-patterns.md) — the things to avoid that
+  every Directive consumer eventually tries.