entroly-wasm 0.9.0

package/js/skills.js

@@ -0,0 +1,124 @@
+/**
+ * Skill Engine — pure-JS port of entroly/skill_engine.py
+ * Dynamic skill synthesis, benchmarking, and lifecycle management.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { randomUUID } = require('crypto');
+const { nowISO, safeFilename } = require('./vault');
+
+class SkillEngine {
+  constructor(vault) {
+    this._vault = vault;
+    this._skillsDir = path.join(vault._base, 'evolution', 'skills');
+  }
+
+  createSkill(entityKey, failingQueries, intent = '') {
+    this._vault.ensureStructure();
+    const skillId = `skill_${safeFilename(entityKey)}_${Date.now().toString(36)}`;
+    const skillDir = path.join(this._skillsDir, skillId);
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.mkdirSync(path.join(skillDir, 'tests'), { recursive: true });
+
+    // SKILL.md
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), [
+      `# Skill: ${entityKey}`,
+      '',
+      `**ID:** ${skillId}`,
+      `**Entity:** ${entityKey}`,
+      `**Intent:** ${intent || 'general'}`,
+      `**Created:** ${nowISO()}`,
+      `**Status:** draft`,
+      '',
+      '## Failing Queries',
+      '',
+      ...failingQueries.map(q => `- ${q}`),
+      '',
+      '## Procedure',
+      '',
+      '1. TODO: Define the skill procedure',
+      '2. TODO: Implement the tool',
+      '3. TODO: Add test cases',
+      '',
+    ].join('\n'), 'utf-8');
+
+    // metrics.json
+    fs.writeFileSync(path.join(skillDir, 'metrics.json'), JSON.stringify({
+      skill_id: skillId, entity: entityKey, created: nowISO(),
+      status: 'draft', fitness: 0, runs: 0, successes: 0, failures: 0,
+    }, null, 2), 'utf-8');
+
+    // tests/test_cases.json
+    fs.writeFileSync(path.join(skillDir, 'tests', 'test_cases.json'), JSON.stringify({
+      skill_id: skillId,
+      cases: failingQueries.map((q, i) => ({
+        id: `tc_${i}`, query: q, expected_pass: true, actual: null,
+      })),
+    }, null, 2), 'utf-8');
+
+    // Update registry
+    const regPath = path.join(this._vault._base, 'evolution', 'registry.md');
+    if (fs.existsSync(regPath)) {
+      const reg = fs.readFileSync(regPath, 'utf-8');
+      fs.writeFileSync(regPath, reg + `| ${skillId} | draft | ${nowISO().slice(0, 10)} | ${entityKey} |\n`, 'utf-8');
+    }
+
+    return { status: 'created', skill_id: skillId, entity: entityKey, path: skillDir, engine: 'javascript' };
+  }
+
+  listSkills() {
+    this._vault.ensureStructure();
+    if (!fs.existsSync(this._skillsDir)) return [];
+    const skills = [];
+    for (const name of fs.readdirSync(this._skillsDir)) {
+      const metricsPath = path.join(this._skillsDir, name, 'metrics.json');
+      if (!fs.existsSync(metricsPath)) continue;
+      try {
+        const m = JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+        skills.push({ skill_id: m.skill_id || name, entity: m.entity || '', status: m.status || 'draft', fitness: m.fitness || 0, runs: m.runs || 0 });
+      } catch {}
+    }
+    return skills;
+  }
+
+  benchmarkSkill(skillId) {
+    const metricsPath = path.join(this._skillsDir, skillId, 'metrics.json');
+    const testsPath = path.join(this._skillsDir, skillId, 'tests', 'test_cases.json');
+    if (!fs.existsSync(metricsPath)) return { error: `Skill '${skillId}' not found` };
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+    let cases = [];
+    if (fs.existsSync(testsPath)) {
+      try { cases = JSON.parse(fs.readFileSync(testsPath, 'utf-8')).cases || []; } catch {}
+    }
+    // Simple benchmark: count cases as "passed" if they have expected_pass
+    const passed = cases.filter(c => c.expected_pass).length;
+    const fitness = cases.length ? passed / cases.length : 0;
+    metrics.fitness = fitness;
+    metrics.runs = (metrics.runs || 0) + 1;
+    fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2), 'utf-8');
+    return { skill_id: skillId, fitness, test_cases: cases.length, passed, status: metrics.status, engine: 'javascript' };
+  }
+
+  promoteOrPrune(skillId) {
+    const metricsPath = path.join(this._skillsDir, skillId, 'metrics.json');
+    if (!fs.existsSync(metricsPath)) return { error: `Skill '${skillId}' not found` };
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+    let action;
+    if (metrics.fitness >= 0.7) {
+      metrics.status = 'promoted';
+      action = 'promoted';
+    } else if (metrics.fitness <= 0.3) {
+      metrics.status = 'pruned';
+      action = 'pruned';
+    } else {
+      action = 'no_change';
+    }
+    fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2), 'utf-8');
+    return { skill_id: skillId, action, fitness: metrics.fitness, new_status: metrics.status, engine: 'javascript' };
+  }
+}
+
+module.exports = { SkillEngine };

package/js/value_tracker.js

@@ -0,0 +1,181 @@
+/**
+ * ValueTracker — JS port of entroly/value_tracker.py
+ *
+ * Persistent, lifetime-savings accounting with the self-funded evolution
+ * budget invariant:
+ *
+ *     C_spent(t)  ≤  τ · S(t)         (τ = 5%)
+ *
+ * Any token-costing evolution step MUST gate on `getEvolutionBudget().canEvolve`.
+ * The tracker is atomic-write safe and survives process restarts.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const EVOLUTION_TAX_RATE = 0.05;
+const FILE_NAME = 'value_tracker.json';
+
+// Per-model $/1M tokens — kept in sync with entroly/value_tracker.py (×1000).
+const COST_PER_M = {
+  default: 3.0,
+  // OpenAI
+  'gpt-4o': 2.5,
+  'gpt-4o-mini': 0.15,
+  'gpt-4-turbo': 10.0,
+  'gpt-4': 30.0,
+  'gpt-3.5-turbo': 0.5,
+  'o1': 15.0,
+  'o1-mini': 3.0,
+  'o3': 10.0,
+  'o3-mini': 1.1,
+  'o4-mini': 1.1,
+  // Anthropic
+  'claude-opus-4': 15.0,
+  'claude-sonnet-4': 3.0,
+  'claude-haiku-4': 0.8,
+  'claude-3-5-sonnet': 3.0,
+  'claude-3-5-haiku': 0.8,
+  // Google
+  'gemini-2.5-pro': 1.25,
+  'gemini-2.5-flash': 0.075,
+  'gemini-1.5-pro': 1.25,
+  'gemini-1.5-flash': 0.075,
+};
+
+// Old→new name aliases so 'claude-3-opus' hits the same rate as Python.
+const MODEL_ALIASES = {
+  'claude-3-opus': 'claude-opus-4',
+  'claude-3-sonnet': 'claude-sonnet-4',
+  'claude-3-haiku': 'claude-haiku-4',
+  'claude-3.5-sonnet': 'claude-3-5-sonnet',
+  'claude-3.5-haiku': 'claude-3-5-haiku',
+};
+
+function estimateCost(tokens, model = '') {
+  let m = (model || '').toLowerCase();
+  for (const [alias, canonical] of Object.entries(MODEL_ALIASES)) {
+    if (m.startsWith(alias)) { m = canonical + m.slice(alias.length); break; }
+  }
+  // Longest-prefix match — prevents 'gpt-4o' eating 'gpt-4o-mini'.
+  const keys = Object.keys(COST_PER_M).filter(k => k !== 'default').sort((a, b) => b.length - a.length);
+  const key = (m && keys.find(k => m.startsWith(k)));
+  if (!key && model) {
+    // One-time warning per unknown model — stderr, doesn't pollute stdout.
+    if (!estimateCost._warned) estimateCost._warned = new Set();
+    if (!estimateCost._warned.has(model)) {
+      estimateCost._warned.add(model);
+      try { console.warn(`[entroly] unknown model '${model}'; using default $${COST_PER_M.default}/M`); } catch (_) {}
+    }
+  }
+  return (tokens / 1_000_000) * COST_PER_M[key || 'default'];
+}
+
+function atomicWrite(filePath, content) {
+  const tmp = filePath + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+class ValueTracker {
+  constructor(dataDir = null) {
+    this._dir = dataDir || path.join(os.homedir(), '.entroly');
+    fs.mkdirSync(this._dir, { recursive: true });
+    this._path = path.join(this._dir, FILE_NAME);
+    this._data = this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this._path)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(this._path, 'utf8'));
+        if (raw && typeof raw === 'object' && 'version' in raw) return raw;
+      } catch (_) { /* fall through */ }
+    }
+    return this._defaults();
+  }
+
+  _defaults() {
+    const now = Date.now() / 1000;
+    return {
+      version: 2,
+      lifetime: {
+        tokens_saved: 0,
+        cost_saved_usd: 0.0,
+        requests_optimized: 0,
+        first_seen: now,
+        last_seen: now,
+        evolution_spent_usd: 0.0,
+        evolution_attempts: 0,
+        evolution_successes: 0,
+      },
+    };
+  }
+
+  _save() {
+    try { atomicWrite(this._path, JSON.stringify(this._data, null, 2)); }
+    catch (_) { /* best-effort */ }
+  }
+
+  record({ tokensSaved = 0, model = '', optimized = true } = {}) {
+    const cost = estimateCost(tokensSaved, model);
+    const lt = this._data.lifetime;
+    lt.tokens_saved += tokensSaved;
+    lt.cost_saved_usd = +(lt.cost_saved_usd + cost).toFixed(6);
+    if (optimized) lt.requests_optimized += 1;
+    lt.last_seen = Date.now() / 1000;
+    this._save();
+    return { tokensSaved, costSaved: cost };
+  }
+
+  getEvolutionBudget() {
+    const lt = this._data.lifetime;
+    const lifetimeSaved = lt.cost_saved_usd || 0;
+    const totalSpent = lt.evolution_spent_usd || 0;
+    const totalEarned = lifetimeSaved * EVOLUTION_TAX_RATE;
+    const available = Math.max(0, totalEarned - totalSpent);
+    return {
+      availableUsd: +available.toFixed(6),
+      totalEarnedUsd: +totalEarned.toFixed(6),
+      totalSpentUsd: +totalSpent.toFixed(6),
+      canEvolve: available > 0.001,
+      taxRate: EVOLUTION_TAX_RATE,
+    };
+  }
+
+  recordEvolutionSpend(costUsd, success = false) {
+    const lt = this._data.lifetime;
+    const lifetimeSaved = lt.cost_saved_usd || 0;
+    const currentSpent = lt.evolution_spent_usd || 0;
+    const totalEarned = lifetimeSaved * EVOLUTION_TAX_RATE;
+    const available = totalEarned - currentSpent;
+
+    if (costUsd > available + 0.001) {
+      return {
+        status: 'rejected',
+        remainingUsd: +Math.max(0, available).toFixed(6),
+      };
+    }
+
+    lt.evolution_spent_usd = +(currentSpent + costUsd).toFixed(6);
+    lt.evolution_attempts = (lt.evolution_attempts || 0) + 1;
+    if (success) lt.evolution_successes = (lt.evolution_successes || 0) + 1;
+    this._save();
+    return {
+      status: 'recorded',
+      remainingUsd: +Math.max(0, available - costUsd).toFixed(6),
+    };
+  }
+
+  stats() {
+    return {
+      lifetime: { ...this._data.lifetime },
+      budget: this.getEvolutionBudget(),
+    };
+  }
+}
+
+module.exports = { ValueTracker, EVOLUTION_TAX_RATE, estimateCost };

