autonomous-flow-daemon 1.1.0 → 1.6.0

package/src/commands/vaccine.ts

@@ -0,0 +1,177 @@
+/**
+ * afd vaccine — Vaccine registry CLI
+ *
+ * Sub-commands:
+ *   afd vaccine list              — list available packages
+ *   afd vaccine search <query>    — search packages
+ *   afd vaccine install <name>    — install a vaccine package
+ *   afd vaccine publish <file>    — publish a vaccine package
+ *   afd vaccine installed         — list installed packages
+ */
+
+import { readFileSync, existsSync } from "fs";
+import {
+  publishPackage,
+  searchPackages,
+  installPackage,
+  listInstalled,
+  getPackage,
+} from "../core/vaccine-registry";
+import type { VaccinePackage } from "../core/vaccine-registry";
+import { getSystemLanguage } from "../core/locale";
+
+const msgs = {
+  en: {
+    title: "afd vaccine — Registry",
+    list: "Available Packages",
+    search: "Search Results",
+    install: "Install",
+    publish: "Publish",
+    installed: "Installed Packages",
+    noPackages: "No packages found.",
+    noResults: "No matching packages.",
+    notFound: "Package not found.",
+    usage: `Usage:
+  afd vaccine list              List available packages
+  afd vaccine search <query>    Search packages
+  afd vaccine install <name>    Install a vaccine package
+  afd vaccine publish <file>    Publish from vaccine.json
+  afd vaccine installed         List installed packages`,
+  },
+  ko: {
+    title: "afd vaccine — 레지스트리",
+    list: "사용 가능한 패키지",
+    search: "검색 결과",
+    install: "설치",
+    publish: "발행",
+    installed: "설치된 패키지",
+    noPackages: "패키지가 없습니다.",
+    noResults: "일치하는 패키지가 없습니다.",
+    notFound: "패키지를 찾을 수 없습니다.",
+    usage: `사용법:
+  afd vaccine list              사용 가능한 패키지 목록
+  afd vaccine search <query>    패키지 검색
+  afd vaccine install <name>    백신 패키지 설치
+  afd vaccine publish <file>    vaccine.json에서 발행
+  afd vaccine installed         설치된 패키지 목록`,
+  },
+};
+
+const BOX = { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│", ml: "├", mr: "┤" };
+const W = 54;
+function hline(l: string, r: string) { return `${l}${BOX.h.repeat(W)}${r}`; }
+function row(s: string) {
+  const pad = Math.max(0, W - 2 - s.length);
+  return `${BOX.v} ${s}${" ".repeat(pad)} ${BOX.v}`;
+}
+
+export async function vaccineCommand(subcommand?: string, arg?: string) {
+  const lang = getSystemLanguage();
+  const m = msgs[lang];
+
+  if (!subcommand) {
+    console.log(m.usage);
+    return;
+  }
+
+  switch (subcommand) {
+    case "list": {
+      const packages = searchPackages();
+      console.log(hline(BOX.tl, BOX.tr));
+      console.log(row(`💉 ${m.title} — ${m.list}`));
+      console.log(hline(BOX.ml, BOX.mr));
+      if (packages.length === 0) {
+        console.log(row(m.noPackages));
+      } else {
+        for (const p of packages) {
+          console.log(row(`📦 ${p.name}@${p.version} (${p.antibodyCount} rules)`));
+          console.log(row(`   ${p.description}`));
+          console.log(row(`   ${p.ecosystem} | by ${p.author}`));
+          console.log(row(""));
+        }
+      }
+      console.log(hline(BOX.bl, BOX.br));
+      break;
+    }
+
+    case "search": {
+      const results = searchPackages(arg);
+      console.log(hline(BOX.tl, BOX.tr));
+      console.log(row(`🔍 ${m.title} — ${m.search}: "${arg ?? ""}"`));
+      console.log(hline(BOX.ml, BOX.mr));
+      if (results.length === 0) {
+        console.log(row(m.noResults));
+      } else {
+        for (const p of results) {
+          console.log(row(`📦 ${p.name}@${p.version} — ${p.description}`));
+        }
+      }
+      console.log(hline(BOX.bl, BOX.br));
+      break;
+    }
+
+    case "install": {
+      if (!arg) {
+        console.error("Usage: afd vaccine install <name>");
+        process.exit(1);
+      }
+      const result = installPackage(arg);
+      if (!result.success) {
+        console.error(`[afd vaccine] ${result.message}`);
+        process.exit(1);
+      }
+      console.log(hline(BOX.tl, BOX.tr));
+      console.log(row(`✅ ${m.install}: ${arg}`));
+      console.log(hline(BOX.ml, BOX.mr));
+      console.log(row(result.message));
+      console.log(hline(BOX.bl, BOX.br));
+      break;
+    }
+
+    case "publish": {
+      const filePath = arg ?? "vaccine.json";
+      if (!existsSync(filePath)) {
+        console.error(`[afd vaccine] File not found: ${filePath}`);
+        process.exit(1);
+      }
+      let pkg: VaccinePackage;
+      try {
+        pkg = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        console.error("[afd vaccine] Invalid JSON in vaccine file.");
+        process.exit(1);
+      }
+      const result = publishPackage(pkg);
+      console.log(hline(BOX.tl, BOX.tr));
+      console.log(row(`📤 ${m.publish}`));
+      console.log(hline(BOX.ml, BOX.mr));
+      console.log(row(result.message));
+      console.log(hline(BOX.bl, BOX.br));
+      break;
+    }
+
+    case "installed": {
+      const pkgs = listInstalled();
+      console.log(hline(BOX.tl, BOX.tr));
+      console.log(row(`📋 ${m.title} — ${m.installed}`));
+      console.log(hline(BOX.ml, BOX.mr));
+      if (pkgs.length === 0) {
+        console.log(row(m.noPackages));
+      } else {
+        for (const name of pkgs) {
+          const pkg = getPackage(name);
+          if (pkg) {
+            console.log(row(`📦 ${pkg.name}@${pkg.version} (${pkg.antibodies.length} rules)`));
+          } else {
+            console.log(row(`📦 ${name}`));
+          }
+        }
+      }
+      console.log(hline(BOX.bl, BOX.br));
+      break;
+    }
+
+    default:
+      console.log(m.usage);
+  }
+}

package/src/constants.ts

@@ -1,8 +1,32 @@
 import { join } from "path";
+import { findWorkspaceRoot } from "./core/workspace";
 
+// Relative paths (used when cwd is already the workspace root)
 export const AFD_DIR = ".afd";
 export const PID_FILE = join(AFD_DIR, "daemon.pid");
 export const PORT_FILE = join(AFD_DIR, "daemon.port");
 export const DB_FILE = join(AFD_DIR, "antibodies.sqlite");
 export const LOG_FILE = join(AFD_DIR, "daemon.log");
-export const WATCH_TARGETS = [".claude/", "CLAUDE.md", ".cursorrules", ".claudeignore", ".gitignore"];
+export const QUARANTINE_DIR = join(AFD_DIR, "quarantine");
+export const WATCH_TARGETS = [
+  ".claude/", "CLAUDE.md", ".cursorrules", ".claudeignore", ".gitignore",
+  ".windsurfrules", ".windsurf/", "codex.md", ".codex/",
+  ".cursorignore", ".windsurfignore", ".codexignore",
+];
+
+/**
+ * Resolve all `.afd/` paths against the workspace root.
+ * Works correctly even when CLI is invoked from a subdirectory.
+ */
+export function resolveWorkspacePaths(from?: string) {
+  const root = findWorkspaceRoot(from);
+  return {
+    root,
+    afdDir: join(root, AFD_DIR),
+    pidFile: join(root, PID_FILE),
+    portFile: join(root, PORT_FILE),
+    dbFile: join(root, DB_FILE),
+    logFile: join(root, LOG_FILE),
+    quarantineDir: join(root, QUARANTINE_DIR),
+  };
+}

package/src/core/boast.ts

@@ -1,9 +1,7 @@
 /**
  * Boastful Doctor — Gamification & Delightful Logging
  *
- * Lightweight value calculations that stay well under the 270ms budget.
- * All math is O(1) — no I/O, no async.
- * All strings are localized via the i18n dictionary.
+ * O(1) math only — no I/O, no async. All strings localized via i18n.
  */
 
 import { getSystemLanguage } from "./locale";
@@ -13,13 +11,8 @@ import type { MessageDict } from "./i18n/messages";
 
 // ── Token & Cost Estimation ──
 
-/** Rough chars-per-token ratio for code (conservative estimate) */
 const CHARS_PER_TOKEN = 3.5;
-
-/** Average cost per 1K input tokens (Claude Sonnet ballpark) */
 const COST_PER_1K_TOKENS = 0.003;
-
-/** Estimated minutes a developer spends debugging a missing config */
 const DEBUG_MINUTES_BASE = 8;
 const DEBUG_MINUTES_PER_KB = 2;
 
@@ -50,6 +43,11 @@ export interface ShiftSummary {
   suppressionsSkipped: number;
   dormantTransitions: number;
   boast: string;
+  // Unified ROI breakdown
+  healTokensSaved: number;
+  healCostSaved: number;
+  hologramTokensSaved: number;
+  hologramCostSaved: number;
 }
 
 /** Build a shift summary from aggregated daemon stats. */
@@ -60,12 +58,24 @@ export function buildShiftSummary(stats: {
   totalFileBytesSaved: number;
   suppressionsSkipped: number;
   dormantTransitions: number;
+  hologramSavedChars?: number;
 }, lang?: SupportedLang): ShiftSummary {
   const l = lang ?? getSystemLanguage();
-  const msg = getMessages(l);
-  const totalTokensSaved = Math.round(stats.totalFileBytesSaved / CHARS_PER_TOKEN);
+  const m = getMessages(l);
+
+  // Auto-Heal ROI
+  const healTokensSaved = Math.round(stats.totalFileBytesSaved / CHARS_PER_TOKEN);
+  const healCostSaved = Math.round(healTokensSaved / 1000 * COST_PER_1K_TOKENS * 100) / 100;
+
+  // Hologram ROI
+  const holoSavedChars = stats.hologramSavedChars ?? 0;
+  const hologramTokensSaved = Math.round(holoSavedChars / CHARS_PER_TOKEN);
+  const hologramCostSaved = Math.round(hologramTokensSaved / 1000 * COST_PER_1K_TOKENS * 100) / 100;
+
+  // Unified totals
+  const totalTokensSaved = healTokensSaved + hologramTokensSaved;
   const totalMinutesSaved = stats.healsPerformed * DEBUG_MINUTES_BASE;
-  const totalCostSaved = Math.round(totalTokensSaved / 1000 * COST_PER_1K_TOKENS * 100) / 100;
+  const totalCostSaved = Math.round((healCostSaved + hologramCostSaved) * 100) / 100;
 
   return {
     uptimeFormatted: formatUptime(stats.uptimeSeconds),
@@ -76,7 +86,11 @@ export function buildShiftSummary(stats: {
     totalCostSaved,
     suppressionsSkipped: stats.suppressionsSkipped,
     dormantTransitions: stats.dormantTransitions,
-    boast: pick(msg.BOAST_SHIFT_END),
+    boast: pick(m.BOAST_SHIFT_END),
+    healTokensSaved,
+    healCostSaved,
+    hologramTokensSaved,
+    hologramCostSaved,
   };
 }
 
@@ -180,6 +194,7 @@ export function formatValueSection(s: ShiftSummary, lang?: SupportedLang): strin
 // ── Helpers ──
 
 function pick<T>(arr: T[]): T {
+  if (arr.length === 0) return "" as unknown as T;
   return arr[Math.floor(Math.random() * arr.length)];
 }
 

package/src/core/db.ts

@@ -1,10 +1,11 @@
 import { mkdirSync } from "fs";
 import { Database } from "bun:sqlite";
-import { AFD_DIR, DB_FILE } from "../constants";
+import { resolveWorkspacePaths } from "../constants";
 
 export function initDb(): Database {
-  mkdirSync(AFD_DIR, { recursive: true });
-  const db = new Database(DB_FILE);
+  const paths = resolveWorkspacePaths();
+  mkdirSync(paths.afdDir, { recursive: true });
+  const db = new Database(paths.dbFile);
   db.exec("PRAGMA journal_mode = WAL");
 
   db.exec(`
@@ -42,5 +43,75 @@ export function initDb(): Database {
     )
   `);
 
+  // ── Hologram Stats: lifetime (single row) + daily (7-day rolling) ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS hologram_lifetime (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      total_requests INTEGER NOT NULL DEFAULT 0,
+      total_original_chars INTEGER NOT NULL DEFAULT 0,
+      total_hologram_chars INTEGER NOT NULL DEFAULT 0
+    )
+  `);
+  db.exec(`INSERT OR IGNORE INTO hologram_lifetime (id) VALUES (1)`);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS hologram_daily (
+      date TEXT PRIMARY KEY,
+      requests INTEGER NOT NULL DEFAULT 0,
+      original_chars INTEGER NOT NULL DEFAULT 0,
+      hologram_chars INTEGER NOT NULL DEFAULT 0
+    )
+  `);
+  // Purge entries older than 7 days
+  db.exec(`DELETE FROM hologram_daily WHERE date < date('now', '-7 days')`);
+
+  // ── Telemetry: feature usage tracking ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS telemetry (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      category TEXT NOT NULL,
+      action TEXT NOT NULL,
+      detail TEXT,
+      duration_ms REAL,
+      timestamp INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+    )
+  `);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_telemetry_cat_ts ON telemetry(category, timestamp)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_telemetry_action ON telemetry(action)`);
+  // Purge raw telemetry older than 30 days
+  db.exec(`DELETE FROM telemetry WHERE timestamp < unixepoch() * 1000 - 30 * 86400000`);
+
+  // ── Mistake History: passive defense tracking ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS mistake_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      mistake_type TEXT NOT NULL,
+      description TEXT NOT NULL,
+      antibody_id TEXT,
+      timestamp INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+    )
+  `);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_mistake_history_path ON mistake_history(file_path)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_mistake_history_ts ON mistake_history(timestamp)`);
+  db.exec(`DELETE FROM mistake_history WHERE timestamp < unixepoch() * 1000 - 30 * 86400000`);
+
+  // Migration: move data from old hologram_stats table if it exists
+  try {
+    const old = db.prepare("SELECT total_requests, total_original_chars, total_hologram_chars FROM hologram_stats WHERE id = 1").get() as {
+      total_requests: number; total_original_chars: number; total_hologram_chars: number;
+    } | null;
+    if (old && old.total_requests > 0) {
+      db.transaction(() => {
+        db.prepare(
+          "UPDATE hologram_lifetime SET total_requests = ?, total_original_chars = ?, total_hologram_chars = ? WHERE id = 1"
+        ).run(old.total_requests, old.total_original_chars, old.total_hologram_chars);
+        db.exec("DROP TABLE hologram_stats");
+      })();
+    }
+  } catch {
+    // Old table doesn't exist — clean install
+  }
+
   return db;
 }

