@soleri/core 2.7.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/core",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Shared engine for Soleri agents — vault, brain, planner, LLM utilities, and facade infrastructure.",
   "keywords": [
     "agent",

package/src/__tests__/content-hash.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { computeContentHash } from '../vault/content-hash.js';
+
+describe('computeContentHash', () => {
+  const base = {
+    type: 'pattern',
+    domain: 'testing',
+    title: 'Test Pattern',
+    description: 'A test pattern.',
+    tags: ['a', 'b'],
+  };
+
+  it('returns 40-char hex string', () => {
+    const hash = computeContentHash(base);
+    expect(hash).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('is deterministic', () => {
+    expect(computeContentHash(base)).toBe(computeContentHash(base));
+  });
+
+  it('normalizes tag order', () => {
+    const a = computeContentHash({ ...base, tags: ['b', 'a'] });
+    const b = computeContentHash({ ...base, tags: ['a', 'b'] });
+    expect(a).toBe(b);
+  });
+
+  it('normalizes whitespace', () => {
+    const a = computeContentHash(base);
+    const b = computeContentHash({
+      ...base,
+      title: '  Test Pattern  ',
+      description: '  A test pattern.  ',
+    });
+    expect(a).toBe(b);
+  });
+
+  it('normalizes domain case', () => {
+    const a = computeContentHash(base);
+    const b = computeContentHash({ ...base, domain: 'TESTING' });
+    expect(a).toBe(b);
+  });
+
+  it('different content produces different hash', () => {
+    const a = computeContentHash(base);
+    const b = computeContentHash({ ...base, title: 'Different' });
+    expect(a).not.toBe(b);
+  });
+
+  it('handles missing optional fields', () => {
+    const hash = computeContentHash({ type: 'rule', domain: 'd', title: 't', description: 'd' });
+    expect(hash).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('example and counterExample affect hash', () => {
+    const a = computeContentHash({ ...base, example: 'do this' });
+    const b = computeContentHash({ ...base, example: 'do that' });
+    expect(a).not.toBe(b);
+  });
+});

package/src/__tests__/core-ops.test.ts

@@ -3,11 +3,11 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
 
-describe('createCoreOps', () => {
+describe('createSemanticFacades', () => {
   let runtime: AgentRuntime;
   let ops: OpDefinition[];
   let plannerDir: string;
@@ -20,7 +20,7 @@ describe('createCoreOps', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {
@@ -34,8 +34,8 @@ describe('createCoreOps', () => {
     return op;
   }
 
-  it('should return 207 ops', () => {
-    expect(ops.length).toBe(207);
+  it('should return 209 ops', () => {
+    expect(ops.length).toBe(209);
   });
 
   it('should have all expected op names', () => {
@@ -159,6 +159,9 @@ describe('createCoreOps', () => {
     expect(names).toContain('vault_archive');
     expect(names).toContain('vault_restore');
     expect(names).toContain('vault_optimize');
+    // Vault content hashing (#166)
+    expect(names).toContain('vault_content_hash');
+    expect(names).toContain('vault_dedup_status');
     // Admin (8)
     expect(names).toContain('admin_health');
     expect(names).toContain('admin_tool_list');
@@ -264,7 +267,7 @@ describe('createCoreOps', () => {
     runtime.brain.rebuildVocabulary();
 
     // Re-create ops since brain state changed
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
     const results = (await findOp('search').handler({ query: 'core ops test' })) as unknown[];
     expect(results.length).toBeGreaterThan(0);
   });
@@ -371,7 +374,7 @@ describe('createCoreOps', () => {
         tags: ['test'],
       },
     ]);
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
     const result = (await findOp('brain_feedback').handler({
       query: 'test',
       entryId: 'bf-1',

package/src/__tests__/extensions.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from 'vitest';
+import { wrapWithMiddleware } from '../extensions/middleware.js';
+import type { FacadeConfig } from '../facades/types.js';
+import type { OpMiddleware, AgentExtensions } from '../extensions/types.js';
+
+describe('extensions', () => {
+  describe('AgentExtensions type', () => {
+    it('should accept empty extensions', () => {
+      const ext: AgentExtensions = {};
+      expect(ext.ops).toBeUndefined();
+      expect(ext.facades).toBeUndefined();
+      expect(ext.middleware).toBeUndefined();
+      expect(ext.hooks).toBeUndefined();
+    });
+
+    it('should accept extensions with ops', () => {
+      const ext: AgentExtensions = {
+        ops: [
+          {
+            name: 'custom_op',
+            description: 'A custom op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+      expect(ext.ops).toHaveLength(1);
+    });
+
+    it('should accept extensions with facades', () => {
+      const ext: AgentExtensions = {
+        facades: [
+          {
+            name: 'my_facade',
+            description: 'Custom facade',
+            ops: [
+              {
+                name: 'do_thing',
+                description: 'Does a thing',
+                auth: 'write',
+                handler: async () => ({ done: true }),
+              },
+            ],
+          },
+        ],
+      };
+      expect(ext.facades).toHaveLength(1);
+    });
+  });
+
+  describe('wrapWithMiddleware', () => {
+    it('should wrap facade ops with before middleware', async () => {
+      const calls: string[] = [];
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test facade',
+        ops: [
+          {
+            name: 'greet',
+            description: 'Say hello',
+            auth: 'read',
+            handler: async (params) => {
+              calls.push('handler');
+              return { message: `Hello ${params.name}` };
+            },
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'logger',
+        before: async (ctx) => {
+          calls.push(`before:${ctx.op}`);
+          return ctx.params;
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({ name: 'World' });
+
+      expect(calls).toEqual(['before:greet', 'handler']);
+      expect(result).toEqual({ message: 'Hello World' });
+    });
+
+    it('should wrap facade ops with after middleware', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test facade',
+        ops: [
+          {
+            name: 'greet',
+            description: 'Say hello',
+            auth: 'read',
+            handler: async () => ({ message: 'Hello' }),
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'enricher',
+        after: async (ctx) => {
+          const data = ctx.result as Record<string, unknown>;
+          return { ...data, enriched: true };
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({});
+      expect(result).toEqual({ message: 'Hello', enriched: true });
+    });
+
+    it('should chain multiple middleware in order', async () => {
+      const order: string[] = [];
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op1',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => {
+              order.push('handler');
+              return { v: 1 };
+            },
+          },
+        ],
+      };
+
+      const mw1: OpMiddleware = {
+        name: 'first',
+        before: async (ctx) => {
+          order.push('first:before');
+          return ctx.params;
+        },
+        after: async (ctx) => {
+          order.push('first:after');
+          return ctx.result;
+        },
+      };
+      const mw2: OpMiddleware = {
+        name: 'second',
+        before: async (ctx) => {
+          order.push('second:before');
+          return ctx.params;
+        },
+        after: async (ctx) => {
+          order.push('second:after');
+          return ctx.result;
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw1, mw2]);
+      await facade.ops[0].handler({});
+
+      expect(order).toEqual([
+        'first:before',
+        'second:before',
+        'handler',
+        'second:after',
+        'first:after',
+      ]);
+    });
+
+    it('should allow before middleware to modify params', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'echo',
+            description: 'Echo',
+            auth: 'read',
+            handler: async (params) => params,
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'injector',
+        before: async (ctx) => ({ ...ctx.params, injected: true }),
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({ original: true });
+      expect(result).toEqual({ original: true, injected: true });
+    });
+
+    it('should handle empty middleware array (no-op)', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+
+      wrapWithMiddleware([facade], []);
+      const result = await facade.ops[0].handler({});
+      expect(result).toEqual({ ok: true });
+    });
+
+    it('should propagate middleware errors', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'blocker',
+        before: async () => {
+          throw new Error('Blocked by policy');
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      await expect(facade.ops[0].handler({})).rejects.toThrow('Blocked by policy');
+    });
+  });
+});

package/src/__tests__/grading-ops.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
 
@@ -20,7 +20,7 @@ describe('Grading Ops', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/memory-cross-project-ops.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
 
@@ -20,7 +20,7 @@ describe('Memory Cross-Project Ops', () => {
       vaultPath: ':memory:',
       plansPath: join(tempDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/normalize.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { normalize, collect } from '../streams/normalize.js';
+
+describe('normalize', () => {
+  it('passes through a single value', async () => {
+    expect(await collect(normalize(42))).toEqual([42]);
+  });
+
+  it('flattens an array', async () => {
+    expect(await collect(normalize([1, 2, 3]))).toEqual([1, 2, 3]);
+  });
+
+  it('resolves a promise', async () => {
+    expect(await collect(normalize(Promise.resolve(99)))).toEqual([99]);
+  });
+
+  it('resolves a promise of array', async () => {
+    expect(await collect(normalize(Promise.resolve([4, 5])))).toEqual([4, 5]);
+  });
+
+  it('consumes an async iterable', async () => {
+    async function* gen() {
+      yield 'a';
+      yield 'b';
+    }
+    expect(await collect(normalize(gen()))).toEqual(['a', 'b']);
+  });
+
+  it('flattens nested arrays', async () => {
+    const input = [
+      [1, 2],
+      [3, [4, 5]],
+    ];
+    expect(await collect(normalize(input))).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it('handles mixed nesting', async () => {
+    async function* gen() {
+      yield 30;
+    }
+    const input = [10, Promise.resolve(20), gen()];
+    expect(await collect(normalize(input))).toEqual([10, 20, 30]);
+  });
+
+  it('handles empty array', async () => {
+    expect(await collect(normalize([]))).toEqual([]);
+  });
+
+  it('handles string as leaf (not iterable)', async () => {
+    expect(await collect(normalize('hello'))).toEqual(['hello']);
+  });
+
+  it('handles deeply nested structure', async () => {
+    const input = [[[1]], [[2, [3]]]];
+    expect(await collect(normalize(input))).toEqual([1, 2, 3]);
+  });
+});
+
+describe('collect', () => {
+  it('collects async iterable to array', async () => {
+    async function* gen() {
+      yield 1;
+      yield 2;
+      yield 3;
+    }
+    expect(await collect(gen())).toEqual([1, 2, 3]);
+  });
+
+  it('returns empty for empty iterable', async () => {
+    async function* gen() {
+      /* empty */
+    }
+    expect(await collect(gen())).toEqual([]);
+  });
+});

package/src/__tests__/playbook.test.ts

@@ -7,7 +7,7 @@ import { validatePlaybook, parsePlaybookFromEntry } from '../vault/playbook.js';
 import type { Playbook } from '../vault/playbook.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime, OpDefinition } from '../runtime/types.js';
 
 function makePlaybook(overrides: Partial<Playbook> = {}): Playbook {
@@ -189,7 +189,7 @@ describe('playbook_create op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {
@@ -300,7 +300,7 @@ describe('playbook_match op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {
@@ -356,7 +356,7 @@ describe('playbook_seed op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/replayable-stream.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { ReplayableStream } from '../streams/replayable-stream.js';
+
+async function* generate(items: number[]): AsyncIterable<number> {
+  for (const item of items) yield item;
+}
+
+let sourceCallCount = 0;
+async function* trackedGenerate(items: number[]): AsyncIterable<number> {
+  sourceCallCount++;
+  for (const item of items) yield item;
+}
+
+describe('ReplayableStream', () => {
+  it('single consumer iterates all items', async () => {
+    const stream = new ReplayableStream(generate([1, 2, 3]));
+    const result = await stream.collect();
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  it('multiple consumers each see full stream', async () => {
+    const stream = new ReplayableStream(generate([10, 20, 30]));
+    const a = stream.collect();
+    const b = stream.collect();
+    expect(await a).toEqual([10, 20, 30]);
+    expect(await b).toEqual([10, 20, 30]);
+  });
+
+  it('source executes exactly once', async () => {
+    sourceCallCount = 0;
+    const stream = new ReplayableStream(trackedGenerate([1, 2]));
+    await stream.collect();
+    await stream.collect();
+    await stream.collect();
+    expect(sourceCallCount).toBe(1);
+  });
+
+  it('bufferedCount tracks buffer size', async () => {
+    const stream = new ReplayableStream(generate([1, 2, 3]));
+    expect(stream.bufferedCount).toBe(0);
+    await stream.collect();
+    expect(stream.bufferedCount).toBe(3);
+  });
+
+  it('empty stream returns empty array', async () => {
+    const stream = new ReplayableStream(generate([]));
+    expect(await stream.collect()).toEqual([]);
+    expect(stream.isDone).toBe(true);
+  });
+
+  it('error propagates to all consumers', async () => {
+    async function* failing(): AsyncIterable<number> {
+      yield 1;
+      throw new Error('source failed');
+    }
+    const stream = new ReplayableStream(failing());
+    await expect(stream.collect()).rejects.toThrow('source failed');
+  });
+
+  it('for-await-of works', async () => {
+    const stream = new ReplayableStream(generate([5, 6]));
+    const items: number[] = [];
+    for await (const item of stream) items.push(item);
+    expect(items).toEqual([5, 6]);
+  });
+});

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

@@ -48,7 +48,7 @@ describe('createVaultExtraOps', () => {
   }
 
   it('should return 23 ops', () => {
-    expect(ops.length).toBe(23);
+    expect(ops.length).toBe(25);
   });
 
   it('should have all expected op names', () => {

package/src/__tests__/vault.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { Vault } from '../vault/vault.js';
+import { computeContentHash } from '../vault/content-hash.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 function makeEntry(overrides: Partial<IntelligenceEntry> = {}): IntelligenceEntry {
@@ -675,4 +676,75 @@ describe('Vault', () => {
       v.close();
     });
   });
+
+  describe('Content-addressable hashing', () => {
+    it('seed populates content_hash', () => {
+      vault.seed([
+        {
+          id: 'ch-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Hash test',
+          severity: 'warning',
+          description: 'Desc',
+          tags: ['a'],
+        },
+      ]);
+      const hash = computeContentHash({
+        type: 'pattern',
+        domain: 'test',
+        title: 'Hash test',
+        description: 'Desc',
+        tags: ['a'],
+      });
+      expect(vault.findByContentHash(hash)).toBe('ch-1');
+    });
+
+    it('findByContentHash returns null for unknown hash', () => {
+      expect(vault.findByContentHash('0000000000000000000000000000000000000000')).toBeNull();
+    });
+
+    it('contentHashStats returns correct counts', () => {
+      vault.seed([
+        {
+          id: 'hs-1',
+          type: 'pattern',
+          domain: 'd',
+          title: 'T1',
+          severity: 'warning',
+          description: 'D1',
+          tags: ['a'],
+        },
+        {
+          id: 'hs-2',
+          type: 'rule',
+          domain: 'd',
+          title: 'T2',
+          severity: 'warning',
+          description: 'D2',
+          tags: ['b'],
+        },
+      ]);
+      const stats = vault.contentHashStats();
+      expect(stats.total).toBeGreaterThanOrEqual(2);
+      expect(stats.hashed).toBe(stats.total);
+      expect(stats.uniqueHashes).toBe(stats.total);
+    });
+
+    it('backfill hashes existing entries on re-initialize', () => {
+      vault.seed([
+        {
+          id: 'bf-1',
+          type: 'pattern',
+          domain: 'd',
+          title: 'Backfill',
+          severity: 'warning',
+          description: 'D',
+          tags: [],
+        },
+      ]);
+      const stats = vault.contentHashStats();
+      expect(stats.hashed).toBe(stats.total);
+    });
+  });
 });

package/src/extensions/index.ts

@@ -0,0 +1,2 @@
+export type { AgentExtensions, OpMiddleware, MiddlewareContext } from './types.js';
+export { wrapWithMiddleware } from './middleware.js';