@steno-ai/engine 0.1.0

package/dist/models/webhook.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export declare const WEBHOOK_EVENTS: readonly ["extraction.completed", "extraction.failed", "trigger.fired", "usage.limit_approaching", "usage.limit_exceeded"];
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+export declare const WebhookSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodEnum<["extraction.completed", "extraction.failed", "trigger.fired", "usage.limit_approaching", "usage.limit_exceeded"]>, "many">;
+    secretHash: z.ZodString;
+    signingKey: z.ZodString;
+    active: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    active: boolean;
+    url: string;
+    id: string;
+    tenantId: string;
+    createdAt: Date;
+    events: ("extraction.completed" | "extraction.failed" | "trigger.fired" | "usage.limit_approaching" | "usage.limit_exceeded")[];
+    secretHash: string;
+    signingKey: string;
+}, {
+    url: string;
+    id: string;
+    tenantId: string;
+    createdAt: Date;
+    events: ("extraction.completed" | "extraction.failed" | "trigger.fired" | "usage.limit_approaching" | "usage.limit_exceeded")[];
+    secretHash: string;
+    signingKey: string;
+    active?: boolean | undefined;
+}>;
+export type Webhook = z.infer<typeof WebhookSchema>;
+export declare const CreateWebhookSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodEnum<["extraction.completed", "extraction.failed", "trigger.fired", "usage.limit_approaching", "usage.limit_exceeded"]>, "many">;
+    secret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    tenantId: string;
+    events: ("extraction.completed" | "extraction.failed" | "trigger.fired" | "usage.limit_approaching" | "usage.limit_exceeded")[];
+    secret: string;
+}, {
+    url: string;
+    tenantId: string;
+    events: ("extraction.completed" | "extraction.failed" | "trigger.fired" | "usage.limit_approaching" | "usage.limit_exceeded")[];
+    secret: string;
+}>;
+export type CreateWebhook = z.infer<typeof CreateWebhookSchema>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/models/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/models/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,4HAMjB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;EASxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;EAK9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/models/webhook.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const WEBHOOK_EVENTS = [
+    'extraction.completed',
+    'extraction.failed',
+    'trigger.fired',
+    'usage.limit_approaching',
+    'usage.limit_exceeded',
+];
+export const WebhookSchema = z.object({
+    id: z.string().uuid(),
+    tenantId: z.string().uuid(),
+    url: z.string().url(),
+    events: z.array(z.enum(WEBHOOK_EVENTS)),
+    secretHash: z.string(),
+    signingKey: z.string(), // raw secret for HMAC signing — stored encrypted at rest in production
+    active: z.boolean().default(true),
+    createdAt: z.coerce.date(),
+});
+export const CreateWebhookSchema = z.object({
+    tenantId: z.string().uuid(),
+    url: z.string().url(),
+    events: z.array(z.enum(WEBHOOK_EVENTS)).min(1),
+    secret: z.string().min(16),
+});
+//# sourceMappingURL=webhook.js.map

package/dist/models/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/models/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,sBAAsB;IACtB,mBAAmB;IACnB,eAAe;IACf,yBAAyB;IACzB,sBAAsB;CACd,CAAC;AAGX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC3B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,uEAAuE;IAC/F,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE;CAC3B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC3B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;CAC3B,CAAC,CAAC"}

package/dist/profiles/index.d.ts

@@ -0,0 +1,3 @@
+export { getUserProfile, categorize } from './profile.js';
+export type { UserProfile, ProfileFact } from './profile.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/profiles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/profiles/index.js

@@ -0,0 +1,2 @@
+export { getUserProfile, categorize } from './profile.js';
+//# sourceMappingURL=index.js.map

package/dist/profiles/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/profiles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/profiles/profile.d.ts

@@ -0,0 +1,22 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+export interface UserProfile {
+    userId: string;
+    static: ProfileFact[];
+    dynamic: ProfileFact[];
+    lastUpdated: Date | null;
+}
+export interface ProfileFact {
+    id: string;
+    content: string;
+    importance: number;
+    category: string;
+    validFrom: Date;
+}
+/**
+ * Build a user profile from stored facts.
+ * Static = high importance (>0.7) + old (>7 days)
+ * Dynamic = recent (<7 days) OR low importance
+ */
+export declare function getUserProfile(storage: StorageAdapter, tenantId: string, userId: string): Promise<UserProfile>;
+export declare function categorize(content: string, _importance: number): string;
+//# sourceMappingURL=profile.d.ts.map

