tea-rags 0.9.0

package/build/core/api/schema-drift-monitor.js

@@ -0,0 +1,65 @@
+/**
+ * SchemaDriftMonitor — detects payload schema changes between server version and indexed data.
+ *
+ * Emits a warning ONCE per session (per instance). Shared across all MCP tools.
+ * Lazy: drift check triggers on first tool call that provides a collection path.
+ */
+import { resolveCollectionName, validatePath } from "../contracts/collection.js";
+import { StatsCache } from "./stats-cache.js";
+export class SchemaDriftMonitor {
+    statsCache;
+    currentPayloadKeys;
+    _warned = false;
+    _checkedCollections = new Set();
+    constructor(statsCache, currentPayloadKeys) {
+        this.statsCache = statsCache;
+        this.currentPayloadKeys = currentPayloadKeys;
+    }
+    /**
+     * Check drift for a path and return warning (once per session).
+     * Returns null if already warned, no drift, or no cached keys.
+     */
+    async checkAndConsume(path) {
+        if (this._warned)
+            return null;
+        try {
+            const absolutePath = await validatePath(path);
+            const collectionName = resolveCollectionName(absolutePath);
+            if (this._checkedCollections.has(collectionName))
+                return null;
+            this._checkedCollections.add(collectionName);
+            const loaded = this.statsCache.load(collectionName);
+            if (!loaded)
+                return null;
+            const drift = StatsCache.checkSchemaDrift(loaded.payloadFieldKeys, this.currentPayloadKeys);
+            if (!drift)
+                return null;
+            this._warned = true;
+            return StatsCache.formatSchemaDriftWarning(drift);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Check drift synchronously when collection name is already known. */
+    checkByCollectionName(collectionName) {
+        if (this._warned)
+            return null;
+        if (this._checkedCollections.has(collectionName))
+            return null;
+        this._checkedCollections.add(collectionName);
+        const loaded = this.statsCache.load(collectionName);
+        if (!loaded)
+            return null;
+        const drift = StatsCache.checkSchemaDrift(loaded.payloadFieldKeys, this.currentPayloadKeys);
+        if (!drift)
+            return null;
+        this._warned = true;
+        return StatsCache.formatSchemaDriftWarning(drift);
+    }
+    /** Expose drift detection for testing. */
+    static detectDrift(cachedKeys, currentKeys) {
+        return StatsCache.checkSchemaDrift(cachedKeys, currentKeys);
+    }
+}
+//# sourceMappingURL=schema-drift-monitor.js.map

package/build/core/api/schema-drift-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-drift-monitor.js","sourceRoot":"","sources":["../../../src/core/api/schema-drift-monitor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAEhE,MAAM,OAAO,kBAAkB;IAKV;IACA;IALX,OAAO,GAAG,KAAK,CAAC;IACP,mBAAmB,GAAG,IAAI,GAAG,EAAU,CAAC;IAEzD,YACmB,UAAsB,EACtB,kBAA4B;QAD5B,eAAU,GAAV,UAAU,CAAY;QACtB,uBAAkB,GAAlB,kBAAkB,CAAU;IAC5C,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,IAAY;QAChC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;YAC9C,MAAM,cAAc,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;YAC3D,IAAI,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,cAAc,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC9D,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACpD,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC;YAEzB,MAAM,KAAK,GAAG,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAC5F,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YAExB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,OAAO,UAAU,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,qBAAqB,CAAC,cAAsB;QAC1C,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,cAAc,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9D,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAE7C,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,KAAK,GAAG,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC5F,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,UAAU,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,WAAW,CAAC,UAAgC,EAAE,WAAqB;QACxE,OAAO,UAAU,CAAC,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/build/core/api/search-facade.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SearchFacade - Public API for semantic code search.
+ *
+ * Delegates to:
+ * - SearchModule: semantic code search over indexed collections
+ *
+ * Cold-start: loads cached collection stats into reranker on first search.
+ */
+import type { EmbeddingProvider } from "../adapters/embeddings/base.js";
+import type { QdrantManager } from "../adapters/qdrant/client.js";
+import type { Reranker } from "../search/reranker.js";
+import type { TrajectoryRegistry } from "../trajectory/index.js";
+import type { CodeSearchResult, SearchCodeConfig, SearchOptions } from "../types.js";
+import type { StatsCache } from "./stats-cache.js";
+export declare class SearchFacade {
+    private readonly reranker;
+    private readonly statsCache?;
+    private readonly search;
+    constructor(qdrant: QdrantManager, embeddings: EmbeddingProvider, config: SearchCodeConfig, reranker: Reranker, registry?: TrajectoryRegistry, statsCache?: StatsCache | undefined);
+    /** Search code semantically */
+    searchCode(path: string, query: string, options?: SearchOptions): Promise<CodeSearchResult[]>;
+    /** Load cached collection stats into reranker (cold start). */
+    private loadStatsFromCache;
+}
+//# sourceMappingURL=search-facade.d.ts.map

package/build/core/api/search-facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-facade.d.ts","sourceRoot":"","sources":["../../../src/core/api/search-facade.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAR9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAGpC,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,gBAAgB,EACP,QAAQ,EAAE,QAAQ,EACnC,QAAQ,CAAC,EAAE,kBAAkB,EACZ,UAAU,CAAC,EAAE,UAAU,YAAA;IAK1C,+BAA+B;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAOnG,+DAA+D;YACjD,kBAAkB;CAYjC"}

package/build/core/api/search-facade.js

@@ -0,0 +1,42 @@
+/**
+ * SearchFacade - Public API for semantic code search.
+ *
+ * Delegates to:
+ * - SearchModule: semantic code search over indexed collections
+ *
+ * Cold-start: loads cached collection stats into reranker on first search.
+ */
+import { resolveCollectionName, validatePath } from "../contracts/collection.js";
+import { SearchModule } from "../search/search-module.js";
+export class SearchFacade {
+    reranker;
+    statsCache;
+    search;
+    constructor(qdrant, embeddings, config, reranker, registry, statsCache) {
+        this.reranker = reranker;
+        this.statsCache = statsCache;
+        this.search = new SearchModule(qdrant, embeddings, config, reranker, registry);
+    }
+    /** Search code semantically */
+    async searchCode(path, query, options) {
+        if (this.statsCache && !this.reranker.hasCollectionStats) {
+            await this.loadStatsFromCache(path);
+        }
+        return this.search.searchCode(path, query, options);
+    }
+    /** Load cached collection stats into reranker (cold start). */
+    async loadStatsFromCache(path) {
+        try {
+            const absolutePath = await validatePath(path);
+            const collectionName = resolveCollectionName(absolutePath);
+            const stats = this.statsCache?.load(collectionName);
+            if (stats) {
+                this.reranker.setCollectionStats(stats);
+            }
+        }
+        catch {
+            // Stats loading failure should not prevent search
+        }
+    }
+}
+//# sourceMappingURL=search-facade.js.map

package/build/core/api/search-facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-facade.js","sourceRoot":"","sources":["../../../src/core/api/search-facade.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAK1D,MAAM,OAAO,YAAY;IAOJ;IAEA;IARF,MAAM,CAAe;IAEtC,YACE,MAAqB,EACrB,UAA6B,EAC7B,MAAwB,EACP,QAAkB,EACnC,QAA6B,EACZ,UAAuB;QAFvB,aAAQ,GAAR,QAAQ,CAAU;QAElB,eAAU,GAAV,UAAU,CAAa;QAExC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjF,CAAC;IAED,+BAA+B;IAC/B,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,KAAa,EAAE,OAAuB;QACnE,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,CAAC;YACzD,MAAM,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED,+DAA+D;IACvD,KAAK,CAAC,kBAAkB,CAAC,IAAY;QAC3C,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;YAC9C,MAAM,cAAc,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;YAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YACpD,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;IACH,CAAC;CACF"}

package/build/core/api/stats-cache.d.ts

@@ -0,0 +1,23 @@
+import type { CollectionSignalStats } from "../contracts/types/trajectory.js";
+export interface SchemaDrift {
+    added: string[];
+    removed: string[];
+}
+export declare class StatsCache {
+    private readonly snapshotsDir;
+    constructor(snapshotsDir: string);
+    /** Load cached stats from JSON file. Returns null if missing/corrupt. */
+    load(collectionName: string): (CollectionSignalStats & {
+        payloadFieldKeys?: string[];
+    }) | null;
+    /** Save stats to JSON file. */
+    save(collectionName: string, stats: CollectionSignalStats, payloadFieldKeys?: string[]): void;
+    /** Invalidate (delete) cache file. */
+    invalidate(collectionName: string): void;
+    private filePath;
+    /** Compare cached payload keys vs current. Returns null if no drift or no cached keys. */
+    static checkSchemaDrift(cachedKeys: string[] | undefined, currentKeys: string[]): SchemaDrift | null;
+    /** Format a human-readable warning for schema drift. */
+    static formatSchemaDriftWarning(drift: SchemaDrift): string;
+}
+//# sourceMappingURL=stats-cache.d.ts.map

package/build/core/api/stats-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats-cache.d.ts","sourceRoot":"","sources":["../../../src/core/api/stats-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAe,MAAM,kCAAkC,CAAC;AAY3F,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,MAAM;IAEjD,yEAAyE;IACzE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,qBAAqB,GAAG;QAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,IAAI;IAiB9F,+BAA+B;IAC/B,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAY7F,sCAAsC;IACtC,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAOxC,OAAO,CAAC,QAAQ;IAIhB,0FAA0F;IAC1F,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,IAAI;IAUpG,wDAAwD;IACxD,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;CAW5D"}

package/build/core/api/stats-cache.js

@@ -0,0 +1,76 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const CURRENT_VERSION = 2;
+export class StatsCache {
+    snapshotsDir;
+    constructor(snapshotsDir) {
+        this.snapshotsDir = snapshotsDir;
+    }
+    /** Load cached stats from JSON file. Returns null if missing/corrupt. */
+    load(collectionName) {
+        const filePath = this.filePath(collectionName);
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const raw = readFileSync(filePath, "utf-8");
+            const data = JSON.parse(raw);
+            if (data.version !== CURRENT_VERSION)
+                return null;
+            return {
+                perSignal: new Map(Object.entries(data.perSignal)),
+                computedAt: data.computedAt,
+                payloadFieldKeys: data.payloadFieldKeys,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Save stats to JSON file. */
+    save(collectionName, stats, payloadFieldKeys) {
+        mkdirSync(this.snapshotsDir, { recursive: true });
+        const content = {
+            version: CURRENT_VERSION,
+            collectionName,
+            computedAt: stats.computedAt,
+            perSignal: Object.fromEntries(stats.perSignal),
+            payloadFieldKeys,
+        };
+        writeFileSync(this.filePath(collectionName), JSON.stringify(content, null, 2), "utf-8");
+    }
+    /** Invalidate (delete) cache file. */
+    invalidate(collectionName) {
+        const filePath = this.filePath(collectionName);
+        if (existsSync(filePath)) {
+            rmSync(filePath);
+        }
+    }
+    filePath(collectionName) {
+        return join(this.snapshotsDir, `${collectionName}.stats.json`);
+    }
+    /** Compare cached payload keys vs current. Returns null if no drift or no cached keys. */
+    static checkSchemaDrift(cachedKeys, currentKeys) {
+        if (!cachedKeys)
+            return null;
+        const cachedSet = new Set(cachedKeys);
+        const currentSet = new Set(currentKeys);
+        const added = currentKeys.filter((k) => !cachedSet.has(k));
+        const removed = cachedKeys.filter((k) => !currentSet.has(k));
+        if (added.length === 0 && removed.length === 0)
+            return null;
+        return { added, removed };
+    }
+    /** Format a human-readable warning for schema drift. */
+    static formatSchemaDriftWarning(drift) {
+        const lines = ["Payload schema changed since last indexing."];
+        if (drift.added.length > 0) {
+            lines.push(`New fields: ${drift.added.join(", ")} (require reindex to populate)`);
+        }
+        if (drift.removed.length > 0) {
+            lines.push(`Removed fields: ${drift.removed.join(", ")} (no longer used)`);
+        }
+        lines.push("Run index_codebase with forceReindex=true to update.");
+        return lines.join("\n");
+    }
+}
+//# sourceMappingURL=stats-cache.js.map

package/build/core/api/stats-cache.js.map

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

package/build/core/contracts/collection-stats.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generic collection-wide signal statistics computation.
+ *
+ * Receives already-fetched Qdrant points and PayloadSignalDescriptors,
+ * computes statistics only for signals that declare a `stats` field.
+ * Qdrant scrolling is handled at the API layer — this function is pure.
+ */
+import type { CollectionSignalStats, PayloadSignalDescriptor } from "./types/trajectory.js";
+/**
+ * Compute collection-wide stats for PayloadSignalDescriptors that declare a `stats` field.
+ *
+ * - Filters to signals WITH `stats` request (not just numeric type)
+ * - Resolves dot-notation paths against each point's payload
+ * - Skips missing/non-numeric/zero-or-negative values
+ * - Computes only what's declared: percentiles, mean, stddev
+ * - Returns empty perSignal map for signals with no valid values
+ */
+export declare function computeCollectionStats(points: {
+    payload: Record<string, unknown>;
+}[], signals: PayloadSignalDescriptor[]): CollectionSignalStats;
+//# sourceMappingURL=collection-stats.d.ts.map

package/build/core/contracts/collection-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-stats.d.ts","sourceRoot":"","sources":["../../../src/core/contracts/collection-stats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAe,MAAM,uBAAuB,CAAC;AA+BzG;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,EAC9C,OAAO,EAAE,uBAAuB,EAAE,GACjC,qBAAqB,CAmDvB"}

package/build/core/contracts/collection-stats.js

@@ -0,0 +1,93 @@
+/**
+ * Generic collection-wide signal statistics computation.
+ *
+ * Receives already-fetched Qdrant points and PayloadSignalDescriptors,
+ * computes statistics only for signals that declare a `stats` field.
+ * Qdrant scrolling is handled at the API layer — this function is pure.
+ */
+/**
+ * Read a value from a nested object using dot-notation path.
+ * Returns undefined if any segment is missing.
+ */
+function readPayloadPath(payload, path) {
+    const parts = path.split(".");
+    let current = payload;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Compute percentile from a sorted array using linear interpolation.
+ *
+ * For p in [0, 100], computes the index as (p/100) * (n-1),
+ * then interpolates between the two adjacent values.
+ */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(idx);
+    const upper = Math.ceil(idx);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+}
+/**
+ * Compute collection-wide stats for PayloadSignalDescriptors that declare a `stats` field.
+ *
+ * - Filters to signals WITH `stats` request (not just numeric type)
+ * - Resolves dot-notation paths against each point's payload
+ * - Skips missing/non-numeric/zero-or-negative values
+ * - Computes only what's declared: percentiles, mean, stddev
+ * - Returns empty perSignal map for signals with no valid values
+ */
+export function computeCollectionStats(points, signals) {
+    const statsSignals = signals.filter((s) => s.stats !== undefined);
+    const valueArrays = new Map();
+    for (const signal of statsSignals) {
+        valueArrays.set(signal.key, []);
+    }
+    for (const point of points) {
+        for (const signal of statsSignals) {
+            const val = readPayloadPath(point.payload, signal.key);
+            if (typeof val === "number" && val > 0) {
+                const arr = valueArrays.get(signal.key);
+                if (arr)
+                    arr.push(val);
+            }
+        }
+    }
+    const perSignal = new Map();
+    for (const signal of statsSignals) {
+        const values = valueArrays.get(signal.key);
+        if (!values || values.length === 0)
+            continue;
+        values.sort((a, b) => a - b);
+        const result = { count: values.length };
+        const req = signal.stats;
+        if (!req)
+            continue;
+        if (req.percentiles && req.percentiles.length > 0) {
+            result.percentiles = {};
+            for (const p of req.percentiles) {
+                result.percentiles[p] = percentile(values, p);
+            }
+        }
+        if (req.mean) {
+            const sum = values.reduce((a, b) => a + b, 0);
+            result.mean = sum / values.length;
+        }
+        if (req.stddev) {
+            const sum = values.reduce((a, b) => a + b, 0);
+            const mean = sum / values.length;
+            const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / values.length;
+            result.stddev = Math.sqrt(variance);
+        }
+        perSignal.set(signal.key, result);
+    }
+    return { perSignal, computedAt: Date.now() };
+}
+//# sourceMappingURL=collection-stats.js.map

package/build/core/contracts/collection-stats.js.map

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

package/build/core/contracts/collection.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for collection name resolution and path validation.
+ *
+ * These are domain-agnostic helpers used by search, ingest, and api layers.
+ * Placed in contracts/ so all domain modules can import them without
+ * violating dependency boundaries.
+ */
+/**
+ * Validate that a path doesn't attempt directory traversal.
+ * @throws Error if path traversal is detected
+ */
+export declare function validatePath(path: string): Promise<string>;
+/**
+ * Generate deterministic collection name from codebase path.
+ */
+export declare function resolveCollectionName(path: string): string;
+//# sourceMappingURL=collection.d.ts.map

package/build/core/contracts/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../../src/core/contracts/collection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAShE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D"}

package/build/core/contracts/collection.js

@@ -0,0 +1,33 @@
+/**
+ * Shared utilities for collection name resolution and path validation.
+ *
+ * These are domain-agnostic helpers used by search, ingest, and api layers.
+ * Placed in contracts/ so all domain modules can import them without
+ * violating dependency boundaries.
+ */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Validate that a path doesn't attempt directory traversal.
+ * @throws Error if path traversal is detected
+ */
+export async function validatePath(path) {
+    const absolutePath = resolve(path);
+    try {
+        const realPath = await fs.realpath(absolutePath);
+        return realPath;
+    }
+    catch {
+        return absolutePath;
+    }
+}
+/**
+ * Generate deterministic collection name from codebase path.
+ */
+export function resolveCollectionName(path) {
+    const absolutePath = resolve(path);
+    const hash = createHash("md5").update(absolutePath).digest("hex");
+    return `code_${hash.substring(0, 8)}`;
+}
+//# sourceMappingURL=collection.js.map

package/build/core/contracts/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../../../src/core/contracts/collection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QACjD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClE,OAAO,QAAQ,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/build/core/contracts/index.d.ts

@@ -0,0 +1,8 @@
+export type * from "./types/app.js";
+export type * from "./types/config.js";
+export type * from "./types/provider.js";
+export type * from "./types/reranker.js";
+export type * from "./types/trajectory.js";
+export * from "./signal-utils.js";
+export type { QdrantMatchCondition, QdrantRangeCondition, QdrantFilterCondition, QdrantFilter, } from "../adapters/qdrant/types.js";
+//# sourceMappingURL=index.d.ts.map

package/build/core/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/contracts/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,gBAAgB,CAAC;AACpC,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,uBAAuB,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAElC,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,GACb,MAAM,6BAA6B,CAAC"}

package/build/core/contracts/index.js

@@ -0,0 +1,2 @@
+export * from "./signal-utils.js";
+//# sourceMappingURL=index.js.map

package/build/core/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/contracts/index.ts"],"names":[],"mappings":"AAKA,cAAc,mBAAmB,CAAC"}

package/build/core/contracts/signal-utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic signal utility functions.
+ *
+ * Pure math — no payload access, no provider knowledge.
+ * Provider-specific payload accessors live in trajectory/<provider>/rerank/derived-signals/helpers.ts.
+ */
+/**
+ * Normalize a value to 0-1 range, clamped.
+ */
+export declare function normalize(value: number, max: number): number;
+/**
+ * Calculate the 95th percentile of a numeric array.
+ * Returns 1 for empty arrays to avoid division by zero downstream.
+ */
+export declare function p95(arr: number[]): number;
+/** Default minimum chunk commits for full maturity in alpha computation. */
+export declare const DEFAULT_CHUNK_MATURITY_THRESHOLD = 3;
+/**
+ * Compute alpha blending factor for chunk-vs-file data quality.
+ * alpha = coverageRatio × maturity, clamped to [0, 1].
+ *   coverageRatio = chunkCount / fileCount
+ *   maturity = min(1, chunkCount / maturityThreshold)
+ *
+ * Maturity prevents low-commit chunks (1-2 commits) from overriding
+ * reliable file-level statistics.
+ */
+export declare function computeAlpha(chunkCount: number | undefined, fileCount: number | undefined, maturityThreshold?: number): number;
+/**
+ * Blend chunk and file signal values using alpha.
+ * When chunkValue is undefined, falls back to fileValue.
+ */
+export declare function blend(chunkValue: number | undefined, fileValue: number, alpha: number): number;
+/**
+ * Quadratic confidence dampening.
+ * Returns 1 when sampleCount >= threshold, otherwise (n/k)^power.
+ * Used to dampen statistical signals that are unreliable with small samples.
+ */
+export declare function confidenceDampening(sampleCount: number, threshold: number, power?: number): number;
+//# sourceMappingURL=signal-utils.d.ts.map

package/build/core/contracts/signal-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-utils.d.ts","sourceRoot":"","sources":["../../../src/core/contracts/signal-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAIzC;AAMD,4EAA4E;AAC5E,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,SAAmC,GACnD,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9F;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,CAI7F"}

package/build/core/contracts/signal-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Generic signal utility functions.
+ *
+ * Pure math — no payload access, no provider knowledge.
+ * Provider-specific payload accessors live in trajectory/<provider>/rerank/derived-signals/helpers.ts.
+ */
+// ---------------------------------------------------------------------------
+// Normalization & percentiles
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a value to 0-1 range, clamped.
+ */
+export function normalize(value, max) {
+    if (max <= 0)
+        return 0;
+    return Math.min(1, Math.max(0, value / max));
+}
+/**
+ * Calculate the 95th percentile of a numeric array.
+ * Returns 1 for empty arrays to avoid division by zero downstream.
+ */
+export function p95(arr) {
+    if (arr.length === 0)
+        return 1;
+    const sorted = [...arr].sort((a, b) => a - b);
+    return sorted[Math.min(Math.floor(sorted.length * 0.95), sorted.length - 1)] || 1;
+}
+// ---------------------------------------------------------------------------
+// Alpha-blending (file ↔ chunk)
+// ---------------------------------------------------------------------------
+/** Default minimum chunk commits for full maturity in alpha computation. */
+export const DEFAULT_CHUNK_MATURITY_THRESHOLD = 3;
+/**
+ * Compute alpha blending factor for chunk-vs-file data quality.
+ * alpha = coverageRatio × maturity, clamped to [0, 1].
+ *   coverageRatio = chunkCount / fileCount
+ *   maturity = min(1, chunkCount / maturityThreshold)
+ *
+ * Maturity prevents low-commit chunks (1-2 commits) from overriding
+ * reliable file-level statistics.
+ */
+export function computeAlpha(chunkCount, fileCount, maturityThreshold = DEFAULT_CHUNK_MATURITY_THRESHOLD) {
+    if (chunkCount === undefined || chunkCount <= 0)
+        return 0;
+    if (fileCount === undefined || fileCount <= 0)
+        return 0;
+    const coverageRatio = chunkCount / fileCount;
+    const maturity = Math.min(1, chunkCount / maturityThreshold);
+    return Math.min(1, coverageRatio * maturity);
+}
+/**
+ * Blend chunk and file signal values using alpha.
+ * When chunkValue is undefined, falls back to fileValue.
+ */
+export function blend(chunkValue, fileValue, alpha) {
+    if (chunkValue === undefined)
+        return fileValue;
+    return alpha * chunkValue + (1 - alpha) * fileValue;
+}
+// ---------------------------------------------------------------------------
+// Confidence dampening
+// ---------------------------------------------------------------------------
+/**
+ * Quadratic confidence dampening.
+ * Returns 1 when sampleCount >= threshold, otherwise (n/k)^power.
+ * Used to dampen statistical signals that are unreliable with small samples.
+ */
+export function confidenceDampening(sampleCount, threshold, power = 2) {
+    if (threshold <= 0)
+        return 1;
+    if (sampleCount >= threshold)
+        return 1;
+    return Math.pow(sampleCount / threshold, power);
+}
+//# sourceMappingURL=signal-utils.js.map

package/build/core/contracts/signal-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-utils.js","sourceRoot":"","sources":["../../../src/core/contracts/signal-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,GAAW;IAClD,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,GAAa;IAC/B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACpF,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA8B,EAC9B,SAA6B,EAC7B,iBAAiB,GAAG,gCAAgC;IAEpD,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,iBAAiB,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,UAA8B,EAAE,SAAiB,EAAE,KAAa;IACpF,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,KAAK,GAAG,UAAU,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,SAAS,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB,EAAE,SAAiB,EAAE,KAAK,GAAG,CAAC;IACnF,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7B,IAAI,WAAW,IAAI,SAAS;QAAE,OAAO,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,SAAS,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/build/core/contracts/types/app.d.ts

@@ -0,0 +1,9 @@
+/**
+ * App-level DTOs — re-exported from api/public/dto/ for backward compatibility.
+ *
+ * Canonical source: core/api/public/dto/
+ */
+export type { CollectionRef, TypedFilterParams, SemanticSearchRequest, HybridSearchRequest, RankChunksRequest, ExploreCodeRequest, SearchResult, ExploreResponse, SignalDescriptor, PresetDescriptors, } from "../../api/public/dto/explore.js";
+export type { CreateCollectionRequest, CollectionInfo } from "../../api/public/dto/collection.js";
+export type { AddDocumentsRequest, DeleteDocumentsRequest } from "../../api/public/dto/document.js";
+//# sourceMappingURL=app.d.ts.map

package/build/core/contracts/types/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/core/contracts/types/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAElG,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC"}

package/build/core/contracts/types/app.js

@@ -0,0 +1,7 @@
+/**
+ * App-level DTOs — re-exported from api/public/dto/ for backward compatibility.
+ *
+ * Canonical source: core/api/public/dto/
+ */
+export {};
+//# sourceMappingURL=app.js.map

package/build/core/contracts/types/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../../src/core/contracts/types/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}