@soleri/core 2.4.0 → 2.6.0

package/src/__tests__/template-manager.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { parseVariables, resolveIncludes } from '../prompts/parser.js';
+import { TemplateManager } from '../prompts/template-manager.js';
+
+// ─── parseVariables ───────────────────────────────────────────────────
+
+describe('parseVariables', () => {
+  it('extracts required variable', () => {
+    const vars = parseVariables('Hello {{name}}');
+    expect(vars).toHaveLength(1);
+    expect(vars[0]).toEqual({ name: 'name', required: true, defaultValue: undefined });
+  });
+
+  it('extracts variable with default', () => {
+    const vars = parseVariables('Hello {{name:World}}');
+    expect(vars).toHaveLength(1);
+    expect(vars[0]).toEqual({ name: 'name', required: false, defaultValue: 'World' });
+  });
+
+  it('extracts multiple unique variables', () => {
+    const vars = parseVariables('{{greeting}} {{name}}, welcome to {{place}}');
+    expect(vars).toHaveLength(3);
+    expect(vars.map((v) => v.name)).toEqual(['greeting', 'name', 'place']);
+  });
+
+  it('deduplicates same variable', () => {
+    const vars = parseVariables('{{name}} and {{name}} again');
+    expect(vars).toHaveLength(1);
+  });
+
+  it('handles empty default', () => {
+    const vars = parseVariables('{{opt:}}');
+    expect(vars[0]).toEqual({ name: 'opt', required: false, defaultValue: '' });
+  });
+
+  it('returns empty for no variables', () => {
+    expect(parseVariables('plain text')).toEqual([]);
+  });
+
+  it('handles mixed required and optional', () => {
+    const vars = parseVariables('{{required}} and {{optional:fallback}}');
+    expect(vars).toHaveLength(2);
+    expect(vars[0].required).toBe(true);
+    expect(vars[1].required).toBe(false);
+    expect(vars[1].defaultValue).toBe('fallback');
+  });
+});
+
+// ─── resolveIncludes ──────────────────────────────────────────────────
+
+describe('resolveIncludes', () => {
+  it('resolves single include', () => {
+    const result = resolveIncludes('before @include(header) after', (name) => {
+      if (name === 'header') return 'HEADER';
+      return '';
+    });
+    expect(result).toBe('before HEADER after');
+  });
+
+  it('resolves nested includes', () => {
+    const result = resolveIncludes('start @include(a)', (name) => {
+      if (name === 'a') return 'A @include(b)';
+      if (name === 'b') return 'B';
+      return '';
+    });
+    expect(result).toBe('start A B');
+  });
+
+  it('detects circular includes', () => {
+    expect(() =>
+      resolveIncludes('@include(a)', (name) => {
+        if (name === 'a') return '@include(b)';
+        if (name === 'b') return '@include(a)';
+        return '';
+      }),
+    ).toThrow(/Circular include detected/);
+  });
+
+  it('throws on depth exceeding 10', () => {
+    // Each level includes a unique name so cycle detection doesn't fire
+    let counter = 0;
+    expect(() =>
+      resolveIncludes('@include(level0)', (name) => {
+        counter++;
+        return `@include(level${counter})`;
+      }),
+    ).toThrow(/Include depth exceeded/);
+  });
+
+  it('handles no includes', () => {
+    const result = resolveIncludes('no includes here', () => '');
+    expect(result).toBe('no includes here');
+  });
+
+  it('handles multiple includes', () => {
+    const result = resolveIncludes('@include(a) + @include(b)', (name) => name.toUpperCase());
+    expect(result).toBe('A + B');
+  });
+});
+
+// ─── TemplateManager ──────────────────────────────────────────────────
+
+describe('TemplateManager', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `templates-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads .prompt files from directory', () => {
+    writeFileSync(join(tempDir, 'greeting.prompt'), 'Hello {{name}}!');
+    writeFileSync(join(tempDir, 'farewell.prompt'), 'Goodbye {{name}}.');
+    writeFileSync(join(tempDir, 'not-a-template.txt'), 'ignored');
+
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    expect(mgr.listTemplates().sort()).toEqual(['farewell', 'greeting']);
+  });
+
+  it('handles nonexistent directory gracefully', () => {
+    const mgr = new TemplateManager('/nonexistent/path');
+    mgr.load(); // should not throw
+    expect(mgr.listTemplates()).toEqual([]);
+  });
+
+  it('renders template with variables', () => {
+    writeFileSync(join(tempDir, 'hello.prompt'), 'Hello {{name}}, you are {{role}}!');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    const result = mgr.render('hello', { name: 'Atlas', role: 'advisor' });
+    expect(result).toBe('Hello Atlas, you are advisor!');
+  });
+
+  it('uses default values', () => {
+    writeFileSync(join(tempDir, 'hello.prompt'), 'Hello {{name:World}}!');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    expect(mgr.render('hello', {})).toBe('Hello World!');
+    expect(mgr.render('hello', { name: 'Custom' })).toBe('Hello Custom!');
+  });
+
+  it('throws on missing required variable in strict mode', () => {
+    writeFileSync(join(tempDir, 'strict.prompt'), '{{required}}');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    expect(() => mgr.render('strict', {})).toThrow(/Missing required variable: required/);
+  });
+
+  it('leaves placeholder in non-strict mode', () => {
+    writeFileSync(join(tempDir, 'lax.prompt'), 'Hello {{name}}!');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    const result = mgr.render('lax', {}, { strict: false });
+    expect(result).toBe('Hello {{name}}!');
+  });
+
+  it('resolves @include directives', () => {
+    writeFileSync(join(tempDir, 'header.prompt'), '--- HEADER ---');
+    writeFileSync(join(tempDir, 'page.prompt'), '@include(header)\nContent here.');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    const result = mgr.render('page', {});
+    expect(result).toBe('--- HEADER ---\nContent here.');
+  });
+
+  it('throws on missing include', () => {
+    writeFileSync(join(tempDir, 'broken.prompt'), '@include(nonexistent)');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    expect(() => mgr.render('broken', {})).toThrow(/Include not found: nonexistent/);
+  });
+
+  it('throws on nonexistent template name', () => {
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    expect(() => mgr.render('missing', {})).toThrow(/Template not found: missing/);
+  });
+
+  it('getTemplate returns raw template', () => {
+    writeFileSync(join(tempDir, 'raw.prompt'), 'Raw {{content}}');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    const tmpl = mgr.getTemplate('raw');
+    expect(tmpl).not.toBeNull();
+    expect(tmpl!.name).toBe('raw');
+    expect(tmpl!.content).toBe('Raw {{content}}');
+    expect(tmpl!.variables).toHaveLength(1);
+  });
+
+  it('getTemplate returns null for nonexistent', () => {
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+    expect(mgr.getTemplate('nope')).toBeNull();
+  });
+
+  it('variables in included templates get substituted', () => {
+    writeFileSync(join(tempDir, 'partial.prompt'), 'I am {{name}}');
+    writeFileSync(join(tempDir, 'main.prompt'), 'Hello: @include(partial)!');
+    const mgr = new TemplateManager(tempDir);
+    mgr.load();
+
+    const result = mgr.render('main', { name: 'Atlas' });
+    expect(result).toBe('Hello: I am Atlas!');
+  });
+});

package/src/__tests__/vault-extra-ops.test.ts

@@ -47,8 +47,8 @@ describe('createVaultExtraOps', () => {
     return op;
   }
 
-  it('should return 12 ops', () => {
-    expect(ops.length).toBe(12);
+  it('should return 23 ops', () => {
+    expect(ops.length).toBe(23);
   });
 
   it('should have all expected op names', () => {
@@ -65,6 +65,17 @@ describe('createVaultExtraOps', () => {
     expect(names).toContain('vault_seed');
     expect(names).toContain('vault_backup');
     expect(names).toContain('vault_age_report');
+    // #153: Seed canonical
+    expect(names).toContain('vault_seed_canonical');
+    // #155: Knowledge lifecycle
+    expect(names).toContain('knowledge_audit');
+    expect(names).toContain('knowledge_health');
+    expect(names).toContain('knowledge_merge');
+    expect(names).toContain('knowledge_reorganize');
+    // #89: Bi-temporal
+    expect(names).toContain('vault_set_temporal');
+    expect(names).toContain('vault_find_expiring');
+    expect(names).toContain('vault_find_expired');
   });
 
   // ─── vault_get ────────────────────────────────────────────────────
@@ -357,10 +368,7 @@ describe('createVaultExtraOps', () => {
   // ─── vault_age_report ─────────────────────────────────────────────
 
   it('vault_age_report should return age distribution', async () => {
-    runtime.vault.seed([
-      makeEntry({ id: 'va-1' }),
-      makeEntry({ id: 'va-2' }),
-    ]);
+    runtime.vault.seed([makeEntry({ id: 'va-1' }), makeEntry({ id: 'va-2' })]);
     const result = (await findOp('vault_age_report').handler({})) as {
       total: number;
       buckets: Array<{ label: string; count: number; minDays: number; maxDays: number }>;
@@ -390,7 +398,14 @@ describe('createVaultExtraOps', () => {
   // ─── Auth levels ──────────────────────────────────────────────────
 
   it('should assign correct auth levels', () => {
-    const readOps = ['vault_get', 'vault_tags', 'vault_domains', 'vault_recent', 'vault_backup', 'vault_age_report'];
+    const readOps = [
+      'vault_get',
+      'vault_tags',
+      'vault_domains',
+      'vault_recent',
+      'vault_backup',
+      'vault_age_report',
+    ];
     const writeOps = ['vault_update', 'vault_bulk_add', 'vault_import', 'vault_seed'];
     const adminOps = ['vault_remove', 'vault_bulk_remove'];
 
@@ -404,4 +419,64 @@ describe('createVaultExtraOps', () => {
       expect(findOp(name).auth).toBe('admin');
     }
   });
+
+  // ─── vault_set_temporal ─────────────────────────────────────────
+
+  describe('vault_set_temporal', () => {
+    it('should set validUntil on an entry', async () => {
+      runtime.vault.seed([makeEntry({ id: 'temporal-1' })]);
+      const result = (await findOp('vault_set_temporal').handler({
+        id: 'temporal-1',
+        validUntil: Math.floor(Date.now() / 1000) + 86400 * 30,
+      })) as { updated: boolean; id: string; validUntil: number | null };
+      expect(result.updated).toBe(true);
+      expect(result.id).toBe('temporal-1');
+      expect(result.validUntil).toBeGreaterThan(0);
+    });
+
+    it('should return error for missing entry', async () => {
+      const result = (await findOp('vault_set_temporal').handler({
+        id: 'nonexistent',
+        validUntil: 1000,
+      })) as { error: string };
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  // ─── vault_find_expiring ────────────────────────────────────────
+
+  describe('vault_find_expiring', () => {
+    it('should find entries expiring within N days', async () => {
+      const now = Math.floor(Date.now() / 1000);
+      runtime.vault.seed([
+        makeEntry({ id: 'exp-1' }),
+        makeEntry({ id: 'exp-2' }),
+        makeEntry({ id: 'exp-3' }),
+      ]);
+      runtime.vault.setTemporal('exp-1', undefined, now + 86400 * 5);
+      runtime.vault.setTemporal('exp-2', undefined, now + 86400 * 60);
+
+      const result = (await findOp('vault_find_expiring').handler({
+        withinDays: 10,
+      })) as { entries: unknown[]; count: number };
+      expect(result.count).toBe(1);
+    });
+  });
+
+  // ─── vault_find_expired ─────────────────────────────────────────
+
+  describe('vault_find_expired', () => {
+    it('should find expired entries', async () => {
+      const now = Math.floor(Date.now() / 1000);
+      runtime.vault.seed([makeEntry({ id: 'past-1' }), makeEntry({ id: 'past-2' })]);
+      runtime.vault.setTemporal('past-1', undefined, now - 86400);
+      runtime.vault.setTemporal('past-2', undefined, now + 86400);
+
+      const result = (await findOp('vault_find_expired').handler({})) as {
+        entries: unknown[];
+        count: number;
+      };
+      expect(result.count).toBe(1);
+    });
+  });
 });

package/src/__tests__/vault.test.ts

@@ -491,4 +491,188 @@ describe('Vault', () => {
       expect(stats.byProject).toEqual({ '/a': 2, '/b': 1 });
     });
   });
+
+  describe('Vault archival and optimization', () => {
+    it('archive moves old entries', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'old-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Old Pattern',
+          severity: 'suggestion',
+          description: 'Old entry',
+          tags: ['test'],
+        },
+      ]);
+      // Manually set the updated_at to 200 days ago
+      v.getProvider().run('UPDATE entries SET updated_at = ? WHERE id = ?', [
+        Math.floor(Date.now() / 1000) - 200 * 86400,
+        'old-1',
+      ]);
+      v.seed([
+        {
+          id: 'new-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'New Pattern',
+          severity: 'suggestion',
+          description: 'New entry',
+          tags: ['test'],
+        },
+      ]);
+
+      const result = v.archive({ olderThanDays: 90 });
+      expect(result.archived).toBe(1);
+      expect(v.get('old-1')).toBeNull();
+      expect(v.get('new-1')).not.toBeNull();
+      v.close();
+    });
+
+    it('archive respects olderThanDays', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'e1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Entry',
+          severity: 'suggestion',
+          description: 'Not old enough',
+          tags: ['test'],
+        },
+      ]);
+      // Entry is fresh (just created), archive with 1 day threshold
+      const result = v.archive({ olderThanDays: 1 });
+      expect(result.archived).toBe(0);
+      expect(v.get('e1')).not.toBeNull();
+      v.close();
+    });
+
+    it('archive returns 0 when no candidates', () => {
+      const v = new Vault(':memory:');
+      const result = v.archive({ olderThanDays: 30 });
+      expect(result.archived).toBe(0);
+      v.close();
+    });
+
+    it('archived entries excluded from search', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'search-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Searchable Pattern',
+          severity: 'suggestion',
+          description: 'Should be archived',
+          tags: ['search'],
+        },
+      ]);
+      v.getProvider().run('UPDATE entries SET updated_at = ? WHERE id = ?', [
+        Math.floor(Date.now() / 1000) - 200 * 86400,
+        'search-1',
+      ]);
+
+      // Before archive: should appear in search
+      const before = v.search('searchable');
+      expect(before.length).toBeGreaterThan(0);
+
+      v.archive({ olderThanDays: 90 });
+
+      // After archive: should not appear
+      const after = v.search('searchable');
+      expect(after.length).toBe(0);
+      v.close();
+    });
+
+    it('restore brings entry back', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'restore-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Restore Me',
+          severity: 'suggestion',
+          description: 'Will be restored',
+          tags: ['test'],
+        },
+      ]);
+      v.getProvider().run('UPDATE entries SET updated_at = ? WHERE id = ?', [
+        Math.floor(Date.now() / 1000) - 200 * 86400,
+        'restore-1',
+      ]);
+      v.archive({ olderThanDays: 90 });
+      expect(v.get('restore-1')).toBeNull();
+
+      const restored = v.restore('restore-1');
+      expect(restored).toBe(true);
+      expect(v.get('restore-1')).not.toBeNull();
+      expect(v.get('restore-1')!.title).toBe('Restore Me');
+      v.close();
+    });
+
+    it('restore returns false for missing id', () => {
+      const v = new Vault(':memory:');
+      const result = v.restore('nonexistent');
+      expect(result).toBe(false);
+      v.close();
+    });
+
+    it('restored entry appears in search', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'search-restore',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Unique Findable Pattern',
+          severity: 'suggestion',
+          description: 'Will be found after restore',
+          tags: ['test'],
+        },
+      ]);
+      v.getProvider().run('UPDATE entries SET updated_at = ? WHERE id = ?', [
+        Math.floor(Date.now() / 1000) - 200 * 86400,
+        'search-restore',
+      ]);
+      v.archive({ olderThanDays: 90 });
+      v.restore('search-restore');
+
+      const results = v.search('unique findable');
+      expect(results.length).toBeGreaterThan(0);
+      v.close();
+    });
+
+    it('optimize runs without error', () => {
+      const v = new Vault(':memory:');
+      v.seed([
+        {
+          id: 'opt-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Optimize Test',
+          severity: 'suggestion',
+          description: 'For optimization',
+          tags: ['test'],
+        },
+      ]);
+
+      expect(() => v.optimize()).not.toThrow();
+      v.close();
+    });
+
+    it('optimize returns status', () => {
+      const v = new Vault(':memory:');
+      const status = v.optimize();
+      expect(status).toHaveProperty('vacuumed');
+      expect(status).toHaveProperty('analyzed');
+      expect(status).toHaveProperty('ftsRebuilt');
+      // SQLite backend should analyze and rebuild FTS
+      expect(status.analyzed).toBe(true);
+      v.close();
+    });
+  });
 });

package/src/brain/brain.ts

@@ -47,7 +47,7 @@ const DEFAULT_WEIGHTS: ScoringWeights = {
   semantic: 0.4,
   vector: 0.0,
   severity: 0.15,
-  recency: 0.15,
+  temporalDecay: 0.15,
   tagOverlap: 0.15,
   domainMatch: 0.15,
 };
@@ -56,7 +56,7 @@ const COGNEE_WEIGHTS: ScoringWeights = {
   semantic: 0.25,
   vector: 0.35,
   severity: 0.1,
-  recency: 0.1,
+  temporalDecay: 0.1,
   tagOverlap: 0.1,
   domainMatch: 0.1,
 };
@@ -454,6 +454,42 @@ export class Brain {
     return this.vocabulary.size;
   }
 
+  async getDecayReport(
+    query: string,
+    limit: number = 10,
+  ): Promise<
+    Array<{
+      id: string;
+      title: string;
+      decayScore: number;
+      validUntil: number | null;
+      status: 'active' | 'expiring' | 'expired';
+    }>
+  > {
+    const results = await this.intelligentSearch(query, { limit });
+    const now = Math.floor(Date.now() / 1000);
+    return results.map((r) => {
+      const validUntil = r.entry.validUntil ?? null;
+      let status: 'active' | 'expiring' | 'expired' = 'active';
+      if (validUntil) {
+        if (validUntil <= now) status = 'expired';
+        else {
+          const validFrom = r.entry.validFrom ?? now;
+          const totalWindow = validUntil - validFrom;
+          const remaining = validUntil - now;
+          if (remaining <= totalWindow * 0.25) status = 'expiring';
+        }
+      }
+      return {
+        id: r.entry.id,
+        title: r.entry.title,
+        decayScore: r.breakdown.temporalDecay,
+        validUntil,
+        status,
+      };
+    });
+  }
+
   // ─── Private methods ─────────────────────────────────────────────
 
   private scoreEntry(
@@ -483,9 +519,7 @@ export class Brain {
 
     const severity = SEVERITY_SCORES[entry.severity] ?? 0.4;
 
-    const entryAge = now - (entry as unknown as { created_at?: number }).created_at!;
-    const halfLifeSeconds = RECENCY_HALF_LIFE_DAYS * 86400;
-    const recency = entryAge > 0 ? Math.exp((-Math.LN2 * entryAge) / halfLifeSeconds) : 1;
+    const temporalDecay = computeTemporalDecay(entry, now);
 
     const tagOverlap = queryTags.length > 0 ? jaccardSimilarity(queryTags, entry.tags) : 0;
 
@@ -497,11 +531,11 @@ export class Brain {
       w.semantic * semantic +
       w.vector * vector +
       w.severity * severity +
-      w.recency * recency +
+      w.temporalDecay * temporalDecay +
       w.tagOverlap * tagOverlap +
       w.domainMatch * domainMatch;
 
-    return { semantic, vector, severity, recency, tagOverlap, domainMatch, total };
+    return { semantic, vector, severity, temporalDecay, tagOverlap, domainMatch, total };
   }
 
   private generateTags(title: string, description: string, context?: string): string[] {
@@ -640,12 +674,12 @@ export class Brain {
     const remaining = 1.0 - newWeights.semantic - newWeights.vector;
     const otherSum =
       DEFAULT_WEIGHTS.severity +
-      DEFAULT_WEIGHTS.recency +
+      DEFAULT_WEIGHTS.temporalDecay +
       DEFAULT_WEIGHTS.tagOverlap +
       DEFAULT_WEIGHTS.domainMatch;
     const scale = remaining / otherSum;
     newWeights.severity = DEFAULT_WEIGHTS.severity * scale;
-    newWeights.recency = DEFAULT_WEIGHTS.recency * scale;
+    newWeights.temporalDecay = DEFAULT_WEIGHTS.temporalDecay * scale;
     newWeights.tagOverlap = DEFAULT_WEIGHTS.tagOverlap * scale;
     newWeights.domainMatch = DEFAULT_WEIGHTS.domainMatch * scale;
 
@@ -653,6 +687,34 @@ export class Brain {
   }
 }
 
+function computeTemporalDecay(entry: IntelligenceEntry, now: number): number {
+  const entryRecord = entry as unknown as {
+    created_at?: number;
+    updated_at?: number;
+    valid_until?: number;
+    valid_from?: number;
+  };
+  const validUntil = entry.validUntil ?? entryRecord.valid_until;
+
+  if (!validUntil) {
+    // No expiry — use existing age-based exponential decay
+    const updatedAt = entryRecord.updated_at ?? entryRecord.created_at ?? now;
+    const ageSeconds = now - updatedAt;
+    const halfLifeSeconds = RECENCY_HALF_LIFE_DAYS * 86400;
+    return ageSeconds > 0 ? Math.exp((-Math.LN2 * ageSeconds) / halfLifeSeconds) : 1;
+  }
+
+  // With valid_until: linear ramp-down in last 25% of validity window
+  const validFrom = entry.validFrom ?? entryRecord.valid_from ?? entryRecord.created_at ?? now;
+  const totalWindow = validUntil - validFrom;
+  const remaining = validUntil - now;
+  if (remaining <= 0) return 0; // expired
+  if (totalWindow <= 0) return 1; // edge case: bad data
+  const decayZone = totalWindow * 0.25;
+  if (remaining > decayZone) return 1.0; // fully valid
+  return remaining / decayZone; // linear decay in last quarter
+}
+
 function clamp(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value));
 }