package/dist/profiles/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/profiles/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CA4CtB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQvE"}

package/dist/profiles/profile.js

@@ -0,0 +1,59 @@
+/**
+ * Build a user profile from stored facts.
+ * Static = high importance (>0.7) + old (>7 days)
+ * Dynamic = recent (<7 days) OR low importance
+ */
+export async function getUserProfile(storage, tenantId, userId) {
+    const facts = await storage.getFactsByScope(tenantId, 'user', userId, { limit: 100 });
+    const validFacts = facts.data.filter(f => f.validUntil === null);
+    const now = Date.now();
+    const sevenDays = 7 * 24 * 60 * 60 * 1000;
+    const staticFacts = [];
+    const dynamicFacts = [];
+    for (const fact of validFacts) {
+        // Skip raw chunks — only use extracted facts for profiles
+        if (fact.tags?.includes('raw_chunk'))
+            continue;
+        const age = now - new Date(fact.validFrom).getTime();
+        const category = categorize(fact.content, fact.importance);
+        const profileFact = {
+            id: fact.id,
+            content: fact.content,
+            importance: fact.importance,
+            category,
+            validFrom: new Date(fact.validFrom),
+        };
+        if (fact.importance >= 0.7 && age > sevenDays) {
+            staticFacts.push(profileFact);
+        }
+        else {
+            dynamicFacts.push(profileFact);
+        }
+    }
+    // Sort: static by importance desc, dynamic by recency desc
+    staticFacts.sort((a, b) => b.importance - a.importance);
+    dynamicFacts.sort((a, b) => b.validFrom.getTime() - a.validFrom.getTime());
+    return {
+        userId,
+        static: staticFacts,
+        dynamic: dynamicFacts,
+        lastUpdated: validFacts.length > 0
+            ? new Date(Math.max(...validFacts.map(f => new Date(f.createdAt).getTime())))
+            : null,
+    };
+}
+export function categorize(content, _importance) {
+    const lower = content.toLowerCase();
+    if (lower.includes('allergic') || lower.includes('medication') || lower.includes('health'))
+        return 'health';
+    if (lower.includes('name is') || lower.includes('age') || lower.includes('born'))
+        return 'identity';
+    if (lower.includes('works at') || lower.includes('job') || lower.includes('engineer') || lower.includes('company'))
+        return 'work';
+    if (lower.includes('lives in') || lower.includes('based in') || lower.includes('location') || lower.includes('from'))
+        return 'location';
+    if (lower.includes('prefers') || lower.includes('likes') || lower.includes('loves') || lower.includes('hates') || lower.includes('favorite'))
+        return 'preference';
+    return 'other';
+}
+//# sourceMappingURL=profile.js.map

package/dist/profiles/profile.js.map

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

package/dist/retrieval/compound-search.d.ts

@@ -0,0 +1,13 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { Candidate } from './types.js';
+/**
+ * Compound search: embeds the query, then calls storage.compoundSearch
+ * (ONE database call for both vector + keyword), and splits results
+ * into Candidate format.
+ */
+export declare function compoundSearchSignal(storage: StorageAdapter, embedding: EmbeddingAdapter, query: string, tenantId: string, scope: string, scopeId: string, limit: number): Promise<{
+    vectorCandidates: Candidate[];
+    keywordCandidates: Candidate[];
+}>;
+//# sourceMappingURL=compound-search.d.ts.map

package/dist/retrieval/compound-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compound-search.d.ts","sourceRoot":"","sources":["../../src/retrieval/compound-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,YAAY,CAAC;AA2B3D;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAAC,iBAAiB,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CA6D5E"}

package/dist/retrieval/compound-search.js

