@directive-run/knowledge 1.1.1 → 1.3.0

package/core/react-adapter.md

@@ -182,6 +182,38 @@ const count = useSelector(system, (s) => s.facts.count);
 const events = useEvent(system);
 ```
 
+## createDirectiveContext
+
+Eliminates prop-drilling by providing the system via React context:
+
+```typescript
+import { createDirectiveContext } from "@directive-run/react";
+
+const Counter = createDirectiveContext(counterSystem);
+
+function App() {
+  return (
+    <Counter.Provider>
+      <Display />
+    </Counter.Provider>
+  );
+}
+
+function Display() {
+  const count = Counter.useFact("count");       // No system arg needed
+  const doubled = Counter.useDerived("doubled");
+  const events = Counter.useEvents();
+  return <button onClick={() => events.increment()}>{count}</button>;
+}
+```
+
+Returns: `{ Provider, useSystem, useFact, useDerived, useEvents, useDispatch, useSelector, useWatch, useInspect, useExplain, useHistory }`.
+
+Provider accepts `system` prop override for testing:
+```tsx
+<Counter.Provider system={testSystem}><ComponentUnderTest /></Counter.Provider>
+```
+
 ## Common Mistakes
 
 ### Creating the system inside a component without useSystem

package/core/system-api.md

@@ -150,29 +150,35 @@ const total = system.read("cart.totalPrice");
 ```typescript
 const inspection = system.inspect();
 
-// Full fact snapshot
-inspection.facts;
-// { count: 5, phase: "done", user: { id: "1", name: "Alice" } }
+// Unmet requirements
+inspection.unmet;
+// [{ id: "req-1", requirement: { type: "FETCH_USER" }, fromConstraint: "needsUser" }]
 
-// Derivation values
-inspection.derivations;
-// { isLoading: false, displayName: "Alice" }
+// Inflight resolvers
+inspection.inflight;
+// [{ id: "req-2", resolverId: "fetchData", startedAt: 1709000000 }]
 
-// Active requirements
-inspection.requirements;
-// [{ id: "req-1", type: "FETCH_USER", userId: "1" }]
+// Facts with meta
+inspection.facts;
+// [{ key: "userId", meta: { label: "User ID" } }, { key: "count" }]
 
-// Constraint definitions and state
-inspection.constraintDefs;
-// [{ id: "fetchWhenAuth", priority: 0, disabled: false }]
+// Constraints with state + meta
+inspection.constraints;
+// [{ id: "needsUser", active: true, disabled: false, priority: 0, hitCount: 3, meta: { label: "..." } }]
 
-// Resolver statuses
+// Resolver definitions + meta
+inspection.resolverDefs;
+// [{ id: "fetchUser", requirement: "FETCH_USER", meta: { label: "..." } }]
+
+// Resolver statuses (inflight only)
 inspection.resolvers;
-// { fetchUser: { state: "success", duration: 150 } }
+// { "req-1": { state: "running" } }
 
-// Currently inflight resolvers
-inspection.inflight;
-// [{ id: "req-2", resolverId: "fetchData", startedAt: 1709000000 }]
+// Effects, derivations, modules — all with optional meta
+inspection.effects;     // [{ id: "log", meta: { ... } }]
+inspection.derivations; // [{ id: "doubled", meta: { ... } }]
+inspection.modules;     // [{ id: "auth", meta: { ... } }]
+inspection.events;      // [{ name: "increment", meta: { ... } }]
 
 // Unmet requirements (no matching resolver)
 inspection.unmet;
@@ -221,6 +227,28 @@ system.meta.byTag("pii");        // MetaMatch[] — all PII-tagged fields
 
 Meta is frozen at registration (Object.create(null) + Object.freeze). Zero hot-path cost. See [Definition Meta docs](https://directive.run/docs/advanced/meta).
 
+## Observation Protocol
+
+Typed event stream for all lifecycle events — enables browser extensions, third-party tools, and test assertions:
+
+```typescript
+import type { ObservationEvent } from "@directive-run/core";
+
+const unsub = system.observe((event: ObservationEvent) => {
+  if (event.type === "constraint.evaluate") console.log(event.id, event.active);
+  if (event.type === "resolver.complete") console.log(event.resolver, event.duration);
+  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,
+// reconcile.start/end, system.init/start/stop/destroy
+
+unsub(); // Stop observing
+```
+
+Zero overhead when no observers. Implemented as an internal plugin.
+
 ## Lifecycle
 
 ```typescript

package/core/testing.md

@@ -215,6 +215,47 @@ it("processes intermediate state", async () => {
 });
 ```
 
+## Coverage Tracking
+
+Track which constraints, resolvers, effects, and derivations are exercised:
+
+```typescript
+import { createCoverageTracker } from "@directive-run/core/testing";
+
+const { run, report } = createCoverageTracker(system);
+
+await run(async () => {
+  system.facts.userId = 123;
+  await system.settle();
+});
+
+const coverage = report();
+// coverage.constraintCoverage — 0-1 (percentage hit)
+// coverage.resolverCoverage — 0-1
+// coverage.effectCoverage — 0-1
+// coverage.derivationCoverage — 0-1
+// coverage.constraintsMissed — Set<string> of IDs never triggered
+```
+
+## Test Observer
+
+Collect observation events for assertion-based testing:
+
+```typescript
+import { createTestObserver } from "@directive-run/core/testing";
+
+const observer = createTestObserver(system);
+
+system.facts.count = 5;
+await system.settle();
+
+const evals = observer.ofType("constraint.evaluate");
+expect(evals).toHaveLength(1);
+
+observer.clear();   // Reset
+observer.dispose();  // Stop observing
+```
+
 ## Common Mistakes
 
 ### Testing real resolvers instead of mocking

package/package.json

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