@directive-run/knowledge 1.4.0 → 1.5.0

package/examples/ai-guardrails.ts

@@ -12,6 +12,7 @@
 import {
   type InjectionDetectionResult,
   type PIIDetectionResult,
+  detectAndRedactPII,
   detectPII,
   detectPromptInjection,
 } from "@directive-run/ai";
@@ -169,7 +170,84 @@ export const system = createSystem({
 // Analysis Functions
 // ============================================================================
 
-export function analyzeMessage(text: string): ChatMessage {
+/**
+ * Compliance gate: blocks the message when the active mode forbids the kinds
+ * of PII detected. Emits its own devtools event and returns whether it blocked.
+ */
+function runComplianceCheck(
+  piiResult: PIIDetectionResult,
+  textLength: number,
+): boolean {
+  const mode = system.facts.complianceMode as ComplianceMode;
+  let blocked = false;
+
+  if (mode !== "standard" && piiResult.detected) {
+    // HIPAA Safe Harbor (45 CFR 164.514) enumerates 18 identifier classes —
+    // names, geographic data, dates, contact info, account/certificate/license
+    // numbers, IP addresses, and more. That is effectively every PII type this
+    // detector emits, so under HIPAA *any* detected PII is PHI and blocks.
+    const hasPHI = piiResult.detected;
+    const hasContactInfo = piiResult.items.some(
+      (i) =>
+        i.type === "email" ||
+        i.type === "phone" ||
+        i.type === "name" ||
+        i.type === "date_of_birth" ||
+        i.type === "address",
+    );
+
+    if (mode === "hipaa" && hasPHI) {
+      blocked = true;
+      system.facts.complianceBlocks =
+        (system.facts.complianceBlocks as number) + 1;
+      addTimeline("compliance", "HIPAA: PHI detected", "compliance");
+    }
+
+    if (mode === "gdpr" && hasContactInfo) {
+      blocked = true;
+      system.facts.complianceBlocks =
+        (system.facts.complianceBlocks as number) + 1;
+      addTimeline("compliance", "GDPR: personal data detected", "compliance");
+    }
+  }
+
+  emitDevToolsEvent({
+    type: "guardrail_check",
+    guardrailName: `compliance-${mode}`,
+    guardrailType: "input",
+    passed: !blocked || !piiResult.detected,
+    inputLength: textLength,
+  });
+
+  return blocked;
+}
+
+/**
+ * When redaction is on, never persist raw PII into reactive facts: strip the
+ * plaintext `value` from each detected item before it reaches facts.
+ */
+function toSafePiiResult(
+  piiResult: PIIDetectionResult,
+  redactionEnabled: boolean,
+): PIIDetectionResult | null {
+  if (!piiResult.detected) {
+    return null;
+  }
+
+  if (!redactionEnabled) {
+    return piiResult;
+  }
+
+  return {
+    ...piiResult,
+    items: piiResult.items.map((item) => ({
+      ...item,
+      value: "[redacted]",
+    })),
+  };
+}
+
+export async function analyzeMessage(text: string): Promise<ChatMessage> {
   const id = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
   let blocked = false;
 
@@ -192,11 +270,12 @@ export function analyzeMessage(text: string): ChatMessage {
     inputLength: text.length,
   });
 
-  // 2. PII detection
-  const piiResult = detectPII(text, {
-    redact: system.facts.redactionEnabled as boolean,
-    redactionStyle: "typed",
-  });
+  // 2. PII detection. detectPII is detection-only; detectAndRedactPII also
+  // populates `redactedText` so we never have to mutate a returned result.
+  const redactionEnabled = system.facts.redactionEnabled;
+  const piiResult = redactionEnabled
+    ? await detectAndRedactPII(text, { style: "typed" })
+    : await detectPII(text);
   if (piiResult.detected) {
     system.facts.piiDetections = (system.facts.piiDetections as number) + 1;
     for (const item of piiResult.items) {
@@ -213,41 +292,10 @@ export function analyzeMessage(text: string): ChatMessage {
   });
 
   // 3. Compliance check
-  const mode = system.facts.complianceMode as ComplianceMode;
-  if (mode !== "standard" && piiResult.detected) {
-    const hasPHI = piiResult.items.some(
-      (i) =>
-        i.type === "medical_id" ||
-        i.type === "ssn" ||
-        i.type === "date_of_birth",
-    );
-    const hasContactInfo = piiResult.items.some(
-      (i) => i.type === "email" || i.type === "phone" || i.type === "name",
-    );
-
-    if (mode === "hipaa" && hasPHI) {
-      blocked = true;
-      system.facts.complianceBlocks =
-        (system.facts.complianceBlocks as number) + 1;
-      addTimeline("compliance", "HIPAA: PHI detected", "compliance");
-    }
-
-    if (mode === "gdpr" && hasContactInfo) {
-      blocked = true;
-      system.facts.complianceBlocks =
-        (system.facts.complianceBlocks as number) + 1;
-      addTimeline("compliance", "GDPR: personal data detected", "compliance");
-    }
+  if (runComplianceCheck(piiResult, text.length)) {
+    blocked = true;
   }
 
-  emitDevToolsEvent({
-    type: "guardrail_check",
-    guardrailName: `compliance-${mode}`,
-    guardrailType: "input",
-    passed: !blocked || !piiResult.detected,
-    inputLength: text.length,
-  });
-
   if (blocked) {
     system.facts.blockedCount = (system.facts.blockedCount as number) + 1;
   }
@@ -260,10 +308,10 @@ export function analyzeMessage(text: string): ChatMessage {
 
   return {
     id,
-    text,
+    text: redactionEnabled ? redactedText : text,
     blocked,
     redactedText,
     injectionResult: injectionResult.detected ? injectionResult : null,
-    piiResult: piiResult.detected ? piiResult : null,
+    piiResult: toSafePiiResult(piiResult, redactionEnabled),
   };
 }

package/examples/checkers.ts

@@ -48,8 +48,8 @@ import {
 } from "@directive-run/core/plugins";
 // createObservability is alpha (not in bundle) — direct source import
 import {
-  createObservability,
   createAgentMetrics,
+  createObservability,
 } from "../../../packages/core/src/plugins/observability.lab.js";
 import {
   analysisAgent,

package/examples/counter-react.ts

@@ -6,7 +6,12 @@
  * Shared counter module — same file used by all framework examples.
  */
 
-import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
 
 const schema = {
   facts: { count: t.number() },
@@ -17,15 +22,23 @@ const schema = {
 
 export const counterModule = createModule("counter", {
   schema,
-  init: (facts) => { facts.count = 0; },
+  init: (facts) => {
+    facts.count = 0;
+  },
   derive: {
     doubled: (facts) => facts.count * 2,
     isPositive: (facts) => facts.count > 0,
   },
   events: {
-    increment: (facts) => { facts.count += 1; },
-    decrement: (facts) => { facts.count -= 1; },
-    reset: (facts) => { facts.count = 0; },
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    decrement: (facts) => {
+      facts.count -= 1;
+    },
+    reset: (facts) => {
+      facts.count = 0;
+    },
   },
   constraints: {
     noNegative: {
@@ -36,7 +49,9 @@ export const counterModule = createModule("counter", {
   resolvers: {
     clamp: {
       requirement: "CLAMP_TO_ZERO",
-      resolve: async (req, context) => { context.facts.count = 0; },
+      resolve: async (req, context) => {
+        context.facts.count = 0;
+      },
     },
   },
 });

package/examples/counter-svelte.ts

@@ -6,7 +6,12 @@
  * Shared counter module — same file used by all framework examples.
  */
 
-import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
 
 const schema = {
   facts: { count: t.number() },
@@ -17,15 +22,23 @@ const schema = {
 
 export const counterModule = createModule("counter", {
   schema,
-  init: (facts) => { facts.count = 0; },
+  init: (facts) => {
+    facts.count = 0;
+  },
   derive: {
     doubled: (facts) => facts.count * 2,
     isPositive: (facts) => facts.count > 0,
   },
   events: {
-    increment: (facts) => { facts.count += 1; },
-    decrement: (facts) => { facts.count -= 1; },
-    reset: (facts) => { facts.count = 0; },
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    decrement: (facts) => {
+      facts.count -= 1;
+    },
+    reset: (facts) => {
+      facts.count = 0;
+    },
   },
   constraints: {
     noNegative: {
@@ -36,7 +49,9 @@ export const counterModule = createModule("counter", {
   resolvers: {
     clamp: {
       requirement: "CLAMP_TO_ZERO",
-      resolve: async (req, context) => { context.facts.count = 0; },
+      resolve: async (req, context) => {
+        context.facts.count = 0;
+      },
     },
   },
 });

package/examples/counter-vue.ts

@@ -6,7 +6,12 @@
  * Shared counter module — same file used by all framework examples.
  */
 
-import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
 
 const schema = {
   facts: { count: t.number() },
@@ -17,15 +22,23 @@ const schema = {
 
 export const counterModule = createModule("counter", {
   schema,
-  init: (facts) => { facts.count = 0; },
+  init: (facts) => {
+    facts.count = 0;
+  },
   derive: {
     doubled: (facts) => facts.count * 2,
     isPositive: (facts) => facts.count > 0,
   },
   events: {
-    increment: (facts) => { facts.count += 1; },
-    decrement: (facts) => { facts.count -= 1; },
-    reset: (facts) => { facts.count = 0; },
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    decrement: (facts) => {
+      facts.count -= 1;
+    },
+    reset: (facts) => {
+      facts.count = 0;
+    },
   },
   constraints: {
     noNegative: {
@@ -36,7 +49,9 @@ export const counterModule = createModule("counter", {
   resolvers: {
     clamp: {
       requirement: "CLAMP_TO_ZERO",
-      resolve: async (req, context) => { context.facts.count = 0; },
+      resolve: async (req, context) => {
+        context.facts.count = 0;
+      },
     },
   },
 });

package/examples/counter.ts

@@ -9,7 +9,12 @@
  * Total: ~40 lines.
  */
 
-import { createModule, createSystem, t, type ModuleSchema } from "@directive-run/core";
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
 
 const schema = {
   facts: {
@@ -42,9 +47,15 @@ export const counterModule = createModule("counter", {
   },
 
   events: {
-    increment: (facts) => { facts.count += 1; },
-    decrement: (facts) => { facts.count -= 1; },
-    reset: (facts) => { facts.count = 0; },
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    decrement: (facts) => {
+      facts.count -= 1;
+    },
+    reset: (facts) => {
+      facts.count = 0;
+    },
   },
 
   // When count goes negative, automatically fix it

package/examples/data-triggers.ts

@@ -0,0 +1,175 @@
+// Example: data-triggers
+// Source: examples/data-triggers/src/index.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * All five Directive definition surfaces written as DATA.
+ *
+ * Run with: `pnpm --filter @directive-run/example-data-triggers start`
+ *
+ * Demonstrates:
+ *   - constraint `when: { ... }`
+ *   - effect    `on:   { ... }`
+ *   - resolver  `key:  [ ... ]`
+ *   - event     `patch: { $set: { ... } }`
+ *   - derive    `compute: { ... }` (predicate + template)
+ *
+ * And the introspection that only a data form makes possible:
+ *   - `system.inspect().constraints[].whenSpec`
+ *   - `constraint.evaluate` observer event with `whenExplain`
+ *   - `system.explain()` rendering a clause-by-clause ✓/✗ tree.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+
+// ----------------------------------------------------------------------------
+// Module
+// ----------------------------------------------------------------------------
+
+const schema = {
+  facts: {
+    phase: t.string<"red" | "yellow" | "green">(),
+    elapsed: t.number(),
+    transitionCount: t.number(),
+    label: t.string(),
+    firstName: t.string(),
+    lastName: t.string(),
+    age: t.number(),
+  },
+  derivations: {
+    isAdult: t.boolean(),
+    fullName: t.string(),
+  },
+  events: {
+    advanceTo: { value: t.string(), userName: t.string() },
+  },
+  requirements: {
+    TRANSITION: { to: t.string<"red" | "yellow" | "green">() },
+  },
+} satisfies ModuleSchema;
+
+const trafficLight = createModule("traffic", {
+  schema,
+
+  init: (facts) => {
+    facts.phase = "red";
+    facts.elapsed = 0;
+    facts.transitionCount = 0;
+    facts.label = "";
+    facts.firstName = "Grace";
+    facts.lastName = "Hopper";
+    facts.age = 30;
+  },
+
+  // ── Derivations — predicate + template, no functions ─────────────────────
+  derive: {
+    isAdult: { compute: { age: { $gte: 18 } } },
+    fullName: { compute: { $template: "${firstName} ${lastName}" } },
+  },
+
+  // ── Event — declarative patch instead of a handler ────────────────────────
+  events: {
+    advanceTo: {
+      patch: {
+        $set: {
+          phase: { $ref: "value" },
+          elapsed: 0,
+          label: { $template: "Set by ${userName} → ${value}" },
+        },
+      },
+    },
+  },
+
+  // ── Constraint — data `when`, declarative `require` ──────────────────────
+  constraints: {
+    transition: {
+      when: { phase: "red", elapsed: { $gte: 30 } },
+      require: { type: "TRANSITION", to: "green" },
+    },
+  },
+
+  // ── Resolver — KeySelector array dedups by requirement field ─────────────
+  resolvers: {
+    transition: {
+      requirement: "TRANSITION",
+      key: ["to"],
+      resolve: async (req, ctx) => {
+        ctx.facts.phase = req.to;
+        ctx.facts.elapsed = 0;
+        ctx.facts.transitionCount = ctx.facts.transitionCount + 1;
+      },
+    },
+  },
+});
+
+// ----------------------------------------------------------------------------
+// System + observer
+// ----------------------------------------------------------------------------
+
+const system = createSystem({ module: trafficLight });
+
+system.observe((event) => {
+  if (event.type === "constraint.evaluate" && event.whenExplain) {
+    console.log(
+      `\n[observe] constraint.evaluate ${event.id} → ${event.active}`,
+    );
+    for (const clause of event.whenExplain) {
+      const mark = clause.pass ? "✓" : "✗";
+      console.log(
+        `  ${mark} ${clause.path} ${clause.op} ${JSON.stringify(clause.expected)} (actual: ${JSON.stringify(clause.actual)})`,
+      );
+    }
+  }
+});
+
+system.start();
+
+// ----------------------------------------------------------------------------
+// Run
+// ----------------------------------------------------------------------------
+
+console.log("--- Initial derivations (data forms) ---");
+console.log(`isAdult:  ${system.derive.isAdult}`);
+console.log(`fullName: ${system.derive.fullName}`);
+
+console.log("\n--- inspect().constraints[] surfaces whenSpec ---");
+for (const c of system.inspect().constraints) {
+  console.log(`${c.id}: whenSpec = ${JSON.stringify(c.whenSpec)}`);
+}
+
+// Trip the predicate: elapsed goes from 0 → 30, so the constraint fires.
+console.log("\n--- elapsed → 30 (predicate now holds) ---");
+system.facts.elapsed = 30;
+await settle();
+
+console.log(`phase after resolver: ${system.facts.phase}`);
+console.log(`transitionCount:      ${system.facts.transitionCount}`);
+
+// Show explain() on the next emitted requirement (if any), or on a re-fire.
+// Two writes: phase ← "red" satisfies the first clause; elapsed ← 5 fails the
+// `$gte: 30` clause, so the predicate as a whole is false and the constraint
+// does not fire.
+console.log("\n--- phase = red, elapsed → 5 (predicate fails on elapsed) ---");
+system.facts.phase = "red";
+system.facts.elapsed = 5;
+await settle();
+
+// Dispatch the data-form event — sets multiple facts from the payload.
+console.log("\n--- dispatch advanceTo (patch) ---");
+system.events.advanceTo({ value: "yellow", userName: "Ada" });
+await settle();
+console.log(`phase: ${system.facts.phase}`);
+console.log(`label: ${system.facts.label}`);
+
+system.destroy();
+
+async function settle(): Promise<void> {
+  await new Promise((r) => setTimeout(r, 0));
+  await Promise.resolve();
+  await new Promise((r) => setTimeout(r, 0));
+}

package/examples/sudoku.ts

@@ -110,12 +110,7 @@ export const sudokuSchema = {
 export const sudokuGame = createModule("sudoku", {
   schema: sudokuSchema,
   history: {
-    snapshotEvents: [
-      "inputNumber",
-      "toggleNote",
-      "requestHint",
-      "newGame",
-    ],
+    snapshotEvents: ["inputNumber", "toggleNote", "requestHint", "newGame"],
   },
 
   init: (facts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/knowledge",
-  "version": "1.4.0",
+  "version": "1.5.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.4.0",
-    "@directive-run/ai": "1.4.0"
+    "@directive-run/core": "1.5.0",
+    "@directive-run/ai": "1.5.0"
   },
   "scripts": {
     "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/generate-sitemap.ts && tsx scripts/extract-examples.ts && tsup",