@@ -0,0 +1,87 @@
+/**
+ * Words to strip from search queries before keyword matching.
+ * Only question/function words that appear in queries but rarely in stored facts.
+ *
+ * NOTE: We intentionally do NOT strip "user" even though it appears in most facts.
+ * PostgreSQL's ts_rank uses IDF (inverse document frequency) weighting internally,
+ * so "user" gets near-zero weight when it appears in most documents. This is the
+ * correct behavior — ts_rank("user | hono") will score a fact containing "hono"
+ * much higher than one containing only "user", even though both match the tsquery.
+ */
+const QUERY_STOP_WORDS = new Set([
+    // Question words
+    'what', 'when', 'where', 'who', 'why', 'how', 'which',
+    // Auxiliary verbs from questions
+    'is', 'are', 'was', 'were', 'did', 'does', 'do', 'will', 'can', 'could', 'would', 'should',
+    'have', 'has', 'had', 'been', 'be',
+    // Articles and prepositions
+    'the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', 'of', 'with',
+    // Conjunctions
+    'and', 'or', 'but', 'not', 'if', 'still',
+    // Pronouns
+    'it', 'its', 'her', 'his', 'she', 'he', 'they', 'them', 'their', 'my', 'your', 'our',
+    'that', 'this',
+]);
+/**
+ * Compound search: embeds the query, then calls storage.compoundSearch
+ * (ONE database call for both vector + keyword), and splits results
+ * into Candidate format.
+ */
+export async function compoundSearchSignal(storage, embedding, query, tenantId, scope, scopeId, limit) {
+    const queryEmbedding = await embedding.embed(query);
+    // Extract content words, join with OR for to_tsquery
+    // ts_rank handles IDF weighting — high-frequency terms get low scores automatically
+    const keywordQuery = query.toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length >= 2 && !QUERY_STOP_WORDS.has(w))
+        .join(' | ');
+    const results = await storage.compoundSearch({
+        embedding: queryEmbedding,
+        query: keywordQuery || query,
+        tenantId,
+        scope,
+        scopeId,
+        limit,
+        minSimilarity: 0.25, // low threshold — let fusion scoring handle ranking, not hard cutoffs
+    });
+    const vectorCandidates = [];
+    const keywordCandidates = [];
+    for (const r of results) {
+        if (r.source === 'vector') {
+            vectorCandidates.push({
+                fact: r.fact,
+                vectorScore: r.relevanceScore,
+                keywordScore: 0,
+                graphScore: 0,
+                recencyScore: 0,
+                salienceScore: 0,
+                temporalScore: 0,
+                source: 'vector',
+            });
+        }
+        else {
+            keywordCandidates.push({
+                fact: r.fact,
+                vectorScore: 0,
+                keywordScore: r.relevanceScore,
+                graphScore: 0,
+                recencyScore: 0,
+                salienceScore: 0,
+                temporalScore: 0,
+                source: 'keyword',
+            });
+        }
+    }
+    // Normalize keyword scores to [0, 1] range
+    if (keywordCandidates.length > 0) {
+        const maxRank = Math.max(...keywordCandidates.map(c => c.keywordScore));
+        if (maxRank > 0) {
+            for (const c of keywordCandidates) {
+                c.keywordScore = c.keywordScore / maxRank;
+            }
+        }
+    }
+    return { vectorCandidates, keywordCandidates };
+}
+//# sourceMappingURL=compound-search.js.map

package/dist/retrieval/compound-search.js.map

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

package/dist/retrieval/contradiction-surfacer.d.ts

@@ -0,0 +1,18 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { FusionResult } from './fusion.js';
+import type { SearchResult } from './types.js';
+/**
+ * Enrich fusion results with contradiction context.
+ * For each result where the fact has an active contradiction,
+ * fetch the contradicted fact and build a timeline description.
+ */
+export declare function surfaceContradictions(storage: StorageAdapter, tenantId: string, results: FusionResult[]): Promise<SearchResult[]>;
+/**
+ * Build a human-readable timeline description of a contradiction.
+ * Examples:
+ * - "Opinion changed over ~2 months"
+ * - "Updated after 3 days"
+ * - "Superseded on the same day"
+ */
+export declare function buildTimeline(oldValidFrom: Date, _oldValidUntil: Date | null, newValidFrom: Date): string;
+//# sourceMappingURL=contradiction-surfacer.d.ts.map