package/src/core/evolution.ts

@@ -0,0 +1,215 @@
+/**
+ * Self-Evolution Engine
+ *
+ * Analyzes quarantined (corrupted) files against their restored originals,
+ * generates failure lessons, and writes them to afd-lessons.md so AI agents
+ * learn from their own mistakes.
+ */
+
+import { readdirSync, readFileSync, writeFileSync, renameSync, existsSync } from "fs";
+import { resolve, basename } from "path";
+import { QUARANTINE_DIR } from "../constants";
+import { lineDiff } from "./log-utils";
+
+const LESSONS_FILE = "afd-lessons.md";
+const LEARNED_SUFFIX = ".learned";
+
+export interface QuarantineEntry {
+  /** Full path inside .afd/quarantine/ */
+  quarantinePath: string;
+  /** Original file path (reconstructed from quarantine filename) */
+  originalPath: string;
+  /** Timestamp string extracted from filename */
+  timestamp: string;
+  /** Whether this entry has already been learned */
+  learned: boolean;
+}
+
+export interface EvolutionLesson {
+  entry: QuarantineEntry;
+  diff: string[];
+  corruptedContent: string;
+  restoredContent: string | null;
+  failureType: "corruption" | "deletion";
+  suggestion: string;
+}
+
+export interface EvolutionStats {
+  totalQuarantined: number;
+  totalLearned: number;
+  pending: number;
+  lessons: EvolutionLesson[];
+}
+
+/** Parse quarantine filename: YYYYMMDD_HHMMSS_originalname → { timestamp, originalPath } */
+function parseQuarantineName(filename: string): { timestamp: string; originalPath: string } | null {
+  // e.g. 20260401_021028_.claude_hooks.json or 20260401_020741_.claudeignore
+  const match = filename.replace(LEARNED_SUFFIX, "").match(/^(\d{8}_\d{6})_(.+)$/);
+  if (!match) return null;
+  const ts = match[1];
+  // Reconstruct path: underscores that were separators become path separators
+  // Heuristic: first underscore-delimited segment starting with "." is likely a directory
+  const rawName = match[2];
+  // Reverse the flatten: `.claude_hooks.json` → `.claude/hooks.json`
+  const originalPath = rawName.replace(/^\.([^.]+)_/, ".$1/");
+  return { timestamp: ts, originalPath };
+}
+
+/** List all quarantined entries */
+export function listQuarantine(): QuarantineEntry[] {
+  if (!existsSync(QUARANTINE_DIR)) return [];
+  const files = readdirSync(QUARANTINE_DIR);
+  const entries: QuarantineEntry[] = [];
+
+  for (const file of files) {
+    const isLearned = file.endsWith(LEARNED_SUFFIX);
+    const cleanName = file.replace(LEARNED_SUFFIX, "");
+    const parsed = parseQuarantineName(cleanName);
+    if (!parsed) continue;
+    entries.push({
+      quarantinePath: resolve(QUARANTINE_DIR, file),
+      originalPath: parsed.originalPath,
+      timestamp: parsed.timestamp,
+      learned: isLearned,
+    });
+  }
+
+  return entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+/** Detect what type of corruption occurred */
+function detectFailureType(content: string): "corruption" | "deletion" {
+  return content.trim() === "DELETED" ? "deletion" : "corruption";
+}
+
+/** Generate a human-readable suggestion based on the failure */
+function generateSuggestion(entry: QuarantineEntry, failureType: string, corruptedContent: string, restoredContent: string | null): string {
+  const file = entry.originalPath;
+
+  if (failureType === "deletion") {
+    return `Do NOT delete \`${file}\`. This is an immune-critical file protected by afd. ` +
+      `If you need to modify it, edit the content instead of removing the file.`;
+  }
+
+  // Corruption analysis
+  if (file.endsWith(".json")) {
+    try {
+      JSON.parse(corruptedContent);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return `When editing \`${file}\`, ensure valid JSON syntax. ` +
+        `Common mistake: ${msg}. Always validate JSON structure after editing.`;
+    }
+  }
+
+  if (corruptedContent.trim().length === 0) {
+    return `Do NOT empty \`${file}\`. The file was overwritten with blank content. ` +
+      `Preserve existing content when making changes.`;
+  }
+
+  if (restoredContent && corruptedContent.length < restoredContent.length * 0.1) {
+    return `Do NOT truncate \`${file}\`. Content was reduced by >90%. ` +
+      `When editing, preserve the existing structure and only modify specific sections.`;
+  }
+
+  return `When editing \`${file}\`, be careful not to corrupt its structure. ` +
+    `Always verify the file is still valid after changes.`;
+}
+
+/** Analyze pending (unlearned) quarantine entries and produce lessons */
+export function analyzeQuarantine(): EvolutionStats {
+  const entries = listQuarantine();
+  const totalQuarantined = entries.length;
+  const totalLearned = entries.filter(e => e.learned).length;
+  const pending = entries.filter(e => !e.learned);
+
+  const lessons: EvolutionLesson[] = [];
+
+  for (const entry of pending) {
+    const corruptedContent = readFileSync(entry.quarantinePath, "utf-8");
+    const failureType = detectFailureType(corruptedContent);
+
+    let restoredContent: string | null = null;
+    let diff: string[] = [];
+
+    if (existsSync(entry.originalPath)) {
+      restoredContent = readFileSync(entry.originalPath, "utf-8");
+      if (failureType === "corruption") {
+        diff = lineDiff(corruptedContent, restoredContent, 20);
+      } else {
+        diff = [`  (file was deleted — restored from antibody snapshot)`];
+      }
+    } else {
+      diff = [`  (original file not found — may still be deleted)`];
+    }
+
+    const suggestion = generateSuggestion(entry, failureType, corruptedContent, restoredContent);
+
+    lessons.push({ entry, diff, corruptedContent, restoredContent, failureType, suggestion });
+  }
+
+  return { totalQuarantined, totalLearned, pending: pending.length, lessons };
+}
+
+/** Mark a quarantine entry as learned by renaming with .learned suffix */
+export function markLearned(entry: QuarantineEntry): void {
+  if (entry.learned) return;
+  const newPath = entry.quarantinePath + LEARNED_SUFFIX;
+  renameSync(entry.quarantinePath, newPath);
+}
+
+/** Build the lesson block for afd-lessons.md */
+function buildLessonBlock(lesson: EvolutionLesson): string {
+  const ts = lesson.entry.timestamp.replace("_", "T");
+  const formattedTs = `${ts.slice(0, 4)}-${ts.slice(4, 6)}-${ts.slice(6, 8)} ${ts.slice(9, 11)}:${ts.slice(11, 13)}:${ts.slice(13, 15)}`;
+  const lines: string[] = [
+    `### ${lesson.entry.originalPath} (${formattedTs})`,
+    `- **Type**: ${lesson.failureType === "deletion" ? "Unauthorized Deletion" : "Content Corruption"}`,
+    `- **Rule**: ${lesson.suggestion}`,
+  ];
+  if (lesson.diff.length > 0) {
+    lines.push(`- **Diff**:`);
+    lines.push("```");
+    lines.push(...lesson.diff);
+    lines.push("```");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Write lessons to afd-lessons.md and mark entries as learned.
+ * Returns the number of new lessons written.
+ */
+export function evolve(): { lessonsWritten: number; totalLessons: number } {
+  const stats = analyzeQuarantine();
+  if (stats.lessons.length === 0) {
+    return { lessonsWritten: 0, totalLessons: stats.totalLearned };
+  }
+
+  // Build new lesson blocks
+  const newBlocks = stats.lessons.map(buildLessonBlock);
+
+  // Read or initialize afd-lessons.md
+  let existing = "";
+  if (existsSync(LESSONS_FILE)) {
+    existing = readFileSync(LESSONS_FILE, "utf-8");
+  }
+
+  if (!existing.includes("# Failure Lessons")) {
+    existing = `# Failure Lessons\n\n` +
+      `> Auto-generated by afd Self-Evolution engine.\n` +
+      `> AI agents: read these rules to avoid repeating past mistakes.\n\n` +
+      existing;
+  }
+
+  // Append new lessons
+  const updated = existing.trimEnd() + "\n\n" + newBlocks.join("\n\n") + "\n";
+  writeFileSync(LESSONS_FILE, updated, "utf-8");
+
+  // Mark all analyzed entries as learned
+  for (const lesson of stats.lessons) {
+    markLearned(lesson.entry);
+  }
+
+  return { lessonsWritten: stats.lessons.length, totalLessons: stats.totalLearned + stats.lessons.length };
+}

package/src/core/hologram/engine.ts

@@ -0,0 +1,71 @@
+import { Parser, Language, type Tree } from "web-tree-sitter";
+import { resolve, dirname } from "path";
+
+/**
+ * Singleton Tree-sitter engine with grammar caching.
+ * Parser.init() runs once; grammar WASMs are lazy-loaded and cached in-memory.
+ */
+export class TreeSitterEngine {
+  private static instance: TreeSitterEngine | null = null;
+  private parser: Parser | null = null;
+  private grammarCache = new Map<string, Language>();
+  private initPromise: Promise<void> | null = null;
+
+  static async getInstance(): Promise<TreeSitterEngine> {
+    if (!this.instance) {
+      this.instance = new TreeSitterEngine();
+      await this.instance.init();
+    }
+    return this.instance;
+  }
+
+  /** Reset singleton — for testing only */
+  static resetForTest(): void {
+    if (this.instance?.parser) {
+      this.instance.parser.delete();
+    }
+    this.instance = null;
+  }
+
+  private async init(): Promise<void> {
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = (async () => {
+      await Parser.init();
+      this.parser = new Parser();
+    })();
+    return this.initPromise;
+  }
+
+  async parse(source: string, grammarName: string): Promise<Tree> {
+    const grammar = await this.loadGrammar(grammarName);
+    this.parser!.setLanguage(grammar);
+    const tree = this.parser!.parse(source);
+    if (!tree) throw new Error(`Failed to parse with grammar: ${grammarName}`);
+    return tree;
+  }
+
+  private async loadGrammar(grammarName: string): Promise<Language> {
+    const cached = this.grammarCache.get(grammarName);
+    if (cached) return cached;
+
+    const wasmPath = resolveGrammarWasm(grammarName);
+    const lang = await Language.load(wasmPath);
+    this.grammarCache.set(grammarName, lang);
+    return lang;
+  }
+}
+
+/** Resolve WASM file path from installed npm grammar package */
+function resolveGrammarWasm(grammarName: string): string {
+  // Grammar packages: tree-sitter-typescript, tree-sitter-python, etc.
+  // WASM file is at package root: node_modules/tree-sitter-{name}/tree-sitter-{name}.wasm
+  const packageName = `tree-sitter-${grammarName}`;
+  try {
+    // require.resolve returns bindings/node/index.js — walk up to package root
+    const pkgJson = require.resolve(`${packageName}/package.json`);
+    return resolve(dirname(pkgJson), `${packageName}.wasm`);
+  } catch {
+    // Fallback: try direct node_modules path
+    return resolve(process.cwd(), "node_modules", packageName, `${packageName}.wasm`);
+  }
+}

package/src/core/hologram/fallback.ts

@@ -0,0 +1,11 @@
+import type { HologramResult } from "./types";
+
+/** L0 fallback: return full source when tree-sitter cannot parse */
+export function fallbackL0(filePath: string, source: string): HologramResult {
+  return {
+    hologram: source,
+    originalLength: source.length,
+    hologramLength: source.length,
+    savings: 0,
+  };
+}