@directive-run/knowledge 0.2.0

package/core/time-travel.md

@@ -0,0 +1,238 @@
+# Time-Travel Debugging
+
+Directive can record every fact change as a snapshot, enabling undo/redo, replay, and state export for bug reports.
+
+## Decision Tree: "Should I enable time-travel?"
+
+```
+What's the use case?
+├── Debugging during development → Yes, enable with maxSnapshots cap
+├── Production app → No, disable for performance
+├── Bug reproduction → Enable, use exportHistory() to share
+├── Testing → Usually no — use assertFact/assertDerivation instead
+└── Demo / presentation → Yes, great for showing state changes
+```
+
+## Enabling Time-Travel
+
+```typescript
+import { createSystem } from "@directive-run/core";
+
+const system = createSystem({
+  module: myModule,
+  debug: {
+    timeTravel: true,       // Enable snapshot recording
+    maxSnapshots: 100,      // Cap memory usage (default: 50)
+  },
+});
+```
+
+Time-travel is disabled by default. Snapshots are recorded automatically on every fact mutation.
+
+## The TimeTravelAPI
+
+Access via `system.debug.timeTravel`:
+
+```typescript
+const tt = system.debug.timeTravel;
+
+// Navigation
+tt.canUndo();           // boolean — is there a previous snapshot?
+tt.canRedo();           // boolean — is there a next snapshot?
+tt.undo();              // Restore previous snapshot
+tt.redo();              // Restore next snapshot
+
+// Direct access
+tt.getSnapshots();      // Array of all snapshots
+tt.goToSnapshot(index); // Jump to a specific snapshot by index
+
+// Each snapshot contains:
+// {
+//   facts: { ... },        — full fact state at that point
+//   timestamp: number,     — when the snapshot was taken
+//   label?: string,        — optional label from changeset
+//   changedKeys: string[], — which facts changed
+// }
+```
+
+## Undo/Redo Pattern
+
+```typescript
+const system = createSystem({
+  module: editorModule,
+  debug: { timeTravel: true, maxSnapshots: 200 },
+});
+
+system.start();
+
+// User makes changes
+system.facts.text = "Hello";
+system.facts.text = "Hello, world";
+system.facts.text = "Hello, world!";
+
+// Undo last change
+const tt = system.debug.timeTravel;
+tt.undo();
+console.log(system.facts.text); // "Hello, world"
+
+tt.undo();
+console.log(system.facts.text); // "Hello"
+
+// Redo
+tt.redo();
+console.log(system.facts.text); // "Hello, world"
+
+// Check navigation state
+tt.canUndo(); // true
+tt.canRedo(); // true
+```
+
+## Changesets: Grouping Related Changes
+
+Multiple fact mutations can be grouped into a single undoable unit.
+
+```typescript
+const tt = system.debug.timeTravel;
+
+// Without changeset — each mutation is a separate snapshot
+system.facts.firstName = "Alice";
+system.facts.lastName = "Smith";
+// Two snapshots, two undos needed
+
+// With changeset — grouped into one snapshot
+tt.beginChangeset("Update user name");
+system.facts.firstName = "Alice";
+system.facts.lastName = "Smith";
+tt.endChangeset();
+// One snapshot, one undo restores both
+
+// Undo reverts the entire changeset
+tt.undo();
+// Both firstName and lastName are restored
+```
+
+Use changesets for logically related mutations: form submissions, multi-field updates, resolver results.
+
+## Exporting and Importing History
+
+Serialize the full snapshot history for bug reports or debugging.
+
+```typescript
+const tt = system.debug.timeTravel;
+
+// Export — returns a serializable object
+const historyData = tt.exportHistory();
+// Send to server, save to file, attach to bug report
+console.log(JSON.stringify(historyData));
+
+// Import — restore history from exported data
+tt.importHistory(historyData);
+
+// Now you can step through the user's exact state sequence
+tt.goToSnapshot(0); // Start
+tt.goToSnapshot(5); // When the bug occurred
+```
+
+## Snapshot Inspection
+
+```typescript
+const tt = system.debug.timeTravel;
+const snapshots = tt.getSnapshots();
+
+// Walk through all snapshots
+for (const snap of snapshots) {
+  console.log(`[${new Date(snap.timestamp).toISOString()}]`);
+  console.log(`  Changed: ${snap.changedKeys.join(", ")}`);
+  if (snap.label) {
+    console.log(`  Label: ${snap.label}`);
+  }
+  console.log(`  Facts:`, snap.facts);
+}
+
+// Jump to a specific point
+tt.goToSnapshot(3);
+console.log(system.facts); // State as of snapshot 3
+```
+
+## Performance: maxSnapshots
+
+Every fact mutation creates a snapshot. Cap the number to control memory:
+
+```typescript
+// Low memory — keeps last 20 snapshots, discards oldest
+debug: { timeTravel: true, maxSnapshots: 20 },
+
+// Development — generous cap for deep debugging
+debug: { timeTravel: true, maxSnapshots: 500 },
+
+// Default if not specified
+debug: { timeTravel: true }, // maxSnapshots defaults to 50
+```
+
+When the cap is reached, the oldest snapshot is discarded (FIFO). Redo history beyond the cap is lost.
+
+## Common Mistakes
+
+### Enabling time-travel in production
+
+```typescript
+// WRONG — snapshots consume memory on every mutation
+const system = createSystem({
+  module: myModule,
+  debug: { timeTravel: true },
+});
+
+// CORRECT — gate on environment
+const system = createSystem({
+  module: myModule,
+  debug: {
+    timeTravel: process.env.NODE_ENV === "development",
+    maxSnapshots: 100,
+  },
+});
+```
+
+### Forgetting to end a changeset
+
+```typescript
+// WRONG — changeset never closed, all subsequent mutations are grouped
+tt.beginChangeset("update");
+system.facts.name = "Alice";
+// ... forgot endChangeset()
+system.facts.unrelated = true; // Still part of the changeset!
+
+// CORRECT — always close changesets
+tt.beginChangeset("update");
+system.facts.name = "Alice";
+tt.endChangeset();
+```
+
+### Accessing time-travel when disabled
+
+```typescript
+// WRONG — timeTravel not enabled, system.debug.timeTravel is null
+const system = createSystem({ module: myModule });
+system.debug.timeTravel.undo(); // TypeError!
+
+// CORRECT — check before using
+const tt = system.debug.timeTravel;
+if (tt) {
+  tt.undo();
+}
+
+// Or enable it
+const system = createSystem({
+  module: myModule,
+  debug: { timeTravel: true },
+});
+```
+
+### No maxSnapshots cap with frequent mutations
+
+```typescript
+// WRONG — unbounded snapshots in a high-frequency update loop
+debug: { timeTravel: true }, // Default cap is 50, which is fine
+
+// Be explicit when mutation rate is high
+debug: { timeTravel: true, maxSnapshots: 30 },
+```