package/js/vault.js

@@ -0,0 +1,237 @@
+/**
+ * Pure-JS VaultManager — port of entroly/vault.py
+ * Manages the persistent Knowledge Vault (Obsidian-compatible markdown).
+ *
+ * Directory contract:
+ *   vault/beliefs/        vault/verification/    vault/actions/
+ *   vault/evolution/skills/<id>/  vault/media/
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+const VAULT_DIRS = ['beliefs', 'verification', 'actions', 'evolution', 'media'];
+const SOURCE_EXTS = new Set(['.py', '.rs', '.ts', '.js', '.tsx', '.jsx', '.go', '.java', '.c', '.cpp', '.h', '.hpp', '.cs', '.rb', '.swift', '.kt']);
+
+function safeFilename(s) {
+  let safe = s.trim().toLowerCase().replace(/[^\w\-.]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+  return (safe || 'untitled').slice(0, 80);
+}
+
+function nowISO() { return new Date().toISOString(); }
+function timestamp() { return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z/, ''); }
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return null;
+  const end = content.indexOf('---', 3);
+  if (end < 0) return null;
+  const fm = {};
+  for (const line of content.slice(3, end).trim().split('\n')) {
+    if (line.trim().startsWith('-')) continue;
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim();
+    if (key && val) fm[key] = val;
+  }
+  return Object.keys(fm).length ? fm : null;
+}
+
+function extractSources(content) {
+  if (!content.startsWith('---')) return [];
+  const end = content.indexOf('---', 3);
+  if (end < 0) return [];
+  const lines = content.slice(3, end).trim().split('\n');
+  const sources = [];
+  let inSources = false;
+  for (const line of lines) {
+    const t = line.trim();
+    if (t.startsWith('sources:')) { inSources = true; continue; }
+    if (inSources) {
+      if (t.startsWith('- ')) { sources.push(t.slice(2).trim()); continue; }
+      if (t && !t.startsWith('-')) break;
+    }
+  }
+  return sources;
+}
+
+function extractBody(content) {
+  if (!content.startsWith('---')) return content;
+  const end = content.indexOf('---', 3);
+  if (end < 0) return content;
+  return content.slice(end + 3).trim();
+}
+
+function beliefToMarkdown(b) {
+  const srcs = (b.sources && b.sources.length) ? b.sources.map(s => `  - ${s}`).join('\n') : '  - unknown';
+  const derived = (b.derived_from && b.derived_from.length) ? b.derived_from.map(d => `  - ${d}`).join('\n') : '  - system';
+  return `---\nclaim_id: ${b.claim_id}\nentity: ${b.entity}\nstatus: ${b.status}\nconfidence: ${b.confidence}\nsources:\n${srcs}\nlast_checked: ${b.last_checked}\nderived_from:\n${derived}\n---\n\n# ${b.title || b.entity}\n\n${b.body}\n`;
+}
+
+class VaultManager {
+  constructor(basePath) {
+    this._base = basePath || path.join(process.cwd(), '.entroly', 'vault');
+    this._initialized = false;
+  }
+
+  ensureStructure() {
+    if (this._initialized) return { status: 'already_initialized', path: this._base };
+    const created = [];
+    for (const d of VAULT_DIRS) {
+      const p = path.join(this._base, d);
+      if (!fs.existsSync(p)) { fs.mkdirSync(p, { recursive: true }); created.push(d); }
+    }
+    const skillsDir = path.join(this._base, 'evolution', 'skills');
+    if (!fs.existsSync(skillsDir)) { fs.mkdirSync(skillsDir, { recursive: true }); created.push('evolution/skills'); }
+    const reg = path.join(this._base, 'evolution', 'registry.md');
+    if (!fs.existsSync(reg)) {
+      fs.writeFileSync(reg, '# Skill Registry\n\nIndex of all dynamically generated skills.\n\n| Skill ID | Status | Created | Description |\n|---|---|---|---|\n', 'utf-8');
+      created.push('evolution/registry.md');
+    }
+    this._initialized = true;
+    return { status: 'initialized', path: this._base, created };
+  }
+
+  writeBelief(artifact) {
+    this.ensureStructure();
+    const safe = safeFilename(artifact.entity || artifact.claim_id);
+    const fp = path.join(this._base, 'beliefs', `${safe}.md`);
+    fs.writeFileSync(fp, beliefToMarkdown(artifact), 'utf-8');
+    return { status: 'written', directory: 'beliefs', path: fp, claim_id: artifact.claim_id, entity: artifact.entity };
+  }
+
+  readBelief(entity) {
+    this.ensureStructure();
+    const beliefsDir = path.join(this._base, 'beliefs');
+    const safe = safeFilename(entity);
+    let fp = path.join(beliefsDir, `${safe}.md`);
+    if (!fs.existsSync(fp)) {
+      const files = this._globBeliefs();
+      const match = files.find(f => path.basename(f, '.md').toLowerCase().includes(entity.toLowerCase()));
+      if (!match) return null;
+      fp = match;
+    }
+    const content = fs.readFileSync(fp, 'utf-8');
+    return { path: fp, frontmatter: parseFrontmatter(content) || {}, body: extractBody(content) };
+  }
+
+  listBeliefs() {
+    this.ensureStructure();
+    const results = [];
+    for (const fp of this._globBeliefs()) {
+      try {
+        const content = fs.readFileSync(fp, 'utf-8');
+        const fm = parseFrontmatter(content);
+        const beliefsDir = path.join(this._base, 'beliefs');
+        results.push({
+          file: path.relative(beliefsDir, fp),
+          entity: fm ? (fm.entity || path.basename(fp, '.md')) : path.basename(fp, '.md'),
+          status: fm ? (fm.status || 'unknown') : 'unknown',
+          confidence: fm ? parseFloat(fm.confidence || '0') : 0,
+          last_checked: fm ? (fm.last_checked || '') : '',
+        });
+      } catch {}
+    }
+    return results;
+  }
+
+  coverageIndex() {
+    const beliefs = this.listBeliefs();
+    const total = beliefs.length;
+    const verified = beliefs.filter(b => b.status === 'verified').length;
+    const stale = beliefs.filter(b => b.status === 'stale').length;
+    const avg = total ? beliefs.reduce((a, b) => a + b.confidence, 0) / total : 0;
+    return { total_beliefs: total, verified, stale, inferred: total - verified - stale, average_confidence: Math.round(avg * 1000) / 1000, entities: beliefs.map(b => b.entity) };
+  }
+
+  writeVerification(artifact) {
+    this.ensureStructure();
+    const ts = timestamp();
+    const safe = safeFilename(artifact.title || artifact.challenges || 'check');
+    const fp = path.join(this._base, 'verification', `${ts}_${safe}.md`);
+    const md = `---\nchallenges: ${artifact.challenges}\nresult: ${artifact.result}\nconfidence_delta: ${artifact.confidence_delta >= 0 ? '+' : ''}${artifact.confidence_delta.toFixed(2)}\nchecked_at: ${artifact.checked_at || nowISO()}\nmethod: ${artifact.method || ''}\n---\n\n# ${artifact.title || ''}\n\n${artifact.body || ''}\n`;
+    fs.writeFileSync(fp, md, 'utf-8');
+    if (artifact.result === 'confirmed' && artifact.challenges) {
+      this._updateBeliefConfidence(artifact.challenges, artifact.confidence_delta);
+    }
+    return { status: 'written', directory: 'verification', path: fp, challenges: artifact.challenges, result: artifact.result };
+  }
+
+  writeAction(title, content, actionType = 'report') {
+    this.ensureStructure();
+    const ts = timestamp();
+    const safe = safeFilename(title);
+    const fp = path.join(this._base, 'actions', `${ts}_${safe}.md`);
+    fs.writeFileSync(fp, `---\ntype: ${actionType}\ntimestamp: ${ts}\n---\n\n# ${title}\n\n${content}\n`, 'utf-8');
+    return { status: 'written', directory: 'actions', path: fp, type: actionType };
+  }
+
+  markBeliefsStaleForFiles(changedFiles) {
+    this.ensureStructure();
+    const changedPaths = new Set(changedFiles.map(f => f.replace(/\\/g, '/').toLowerCase()));
+    const changedStems = new Set(changedFiles.map(f => path.basename(f).replace(/\.[^.]+$/, '').toLowerCase()));
+    const updatedEntities = [], updatedFiles = [], alreadyStale = [];
+    for (const fp of this._globBeliefs()) {
+      try {
+        let content = fs.readFileSync(fp, 'utf-8');
+        const fm = parseFrontmatter(content);
+        if (!fm) continue;
+        const entity = fm.entity || path.basename(fp, '.md');
+        const sources = extractSources(content);
+        let matched = sources.some(src => {
+          const sp = src.split(':')[0].replace(/\\/g, '/').toLowerCase();
+          return changedPaths.has(sp) || changedStems.has(path.basename(sp).replace(/\.[^.]+$/, ''));
+        });
+        if (!matched) matched = [...changedStems].some(stem => entity.toLowerCase().includes(stem));
+        if (!matched) continue;
+        if (fm.status === 'stale') { alreadyStale.push(entity); continue; }
+        content = content.replace(/^status:\s+.+$/m, 'status: stale');
+        fs.writeFileSync(fp, content, 'utf-8');
+        updatedEntities.push(entity);
+        updatedFiles.push(fp);
+      } catch {}
+    }
+    return { status: 'updated', changed_files: changedFiles.length, updated_entities: updatedEntities, updated_files: updatedFiles, already_stale: alreadyStale };
+  }
+
+  _updateBeliefConfidence(claimId, delta) {
+    for (const fp of this._globBeliefs()) {
+      try {
+        let content = fs.readFileSync(fp, 'utf-8');
+        const fm = parseFrontmatter(content);
+        if (!fm || fm.claim_id !== claimId) continue;
+        const oldConf = parseFloat(fm.confidence || '0.5');
+        const newConf = Math.max(0, Math.min(1, oldConf + delta));
+        content = content.replace(`confidence: ${fm.confidence}`, `confidence: ${newConf}`);
+        if (delta > 0 && content.includes('status: inferred')) content = content.replace('status: inferred', 'status: verified');
+        content = content.replace(/last_checked: .+/, `last_checked: ${nowISO()}`);
+        fs.writeFileSync(fp, content, 'utf-8');
+        break;
+      } catch {}
+    }
+  }
+
+  _globBeliefs() {
+    const dir = path.join(this._base, 'beliefs');
+    if (!fs.existsSync(dir)) return [];
+    return this._rglob(dir, '.md');
+  }
+
+  _rglob(dir, ext) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) results.push(...this._rglob(full, ext));
+      else if (entry.name.endsWith(ext)) results.push(full);
+    }
+    return results.sort();
+  }
+}
+
+module.exports = {
+  VaultManager, safeFilename, parseFrontmatter, extractSources, extractBody,
+  beliefToMarkdown, nowISO, timestamp, SOURCE_EXTS,
+};

package/js/vault_observer.js

@@ -0,0 +1,129 @@
+/**
+ * VaultObserver — derive self-evolution stats from the on-disk vault.
+ *
+ * The vault IS the state machine. Whichever runtime (pip or npm) is
+ * actually running the daemon, the effects land here:
+ *
+ *   evolution/skills/<id>/SKILL.md      (status: draft|promoted|pruned)
+ *   evolution/skills/<id>/metrics.json  (fitness, runs, successes)
+ *   evolution/gap_*.md                  (pending gaps)
+ *   value_tracker.json (in data dir)    (budget + savings)
+ *
+ * This observer reads them. It exposes the same `.stats()` shape the
+ * gateways expect, so you can do:
+ *
+ *   const obs = new VaultObserver('.entroly/vault');
+ *   new TelegramGateway({ token, chatId }).attach(obs).start();
+ *
+ * No daemon required. No duplicated orchestration logic. Works
+ * whether the Python or Node runtime owns the vault.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return {};
+  const end = text.indexOf('\n---', 3);
+  if (end < 0) return {};
+  const meta = {};
+  for (const line of text.slice(3, end).split('\n')) {
+    const i = line.indexOf(':');
+    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return meta;
+}
+
+class VaultObserver {
+  /**
+   * @param {string} vaultPath - Path to the vault root (default: .entroly/vault)
+   * @param {object} opts
+   * @param {string} opts.dataDir - Where value_tracker.json lives (default: ~/.entroly)
+   */
+  constructor(vaultPath = '.entroly/vault', opts = {}) {
+    this._vault = vaultPath;
+    this._dataDir = opts.dataDir || path.join(os.homedir(), '.entroly');
+  }
+
+  // ── Derived state ──────────────────────────────────────────
+
+  _listSkills() {
+    const dir = path.join(this._vault, 'evolution', 'skills');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .map(name => {
+        const sdir = path.join(dir, name);
+        const skillMd = path.join(sdir, 'SKILL.md');
+        if (!fs.existsSync(skillMd)) return null;
+        const meta = parseFrontmatter(fs.readFileSync(skillMd, 'utf8'));
+        let metrics = {};
+        const mp = path.join(sdir, 'metrics.json');
+        if (fs.existsSync(mp)) {
+          try { metrics = JSON.parse(fs.readFileSync(mp, 'utf8')); } catch (_) {}
+        }
+        return { id: name, status: meta.status || 'draft', entity: meta.entity || '', metrics };
+      })
+      .filter(Boolean);
+  }
+
+  _listGaps() {
+    const dir = path.join(this._vault, 'evolution');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter(f => f.startsWith('gap_') && f.endsWith('.md'));
+  }
+
+  _readValueTracker() {
+    const p = path.join(this._dataDir, 'value_tracker.json');
+    if (!fs.existsSync(p)) return null;
+    try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+    catch (_) { return null; }
+  }
+
+  _readRegistry() {
+    const p = path.join(this._vault, 'evolution', 'registry.md');
+    return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  }
+
+  // ── Public API (matches EvolutionDaemon.stats() shape) ─────
+
+  stats() {
+    const skills = this._listSkills();
+    const promoted = skills.filter(s => s.status === 'promoted').length;
+    const pruned = skills.filter(s => s.status === 'pruned').length;
+    const structuralSuccesses = skills.filter(s =>
+      (s.metrics && s.metrics.fitness_score >= 0.5)
+    ).length;
+
+    const vt = this._readValueTracker();
+    const lifetimeSaved = vt ? (vt.lifetime?.cost_saved_usd || 0) : 0;
+    const evolutionSpent = vt ? (vt.lifetime?.evolution_spent_usd || 0) : 0;
+    const earned = lifetimeSaved * 0.05;
+    const available = Math.max(0, earned - evolutionSpent);
+
+    return {
+      running: true,
+      skills_promoted: promoted,
+      skills_pruned: pruned,
+      structural_successes: structuralSuccesses,
+      dream_cycles: 0,  // not observable from vault alone
+      gaps_pending: this._listGaps().length,
+      budget: {
+        available_usd: +available.toFixed(6),
+        total_earned_usd: +earned.toFixed(6),
+        total_spent_usd: +evolutionSpent.toFixed(6),
+        can_evolve: available > 0.001,
+      },
+    };
+  }
+
+  /** Raw accessors for gateway command handlers (/skills, /gaps, /status). */
+  skills() { return this._listSkills(); }
+  gaps() { return this._listGaps(); }
+  registry() { return this._readRegistry(); }
+  budget() { return this.stats().budget; }
+}
+
+module.exports = { VaultObserver };