package/dist/retrieval/contradiction-surfacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-surfacer.d.ts","sourceRoot":"","sources":["../../src/retrieval/contradiction-surfacer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,YAAY,EAAE,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAyCzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,IAAI,EAClB,cAAc,EAAE,IAAI,GAAG,IAAI,EAC3B,YAAY,EAAE,IAAI,GACjB,MAAM,CAmBR"}

package/dist/retrieval/contradiction-surfacer.js

@@ -0,0 +1,64 @@
+/**
+ * Enrich fusion results with contradiction context.
+ * For each result where the fact has an active contradiction,
+ * fetch the contradicted fact and build a timeline description.
+ */
+export async function surfaceContradictions(storage, tenantId, results) {
+    const enriched = [];
+    for (const result of results) {
+        const { fact } = result;
+        let contradiction;
+        if (fact.contradictionStatus !== 'none' &&
+            fact.contradictsId) {
+            const contradictedFact = await storage.getFact(tenantId, fact.contradictsId);
+            if (contradictedFact) {
+                const timeline = buildTimeline(contradictedFact.validFrom, contradictedFact.validUntil, fact.validFrom);
+                contradiction = {
+                    contradicts: contradictedFact,
+                    status: fact.contradictionStatus,
+                    timeline,
+                };
+            }
+            // If contradicted fact was deleted (GDPR purge), gracefully omit contradiction context
+        }
+        enriched.push({
+            fact: result.fact,
+            score: result.score,
+            signals: result.signals,
+            triggeredBy: result.triggeredBy,
+            contradiction,
+            // graph and history are filled in by the search orchestrator later
+        });
+    }
+    return enriched;
+}
+/**
+ * Build a human-readable timeline description of a contradiction.
+ * Examples:
+ * - "Opinion changed over ~2 months"
+ * - "Updated after 3 days"
+ * - "Superseded on the same day"
+ */
+export function buildTimeline(oldValidFrom, _oldValidUntil, newValidFrom) {
+    const oldDate = new Date(oldValidFrom);
+    const newDate = new Date(newValidFrom);
+    const diffMs = newDate.getTime() - oldDate.getTime();
+    const diffDays = Math.abs(Math.round(diffMs / (1000 * 60 * 60 * 24)));
+    if (diffDays === 0)
+        return 'Superseded on the same day';
+    if (diffDays === 1)
+        return 'Updated after 1 day';
+    if (diffDays < 7)
+        return `Updated after ${diffDays} days`;
+    if (diffDays < 30) {
+        const weeks = Math.round(diffDays / 7);
+        return `Changed over ~${weeks} week${weeks === 1 ? '' : 's'}`;
+    }
+    if (diffDays < 365) {
+        const months = Math.round(diffDays / 30);
+        return `Changed over ~${months} month${months === 1 ? '' : 's'}`;
+    }
+    const years = Math.round(diffDays / 365);
+    return `Changed over ~${years} year${years === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=contradiction-surfacer.js.map

package/dist/retrieval/contradiction-surfacer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-surfacer.js","sourceRoot":"","sources":["../../src/retrieval/contradiction-surfacer.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAuB,EACvB,QAAgB,EAChB,OAAuB;IAEvB,MAAM,QAAQ,GAAmB,EAAE,CAAC;IAEpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;QAExB,IAAI,aAAwD,CAAC;QAE7D,IACE,IAAI,CAAC,mBAAmB,KAAK,MAAM;YACnC,IAAI,CAAC,aAAa,EAClB,CAAC;YACD,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YAE7E,IAAI,gBAAgB,EAAE,CAAC;gBACrB,MAAM,QAAQ,GAAG,aAAa,CAC5B,gBAAgB,CAAC,SAAS,EAC1B,gBAAgB,CAAC,UAAU,EAC3B,IAAI,CAAC,SAAS,CACf,CAAC;gBAEF,aAAa,GAAG;oBACd,WAAW,EAAE,gBAAgB;oBAC7B,MAAM,EAAE,IAAI,CAAC,mBAAmB;oBAChC,QAAQ;iBACT,CAAC;YACJ,CAAC;YACD,uFAAuF;QACzF,CAAC;QAED,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,aAAa;YACb,mEAAmE;SACpE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAkB,EAClB,cAA2B,EAC3B,YAAkB;IAElB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAEtE,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,4BAA4B,CAAC;IACxD,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,qBAAqB,CAAC;IACjD,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,iBAAiB,QAAQ,OAAO,CAAC;IAC1D,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;QACvC,OAAO,iBAAiB,KAAK,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,GAAG,GAAG,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC;QACzC,OAAO,iBAAiB,MAAM,SAAS,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IACnE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC;IACzC,OAAO,iBAAiB,KAAK,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAChE,CAAC"}

package/dist/retrieval/embedding-cache.d.ts

@@ -0,0 +1,17 @@
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { CacheAdapter } from '../adapters/cache.js';
+/**
+ * Wraps an EmbeddingAdapter with caching.
+ * Same query text -> cached embedding (skip OpenAI call).
+ */
+export declare class CachedEmbeddingAdapter implements EmbeddingAdapter {
+    private inner;
+    private cache;
+    private ttlSeconds;
+    readonly model: string;
+    readonly dimensions: number;
+    constructor(inner: EmbeddingAdapter, cache: CacheAdapter, ttlSeconds?: number);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=embedding-cache.d.ts.map

package/dist/retrieval/embedding-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-cache.d.ts","sourceRoot":"","sources":["../../src/retrieval/embedding-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAK3D,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,UAAU;IANpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAGlB,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,YAAY,EACnB,UAAU,GAAE,MAAa;IAM7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CA0BvD"}

package/dist/retrieval/embedding-cache.js

@@ -0,0 +1,56 @@
+/**
+ * Wraps an EmbeddingAdapter with caching.
+ * Same query text -> cached embedding (skip OpenAI call).
+ */
+export class CachedEmbeddingAdapter {
+    inner;
+    cache;
+    ttlSeconds;
+    model;
+    dimensions;
+    constructor(inner, cache, ttlSeconds = 3600) {
+        this.inner = inner;
+        this.cache = cache;
+        this.ttlSeconds = ttlSeconds;
+        this.model = inner.model;
+        this.dimensions = inner.dimensions;
+    }
+    async embed(text) {
+        const key = `emb:${this.model}:${await hashText(text)}`;
+        const cached = await this.cache.get(key);
+        if (cached)
+            return cached;
+        const result = await this.inner.embed(text);
+        await this.cache.set(key, result, this.ttlSeconds);
+        return result;
+    }
+    async embedBatch(texts) {
+        // For batch, check cache for each, only embed uncached ones
+        const results = [];
+        const uncachedIndices = [];
+        for (let i = 0; i < texts.length; i++) {
+            const key = `emb:${this.model}:${await hashText(texts[i])}`;
+            const cached = await this.cache.get(key);
+            results.push(cached);
+            if (!cached)
+                uncachedIndices.push(i);
+        }
+        if (uncachedIndices.length > 0) {
+            const uncachedTexts = uncachedIndices.map(i => texts[i]);
+            const freshEmbeddings = await this.inner.embedBatch(uncachedTexts);
+            for (let j = 0; j < uncachedIndices.length; j++) {
+                const idx = uncachedIndices[j];
+                results[idx] = freshEmbeddings[j];
+                const key = `emb:${this.model}:${await hashText(texts[idx])}`;
+                await this.cache.set(key, freshEmbeddings[j], this.ttlSeconds);
+            }
+        }
+        return results;
+    }
+}
+async function hashText(text) {
+    const encoded = new TextEncoder().encode(text);
+    const hash = await crypto.subtle.digest('SHA-256', encoded);
+    return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('').slice(0, 16);
+}
+//# sourceMappingURL=embedding-cache.js.map

package/dist/retrieval/embedding-cache.js.map

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

package/dist/retrieval/fusion.d.ts

@@ -0,0 +1,27 @@
+import type { Candidate, FusionWeights } from './types.js';
+import type { Fact } from '../models/fact.js';
+export interface FusionResult {
+    fact: Fact;
+    score: number;
+    signals: {
+        vectorScore: number;
+        keywordScore: number;
+        graphScore: number;
+        recencyScore: number;
+        salienceScore: number;
+        temporalScore: number;
+    };
+    source: string;
+    triggeredBy?: string;
+}
+/**
+ * Fuse candidates from multiple retrieval signals into a single ranked list.
+ *
+ * 1. Normalizes weights so they sum to 1.0
+ * 2. Deduplicates by fact ID, keeping the highest score per signal
+ * 3. Computes a weighted sum for each unique fact
+ * 4. Sorts by score descending
+ * 5. Returns the top `limit` results
+ */
+export declare function fuseAndRank(candidates: Candidate[], weights: FusionWeights, limit: number): FusionResult[];
+//# sourceMappingURL=fusion.d.ts.map

package/dist/retrieval/fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CAiGhB"}

package/dist/retrieval/fusion.js

@@ -0,0 +1,87 @@
+/**
+ * Fuse candidates from multiple retrieval signals into a single ranked list.
+ *
+ * 1. Normalizes weights so they sum to 1.0
+ * 2. Deduplicates by fact ID, keeping the highest score per signal
+ * 3. Computes a weighted sum for each unique fact
+ * 4. Sorts by score descending
+ * 5. Returns the top `limit` results
+ */
+export function fuseAndRank(candidates, weights, limit) {
+    if (candidates.length === 0)
+        return [];
+    // 1. Normalize weights so they sum to 1.0
+    const sum = weights.vector +
+        weights.keyword +
+        weights.graph +
+        weights.recency +
+        weights.salience +
+        weights.temporal;
+    const w = sum === 0
+        ? { vector: 1 / 6, keyword: 1 / 6, graph: 1 / 6, recency: 1 / 6, salience: 1 / 6, temporal: 1 / 6 }
+        : {
+            vector: weights.vector / sum,
+            keyword: weights.keyword / sum,
+            graph: weights.graph / sum,
+            recency: weights.recency / sum,
+            salience: weights.salience / sum,
+            temporal: weights.temporal / sum,
+        };
+    // 2. Deduplicate by fact ID — keep highest score per signal
+    const factMap = new Map();
+    for (const c of candidates) {
+        const existing = factMap.get(c.fact.id);
+        if (existing) {
+            existing.vectorScore = Math.max(existing.vectorScore, c.vectorScore);
+            existing.keywordScore = Math.max(existing.keywordScore, c.keywordScore);
+            existing.graphScore = Math.max(existing.graphScore, c.graphScore);
+            existing.recencyScore = Math.max(existing.recencyScore, c.recencyScore);
+            existing.salienceScore = Math.max(existing.salienceScore, c.salienceScore);
+            existing.temporalScore = Math.max(existing.temporalScore, c.temporalScore);
+            if (c.triggeredBy)
+                existing.triggeredBy = c.triggeredBy;
+        }
+        else {
+            factMap.set(c.fact.id, {
+                fact: c.fact,
+                vectorScore: c.vectorScore,
+                keywordScore: c.keywordScore,
+                graphScore: c.graphScore,
+                recencyScore: c.recencyScore,
+                salienceScore: c.salienceScore,
+                temporalScore: c.temporalScore,
+                source: c.source,
+                triggeredBy: c.triggeredBy,
+            });
+        }
+    }
+    // 3. Compute final score for each unique fact
+    const results = [];
+    for (const entry of factMap.values()) {
+        const score = entry.vectorScore * w.vector +
+            entry.keywordScore * w.keyword +
+            entry.graphScore * w.graph +
+            entry.recencyScore * w.recency +
+            entry.salienceScore * w.salience +
+            entry.temporalScore * w.temporal;
+        results.push({
+            fact: entry.fact,
+            score,
+            signals: {
+                vectorScore: entry.vectorScore,
+                keywordScore: entry.keywordScore,
+                graphScore: entry.graphScore,
+                recencyScore: entry.recencyScore,
+                salienceScore: entry.salienceScore,
+                temporalScore: entry.temporalScore,
+            },
+            source: entry.source,
+            triggeredBy: entry.triggeredBy,
+        });
+    }
+    // 4. Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    // 5. Take top N
+    return results.slice(0, limit);
+}
+//# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

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