package/dist/index.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/index.ts
+var __dirname$1 = path.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
+var PKG_ROOT = path.resolve(__dirname$1, "..");
+function resolveAsset(name) {
+  const fromDist = path.join(PKG_ROOT, name);
+  if (fs.existsSync(fromDist)) {
+    return fromDist;
+  }
+  const fromSrc = path.join(PKG_ROOT, "..", name);
+  if (fs.existsSync(fromSrc)) {
+    return fromSrc;
+  }
+  return fromDist;
+}
+var CORE_DIR = resolveAsset("core");
+var AI_DIR = resolveAsset("ai");
+var EXAMPLES_DIR = resolveAsset("examples");
+var API_SKELETON_PATH = resolveAsset("api-skeleton.md");
+var knowledgeCache = null;
+var exampleCache = null;
+function loadDir(dir, map) {
+  try {
+    const files = fs.readdirSync(dir).filter(
+      (f) => f.endsWith(".md") || f.endsWith(".ts")
+    );
+    for (const file of files) {
+      const name = file.replace(/\.(md|ts)$/, "");
+      map.set(name, fs.readFileSync(path.join(dir, file), "utf-8"));
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+function loadAllKnowledge() {
+  const map = /* @__PURE__ */ new Map();
+  loadDir(CORE_DIR, map);
+  loadDir(AI_DIR, map);
+  try {
+    map.set("api-skeleton", fs.readFileSync(API_SKELETON_PATH, "utf-8"));
+  } catch {
+  }
+  return map;
+}
+function loadAllExamples() {
+  const map = /* @__PURE__ */ new Map();
+  loadDir(EXAMPLES_DIR, map);
+  return map;
+}
+function getKnowledge(name) {
+  if (!knowledgeCache) {
+    knowledgeCache = loadAllKnowledge();
+  }
+  return knowledgeCache.get(name) ?? "";
+}
+function getAllKnowledge() {
+  if (!knowledgeCache) {
+    knowledgeCache = loadAllKnowledge();
+  }
+  return knowledgeCache;
+}
+function getExample(name) {
+  if (!exampleCache) {
+    exampleCache = loadAllExamples();
+  }
+  return exampleCache.get(name) ?? "";
+}
+function getAllExamples() {
+  if (!exampleCache) {
+    exampleCache = loadAllExamples();
+  }
+  return exampleCache;
+}
+function getKnowledgeFiles(names) {
+  return names.map((name) => getKnowledge(name)).filter(Boolean).join("\n\n---\n\n");
+}
+function getExampleFiles(names) {
+  return names.map((name) => {
+    const content = getExample(name);
+    if (!content) {
+      return "";
+    }
+    return `### Example: ${name}
+
+\`\`\`typescript
+${content}
+\`\`\``;
+  }).filter(Boolean).join("\n\n");
+}
+function clearCache() {
+  knowledgeCache = null;
+  exampleCache = null;
+}
+
+exports.clearCache = clearCache;
+exports.getAllExamples = getAllExamples;
+exports.getAllKnowledge = getAllKnowledge;
+exports.getExample = getExample;
+exports.getExampleFiles = getExampleFiles;
+exports.getKnowledge = getKnowledge;
+exports.getKnowledgeFiles = getKnowledgeFiles;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["__dirname","dirname","fileURLToPath","resolve","join","existsSync","readdirSync","readFileSync"],"mappings":"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","file":"index.cjs","sourcesContent":["import { existsSync, readFileSync, readdirSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n// Resolve package root: works both in src/ (dev) and dist/ (bundled)\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst PKG_ROOT = resolve(__dirname, \"..\");\n\n/**\n * Resolve a path relative to the package root.\n * Tries dist-relative first (bundled), then src-relative (dev).\n */\nfunction resolveAsset(name: string): string {\n  const fromDist = join(PKG_ROOT, name);\n  if (existsSync(fromDist)) {\n    return fromDist;\n  }\n\n  const fromSrc = join(PKG_ROOT, \"..\", name);\n  if (existsSync(fromSrc)) {\n    return fromSrc;\n  }\n\n  return fromDist; // default, will just return empty maps\n}\n\nconst CORE_DIR = resolveAsset(\"core\");\nconst AI_DIR = resolveAsset(\"ai\");\nconst EXAMPLES_DIR = resolveAsset(\"examples\");\nconst API_SKELETON_PATH = resolveAsset(\"api-skeleton.md\");\n\nlet knowledgeCache: Map<string, string> | null = null;\nlet exampleCache: Map<string, string> | null = null;\n\nfunction loadDir(dir: string, map: Map<string, string>): void {\n  try {\n    const files = readdirSync(dir).filter(\n      (f) => f.endsWith(\".md\") || f.endsWith(\".ts\"),\n    );\n    for (const file of files) {\n      const name = file.replace(/\\.(md|ts)$/, \"\");\n      map.set(name, readFileSync(join(dir, file), \"utf-8\"));\n    }\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      throw err;\n    }\n    // directory does not exist — expected during tests or incomplete installs\n  }\n}\n\nfunction loadAllKnowledge(): Map<string, string> {\n  const map = new Map<string, string>();\n  loadDir(CORE_DIR, map);\n  loadDir(AI_DIR, map);\n\n  // Include api-skeleton\n  try {\n    map.set(\"api-skeleton\", readFileSync(API_SKELETON_PATH, \"utf-8\"));\n  } catch {\n    // may not exist yet\n  }\n\n  return map;\n}\n\nfunction loadAllExamples(): Map<string, string> {\n  const map = new Map<string, string>();\n  loadDir(EXAMPLES_DIR, map);\n\n  return map;\n}\n\nexport function getKnowledge(name: string): string {\n  if (!knowledgeCache) {\n    knowledgeCache = loadAllKnowledge();\n  }\n\n  return knowledgeCache.get(name) ?? \"\";\n}\n\nexport function getAllKnowledge(): ReadonlyMap<string, string> {\n  if (!knowledgeCache) {\n    knowledgeCache = loadAllKnowledge();\n  }\n\n  return knowledgeCache;\n}\n\nexport function getExample(name: string): string {\n  if (!exampleCache) {\n    exampleCache = loadAllExamples();\n  }\n\n  return exampleCache.get(name) ?? \"\";\n}\n\nexport function getAllExamples(): ReadonlyMap<string, string> {\n  if (!exampleCache) {\n    exampleCache = loadAllExamples();\n  }\n\n  return exampleCache;\n}\n\nexport function getKnowledgeFiles(names: string[]): string {\n  return names\n    .map((name) => getKnowledge(name))\n    .filter(Boolean)\n    .join(\"\\n\\n---\\n\\n\");\n}\n\nexport function getExampleFiles(names: string[]): string {\n  return names\n    .map((name) => {\n      const content = getExample(name);\n      if (!content) {\n        return \"\";\n      }\n\n      return `### Example: ${name}\\n\\n\\`\\`\\`typescript\\n${content}\\n\\`\\`\\``;\n    })\n    .filter(Boolean)\n    .join(\"\\n\\n\");\n}\n\n/** Clear cached knowledge and examples. Useful for dev/watch mode. */\nexport function clearCache(): void {\n  knowledgeCache = null;\n  exampleCache = null;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,10 @@
+declare function getKnowledge(name: string): string;
+declare function getAllKnowledge(): ReadonlyMap<string, string>;
+declare function getExample(name: string): string;
+declare function getAllExamples(): ReadonlyMap<string, string>;
+declare function getKnowledgeFiles(names: string[]): string;
+declare function getExampleFiles(names: string[]): string;
+/** Clear cached knowledge and examples. Useful for dev/watch mode. */
+declare function clearCache(): void;
+
+export { clearCache, getAllExamples, getAllKnowledge, getExample, getExampleFiles, getKnowledge, getKnowledgeFiles };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+declare function getKnowledge(name: string): string;
+declare function getAllKnowledge(): ReadonlyMap<string, string>;
+declare function getExample(name: string): string;
+declare function getAllExamples(): ReadonlyMap<string, string>;
+declare function getKnowledgeFiles(names: string[]): string;
+declare function getExampleFiles(names: string[]): string;
+/** Clear cached knowledge and examples. Useful for dev/watch mode. */
+declare function clearCache(): void;
+
+export { clearCache, getAllExamples, getAllKnowledge, getExample, getExampleFiles, getKnowledge, getKnowledgeFiles };

package/dist/index.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { dirname, resolve, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// src/index.ts
+var __dirname$1 = dirname(fileURLToPath(import.meta.url));
+var PKG_ROOT = resolve(__dirname$1, "..");
+function resolveAsset(name) {
+  const fromDist = join(PKG_ROOT, name);
+  if (existsSync(fromDist)) {
+    return fromDist;
+  }
+  const fromSrc = join(PKG_ROOT, "..", name);
+  if (existsSync(fromSrc)) {
+    return fromSrc;
+  }
+  return fromDist;
+}
+var CORE_DIR = resolveAsset("core");
+var AI_DIR = resolveAsset("ai");
+var EXAMPLES_DIR = resolveAsset("examples");
+var API_SKELETON_PATH = resolveAsset("api-skeleton.md");
+var knowledgeCache = null;
+var exampleCache = null;
+function loadDir(dir, map) {
+  try {
+    const files = readdirSync(dir).filter(
+      (f) => f.endsWith(".md") || f.endsWith(".ts")
+    );
+    for (const file of files) {
+      const name = file.replace(/\.(md|ts)$/, "");
+      map.set(name, readFileSync(join(dir, file), "utf-8"));
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+function loadAllKnowledge() {
+  const map = /* @__PURE__ */ new Map();
+  loadDir(CORE_DIR, map);
+  loadDir(AI_DIR, map);
+  try {
+    map.set("api-skeleton", readFileSync(API_SKELETON_PATH, "utf-8"));
+  } catch {
+  }
+  return map;
+}
+function loadAllExamples() {
+  const map = /* @__PURE__ */ new Map();
+  loadDir(EXAMPLES_DIR, map);
+  return map;
+}
+function getKnowledge(name) {
+  if (!knowledgeCache) {
+    knowledgeCache = loadAllKnowledge();
+  }
+  return knowledgeCache.get(name) ?? "";
+}
+function getAllKnowledge() {
+  if (!knowledgeCache) {
+    knowledgeCache = loadAllKnowledge();
+  }
+  return knowledgeCache;
+}
+function getExample(name) {
+  if (!exampleCache) {
+    exampleCache = loadAllExamples();
+  }
+  return exampleCache.get(name) ?? "";
+}
+function getAllExamples() {
+  if (!exampleCache) {
+    exampleCache = loadAllExamples();
+  }
+  return exampleCache;
+}
+function getKnowledgeFiles(names) {
+  return names.map((name) => getKnowledge(name)).filter(Boolean).join("\n\n---\n\n");
+}
+function getExampleFiles(names) {
+  return names.map((name) => {
+    const content = getExample(name);
+    if (!content) {
+      return "";
+    }
+    return `### Example: ${name}
+
+\`\`\`typescript
+${content}
+\`\`\``;
+  }).filter(Boolean).join("\n\n");
+}
+function clearCache() {
+  knowledgeCache = null;
+  exampleCache = null;
+}
+
+export { clearCache, getAllExamples, getAllKnowledge, getExample, getExampleFiles, getKnowledge, getKnowledgeFiles };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["__dirname"],"mappings":"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","file":"index.js","sourcesContent":["import { existsSync, readFileSync, readdirSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n// Resolve package root: works both in src/ (dev) and dist/ (bundled)\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst PKG_ROOT = resolve(__dirname, \"..\");\n\n/**\n * Resolve a path relative to the package root.\n * Tries dist-relative first (bundled), then src-relative (dev).\n */\nfunction resolveAsset(name: string): string {\n  const fromDist = join(PKG_ROOT, name);\n  if (existsSync(fromDist)) {\n    return fromDist;\n  }\n\n  const fromSrc = join(PKG_ROOT, \"..\", name);\n  if (existsSync(fromSrc)) {\n    return fromSrc;\n  }\n\n  return fromDist; // default, will just return empty maps\n}\n\nconst CORE_DIR = resolveAsset(\"core\");\nconst AI_DIR = resolveAsset(\"ai\");\nconst EXAMPLES_DIR = resolveAsset(\"examples\");\nconst API_SKELETON_PATH = resolveAsset(\"api-skeleton.md\");\n\nlet knowledgeCache: Map<string, string> | null = null;\nlet exampleCache: Map<string, string> | null = null;\n\nfunction loadDir(dir: string, map: Map<string, string>): void {\n  try {\n    const files = readdirSync(dir).filter(\n      (f) => f.endsWith(\".md\") || f.endsWith(\".ts\"),\n    );\n    for (const file of files) {\n      const name = file.replace(/\\.(md|ts)$/, \"\");\n      map.set(name, readFileSync(join(dir, file), \"utf-8\"));\n    }\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      throw err;\n    }\n    // directory does not exist — expected during tests or incomplete installs\n  }\n}\n\nfunction loadAllKnowledge(): Map<string, string> {\n  const map = new Map<string, string>();\n  loadDir(CORE_DIR, map);\n  loadDir(AI_DIR, map);\n\n  // Include api-skeleton\n  try {\n    map.set(\"api-skeleton\", readFileSync(API_SKELETON_PATH, \"utf-8\"));\n  } catch {\n    // may not exist yet\n  }\n\n  return map;\n}\n\nfunction loadAllExamples(): Map<string, string> {\n  const map = new Map<string, string>();\n  loadDir(EXAMPLES_DIR, map);\n\n  return map;\n}\n\nexport function getKnowledge(name: string): string {\n  if (!knowledgeCache) {\n    knowledgeCache = loadAllKnowledge();\n  }\n\n  return knowledgeCache.get(name) ?? \"\";\n}\n\nexport function getAllKnowledge(): ReadonlyMap<string, string> {\n  if (!knowledgeCache) {\n    knowledgeCache = loadAllKnowledge();\n  }\n\n  return knowledgeCache;\n}\n\nexport function getExample(name: string): string {\n  if (!exampleCache) {\n    exampleCache = loadAllExamples();\n  }\n\n  return exampleCache.get(name) ?? \"\";\n}\n\nexport function getAllExamples(): ReadonlyMap<string, string> {\n  if (!exampleCache) {\n    exampleCache = loadAllExamples();\n  }\n\n  return exampleCache;\n}\n\nexport function getKnowledgeFiles(names: string[]): string {\n  return names\n    .map((name) => getKnowledge(name))\n    .filter(Boolean)\n    .join(\"\\n\\n---\\n\\n\");\n}\n\nexport function getExampleFiles(names: string[]): string {\n  return names\n    .map((name) => {\n      const content = getExample(name);\n      if (!content) {\n        return \"\";\n      }\n\n      return `### Example: ${name}\\n\\n\\`\\`\\`typescript\\n${content}\\n\\`\\`\\``;\n    })\n    .filter(Boolean)\n    .join(\"\\n\\n\");\n}\n\n/** Clear cached knowledge and examples. Useful for dev/watch mode. */\nexport function clearCache(): void {\n  knowledgeCache = null;\n  exampleCache = null;\n}\n"]}