@kybernesis/brain-testkit 0.1.0

package/dist/helpers/tenant.d.ts

@@ -0,0 +1,8 @@
+import { type TenantContext } from '@kybernesis/brain-contracts';
+export interface TestTenantHandle {
+    tenant: TenantContext;
+    root: string;
+    cleanup: () => void;
+}
+export declare function createTestTenant(slug?: string): TestTenantHandle;
+//# sourceMappingURL=tenant.d.ts.map

package/dist/helpers/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/helpers/tenant.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAYD,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,GAAG,gBAAgB,CAsBhE"}

package/dist/helpers/tenant.js

@@ -0,0 +1,37 @@
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, rmSync } from 'node:fs';
+import { pathsFor } from '@kybernesis/brain-contracts';
+/**
+ * Creates an isolated TenantContext rooted in tmpdir. Each call gets its own
+ * directory (process-unique slug + timestamp + counter) so parallel tests
+ * never share SQLite files.
+ *
+ * Usage:
+ *   const { tenant, cleanup } = createTestTenant();
+ *   afterAll(cleanup);
+ */
+let counter = 0;
+export function createTestTenant(slug = 'test') {
+    counter += 1;
+    const uniq = `${slug}-${process.pid}-${Date.now()}-${counter}`;
+    const root = join(tmpdir(), `cortex-test-${uniq}`);
+    mkdirSync(join(root, 'brain'), { recursive: true });
+    const tenant = {
+        slug: uniq,
+        paths: pathsFor(uniq, root),
+    };
+    return {
+        tenant,
+        root,
+        cleanup: () => {
+            try {
+                rmSync(root, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore — best-effort */
+            }
+        },
+    };
+}
+//# sourceMappingURL=tenant.js.map

package/dist/helpers/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.js","sourceRoot":"","sources":["../../src/helpers/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAsB,MAAM,6BAA6B,CAAC;AAQ3E;;;;;;;;GAQG;AACH,IAAI,OAAO,GAAG,CAAC,CAAC;AAChB,MAAM,UAAU,gBAAgB,CAAC,IAAI,GAAG,MAAM;IAC5C,OAAO,IAAI,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,IAAI,EAAE,CAAC,CAAC;IACnD,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAkB;QAC5B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;KAC5B,CAAC;IAEF,OAAO;QACL,MAAM;QACN,IAAI;QACJ,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACjD,CAAC;YAAC,MAAM,CAAC;gBACP,0BAA0B;YAC5B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './parity/index.js';
+export * from './helpers/tenant.js';
+export * from './llm-stub.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './parity/index.js';
+export * from './helpers/tenant.js';
+export * from './llm-stub.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC"}

package/dist/llm-stub.d.ts

@@ -0,0 +1,11 @@
+interface LLMProvider {
+    call(prompt: string, opts?: unknown): Promise<string | null>;
+}
+/**
+ * Test double for LLMProvider. `responses` is a map from prompt substring to
+ * the string the stub should return. '*' is a special wildcard fallback — it
+ * only fires when no other key matches (regardless of insertion order).
+ */
+export declare function makeLLMStub(responses?: Record<string, string>): LLMProvider;
+export {};
+//# sourceMappingURL=llm-stub.d.ts.map

package/dist/llm-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-stub.d.ts","sourceRoot":"","sources":["../src/llm-stub.ts"],"names":[],"mappings":"AAEA,UAAU,WAAW;IACnB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,WAAW,CAS/E"}

package/dist/llm-stub.js

@@ -0,0 +1,17 @@
+/**
+ * Test double for LLMProvider. `responses` is a map from prompt substring to
+ * the string the stub should return. '*' is a special wildcard fallback — it
+ * only fires when no other key matches (regardless of insertion order).
+ */
+export function makeLLMStub(responses = {}) {
+    return {
+        async call(prompt) {
+            for (const [key, value] of Object.entries(responses)) {
+                if (key !== '*' && prompt.includes(key))
+                    return value;
+            }
+            return responses['*'] ?? null;
+        },
+    };
+}
+//# sourceMappingURL=llm-stub.js.map

package/dist/llm-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-stub.js","sourceRoot":"","sources":["../src/llm-stub.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoC,EAAE;IAChE,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,MAAc;YACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrD,IAAI,GAAG,KAAK,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAAE,OAAO,KAAK,CAAC;YACxD,CAAC;YACD,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/parity/index.d.ts

@@ -0,0 +1,34 @@
+export interface ParityQuery {
+    id: string;
+    input: unknown;
+}
+export interface ParityHarnessInput<TResult, TId = string> {
+    queries: ParityQuery[];
+    baseline: (input: unknown) => Promise<TResult>;
+    candidate: (input: unknown) => Promise<TResult>;
+    extractIds: (result: TResult) => TId[];
+    topN?: number;
+    threshold?: number;
+}
+export interface ParityPerQueryReport<TId = string> {
+    queryId: string;
+    overlap: number;
+    baselineIds: TId[];
+    candidateIds: TId[];
+    missingFromCandidate: TId[];
+    extraInCandidate: TId[];
+    error?: {
+        side: 'baseline' | 'candidate';
+        message: string;
+    };
+}
+export interface ParityReport<TId = string> {
+    passes: boolean;
+    threshold: number;
+    topN: number;
+    meanOverlap: number;
+    totalQueries: number;
+    perQuery: ParityPerQueryReport<TId>[];
+}
+export declare function runParityHarness<TResult, TId = string>(input: ParityHarnessInput<TResult, TId>): Promise<ParityReport<TId>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/parity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/parity/index.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM;IACvD,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,GAAG,EAAE,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB,CAAC,GAAG,GAAG,MAAM;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,GAAG,EAAE,CAAC;IACnB,YAAY,EAAE,GAAG,EAAE,CAAC;IACpB,oBAAoB,EAAE,GAAG,EAAE,CAAC;IAC5B,gBAAgB,EAAE,GAAG,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,MAAM,WAAW,YAAY,CAAC,GAAG,GAAG,MAAM;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;CACvC;AAKD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,EAC1D,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,GACtC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAsE5B"}

package/dist/parity/index.js

@@ -0,0 +1,79 @@
+// Parity harness — generic top-N overlap test for swapping a working
+// parallel implementation to a library implementation.
+//
+// Port from cortex-appydave/packages/cortex-testkit/src/parity/index.ts
+// (verbatim, as required by the port-faithful rule).
+//
+// Usage:
+//   const report = await runParityHarness({
+//     queries: [{ id: 'q1', input: { query: 'kybernesis' } }],
+//     baseline:  (input) => legacyHybridSearch(input as Query),
+//     candidate: (input) => library.hybridSearch(input as Query),
+//     extractIds: (r) => r.data.map((row) => row.id),
+//   });
+//   expect(report.passes).toBe(true);
+const DEFAULT_TOP_N = 10;
+const DEFAULT_THRESHOLD = 0.8;
+export async function runParityHarness(input) {
+    const topN = input.topN ?? DEFAULT_TOP_N;
+    const threshold = input.threshold ?? DEFAULT_THRESHOLD;
+    const perQuery = [];
+    for (const q of input.queries) {
+        let baselineResult;
+        let candidateResult;
+        let error;
+        try {
+            baselineResult = await input.baseline(q.input);
+        }
+        catch (err) {
+            error = { side: 'baseline', message: err.message };
+        }
+        if (!error) {
+            try {
+                candidateResult = await input.candidate(q.input);
+            }
+            catch (err) {
+                error = { side: 'candidate', message: err.message };
+            }
+        }
+        if (error || baselineResult === undefined || candidateResult === undefined) {
+            perQuery.push({
+                queryId: q.id,
+                overlap: 0,
+                baselineIds: [],
+                candidateIds: [],
+                missingFromCandidate: [],
+                extraInCandidate: [],
+                error,
+            });
+            continue;
+        }
+        const baselineIds = input.extractIds(baselineResult).slice(0, topN);
+        const candidateIds = input.extractIds(candidateResult).slice(0, topN);
+        const candidateSet = new Set(candidateIds);
+        const baselineSet = new Set(baselineIds);
+        const overlap = baselineIds.length === 0
+            ? 0
+            : baselineIds.filter((id) => candidateSet.has(id)).length / baselineIds.length;
+        perQuery.push({
+            queryId: q.id,
+            overlap,
+            baselineIds,
+            candidateIds,
+            missingFromCandidate: baselineIds.filter((id) => !candidateSet.has(id)),
+            extraInCandidate: candidateIds.filter((id) => !baselineSet.has(id)),
+        });
+    }
+    const meanOverlap = perQuery.length === 0
+        ? 0
+        : perQuery.reduce((sum, q) => sum + q.overlap, 0) / perQuery.length;
+    return {
+        passes: perQuery.length > 0 && meanOverlap >= threshold,
+        threshold,
+        topN,
+        meanOverlap,
+        totalQueries: perQuery.length,
+        perQuery,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/parity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/parity/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kybernesis/brain-testkit",
+  "version": "0.1.0",
+  "description": "In-memory fakes and parity harness for testing brain-* consumers",
+  "license": "MIT",
+  "author": "David Cruwys (AppyDave)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KybernesisAI/cortex.git",
+    "directory": "packages/brain-testkit"
+  },
+  "homepage": "https://github.com/KybernesisAI/cortex/tree/main/packages/brain-testkit#readme",
+  "bugs": {
+    "url": "https://github.com/KybernesisAI/cortex/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./parity": {
+      "types": "./dist/parity/index.d.ts",
+      "default": "./dist/parity/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/tenant.d.ts",
+      "default": "./dist/helpers/tenant.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kybernesis/brain-contracts": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "typecheck": "tsc -b"
+  }
+}