brains-mcp 1.61.2

package/dist/observability/metricsQuery.js

@@ -0,0 +1,106 @@
+/**
+ * metricsQuery.ts
+ *
+ * Aggregates request_events telemetry via a Supabase Postgres RPC function.
+ * Falls back to zero-filled defaults when Supabase is not configured.
+ *
+ * SQL function definition: scripts/metrics-rpc.sql
+ */
+export const VALID_WINDOWS = ["1h", "6h", "24h", "7d"];
+const WINDOW_MINUTES = {
+    "1h": 60,
+    "6h": 360,
+    "24h": 1440,
+    "7d": 10080,
+};
+export function isValidWindow(w) {
+    return VALID_WINDOWS.includes(w);
+}
+function emptyMetrics(window) {
+    return {
+        window,
+        search: {
+            p50: 0,
+            p95: 0,
+            p99: 0,
+            totalRequests: 0,
+            errorRate: 0,
+            zeroResultRate: 0,
+            fallbackRate: 0,
+            backendBreakdown: {},
+            topQueries: [],
+        },
+        writes: { p50: 0, p95: 0, totalRequests: 0 },
+        overall: { p95: 0, errorRate: 0 },
+    };
+}
+function toNum(v, fallback = 0) {
+    const n = Number(v);
+    return isFinite(n) ? n : fallback;
+}
+function parseRpcRow(window, row) {
+    const search = (row["search"] ?? {});
+    const writes = (row["writes"] ?? {});
+    const overall = (row["overall"] ?? {});
+    const backendRaw = search["backendBreakdown"];
+    const backendBreakdown = backendRaw && typeof backendRaw === "object" && !Array.isArray(backendRaw)
+        ? Object.fromEntries(Object.entries(backendRaw).map(([k, v]) => [k, toNum(v)]))
+        : {};
+    const topQueriesRaw = search["topQueries"];
+    const topQueries = Array.isArray(topQueriesRaw)
+        ? topQueriesRaw.filter((q) => typeof q === "string")
+        : [];
+    return {
+        window,
+        search: {
+            p50: toNum(search["p50"]),
+            p95: toNum(search["p95"]),
+            p99: toNum(search["p99"]),
+            totalRequests: toNum(search["totalRequests"]),
+            errorRate: toNum(search["errorRate"]),
+            zeroResultRate: toNum(search["zeroResultRate"]),
+            fallbackRate: toNum(search["fallbackRate"]),
+            backendBreakdown,
+            topQueries,
+        },
+        writes: {
+            p50: toNum(writes["p50"]),
+            p95: toNum(writes["p95"]),
+            totalRequests: toNum(writes["totalRequests"]),
+        },
+        overall: {
+            p95: toNum(overall["p95"]),
+            errorRate: toNum(overall["errorRate"]),
+        },
+    };
+}
+/**
+ * Query aggregated metrics for the given time window.
+ * Returns zero-filled defaults when Supabase is not configured.
+ * Throws on Supabase RPC errors so the HTTP handler can return 500.
+ */
+export async function queryMetrics(window) {
+    const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+    const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+    if (!supabaseUrl || !serviceRoleKey) {
+        return emptyMetrics(window);
+    }
+    const minutes = WINDOW_MINUTES[window];
+    const url = `${supabaseUrl}/rest/v1/rpc/get_metrics`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "apikey": serviceRoleKey,
+            "authorization": `Bearer ${serviceRoleKey}`,
+        },
+        body: JSON.stringify({ minutes }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`get_metrics RPC failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    return parseRpcRow(window, data);
+}
+//# sourceMappingURL=metricsQuery.js.map

package/dist/observability/metricsQuery.js.map

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

package/dist/observability/relevanceSignal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * relevanceSignal.ts
+ *
+ * Implicit relevance signal recorder.
+ * When a `read_page` call follows a `search_pages` call within 30 s from the
+ * same auth subject, and the page read was in the search results, record the
+ * (query_text, page_name) pair to the `search_relevance_signals` Supabase table.
+ *
+ * Phase 4 accuracy improvement.
+ *
+ * Table schema: scripts/search-relevance-signals.sql
+ */
+/**
+ * Record a completed search for correlation tracking.
+ */
+export declare function recordSearch(userId: string, queryText: string, resultNames: string[]): void;
+/**
+ * Check whether a page read correlates with a recent search and, if so, fire a
+ * background insert into `search_relevance_signals`.
+ *
+ * Safe to call on every `read_page` — returns immediately without awaiting.
+ */
+export declare function maybeRecordRelevanceSignal(userId: string, pageName: string, supabaseUrl: string, serviceRoleKey: string): void;
+/** Reset state — used in tests. */
+export declare function resetRelevanceSignalState(): void;
+//# sourceMappingURL=relevanceSignal.d.ts.map

package/dist/observability/relevanceSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevanceSignal.d.ts","sourceRoot":"","sources":["../../src/observability/relevanceSignal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqBH;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,GACpB,IAAI,CASN;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,IAAI,CAwBN;AAoCD,mCAAmC;AACnC,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/observability/relevanceSignal.js

@@ -0,0 +1,95 @@
+/**
+ * relevanceSignal.ts
+ *
+ * Implicit relevance signal recorder.
+ * When a `read_page` call follows a `search_pages` call within 30 s from the
+ * same auth subject, and the page read was in the search results, record the
+ * (query_text, page_name) pair to the `search_relevance_signals` Supabase table.
+ *
+ * Phase 4 accuracy improvement.
+ *
+ * Table schema: scripts/search-relevance-signals.sql
+ */
+const CORRELATION_WINDOW_MS = 30_000; // 30 seconds
+const MAX_TRACKED_USERS = 500;
+// In-memory store: userId → most-recent search
+const recentSearches = new Map();
+function evictStale() {
+    const cutoff = Date.now() - CORRELATION_WINDOW_MS;
+    for (const [userId, entry] of recentSearches) {
+        if (entry.ts < cutoff)
+            recentSearches.delete(userId);
+    }
+}
+/**
+ * Record a completed search for correlation tracking.
+ */
+export function recordSearch(userId, queryText, resultNames) {
+    if (!userId)
+        return;
+    evictStale();
+    if (recentSearches.size >= MAX_TRACKED_USERS && !recentSearches.has(userId)) {
+        // Evict the oldest entry to cap memory usage.
+        const oldest = recentSearches.keys().next().value;
+        if (oldest !== undefined)
+            recentSearches.delete(oldest);
+    }
+    recentSearches.set(userId, { queryText, resultNames, ts: Date.now() });
+}
+/**
+ * Check whether a page read correlates with a recent search and, if so, fire a
+ * background insert into `search_relevance_signals`.
+ *
+ * Safe to call on every `read_page` — returns immediately without awaiting.
+ */
+export function maybeRecordRelevanceSignal(userId, pageName, supabaseUrl, serviceRoleKey) {
+    if (!userId || !supabaseUrl || !serviceRoleKey)
+        return;
+    evictStale();
+    const search = recentSearches.get(userId);
+    if (!search)
+        return;
+    const age = Date.now() - search.ts;
+    if (age > CORRELATION_WINDOW_MS) {
+        recentSearches.delete(userId);
+        return;
+    }
+    if (!search.resultNames.includes(pageName))
+        return;
+    // Fire-and-forget insert.
+    void insertRelevanceSignal(supabaseUrl, serviceRoleKey, {
+        authSubject: userId,
+        queryText: search.queryText,
+        pageName,
+        searchTs: new Date(search.ts).toISOString(),
+    }).catch((err) => {
+        console.error("[relevance] insert failed", err.message);
+    });
+}
+async function insertRelevanceSignal(supabaseUrl, serviceRoleKey, row) {
+    const url = `${supabaseUrl}/rest/v1/search_relevance_signals`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            apikey: serviceRoleKey,
+            authorization: `Bearer ${serviceRoleKey}`,
+            prefer: "return=minimal",
+        },
+        body: JSON.stringify({
+            auth_subject: row.authSubject,
+            query_text: row.queryText,
+            page_name: row.pageName,
+            search_ts: row.searchTs,
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`insertRelevanceSignal failed (${res.status}): ${text}`);
+    }
+}
+/** Reset state — used in tests. */
+export function resetRelevanceSignalState() {
+    recentSearches.clear();
+}
+//# sourceMappingURL=relevanceSignal.js.map

package/dist/observability/relevanceSignal.js.map

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

package/dist/observability/requestEvents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * requestEvents.ts
+ *
+ * Fire-and-forget insert of per-request telemetry into the Supabase
+ * `request_events` table.  Uses the same raw-fetch / service-role-key
+ * pattern as PostgresTokenStore and PostgresSearchIndex — no extra SDK.
+ *
+ * When SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY are absent the insert
+ * is skipped entirely and the caller sees no error.
+ *
+ * Table schema: scripts/request-events.sql
+ */
+export interface RequestEvent {
+    method: string;
+    path: string;
+    status: number;
+    duration_ms: number;
+    backend?: string;
+    query_ms?: number;
+    sync_ms?: number;
+    result_count?: number;
+    query_text?: string;
+    tool?: string;
+    page_count?: number;
+}
+/**
+ * Insert a single request event row into `request_events`.
+ * Throws on HTTP error so callers can decide how to handle failures.
+ */
+export declare function insertRequestEvent(supabaseUrl: string, serviceRoleKey: string, event: RequestEvent): Promise<void>;
+//# sourceMappingURL=requestEvents.d.ts.map

package/dist/observability/requestEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestEvents.d.ts","sourceRoot":"","sources":["../../src/observability/requestEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/observability/requestEvents.js

@@ -0,0 +1,54 @@
+/**
+ * requestEvents.ts
+ *
+ * Fire-and-forget insert of per-request telemetry into the Supabase
+ * `request_events` table.  Uses the same raw-fetch / service-role-key
+ * pattern as PostgresTokenStore and PostgresSearchIndex — no extra SDK.
+ *
+ * When SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY are absent the insert
+ * is skipped entirely and the caller sees no error.
+ *
+ * Table schema: scripts/request-events.sql
+ */
+/**
+ * Insert a single request event row into `request_events`.
+ * Throws on HTTP error so callers can decide how to handle failures.
+ */
+export async function insertRequestEvent(supabaseUrl, serviceRoleKey, event) {
+    const url = `${supabaseUrl}/rest/v1/request_events`;
+    const body = {
+        method: event.method,
+        path: event.path,
+        status: event.status,
+        duration_ms: event.duration_ms,
+    };
+    if (event.backend !== undefined)
+        body["backend"] = event.backend;
+    if (event.query_ms !== undefined)
+        body["query_ms"] = event.query_ms;
+    if (event.sync_ms !== undefined)
+        body["sync_ms"] = event.sync_ms;
+    if (event.result_count !== undefined)
+        body["result_count"] = event.result_count;
+    if (event.query_text !== undefined)
+        body["query_text"] = event.query_text;
+    if (event.tool !== undefined)
+        body["tool"] = event.tool;
+    if (event.page_count !== undefined)
+        body["page_count"] = event.page_count;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "apikey": serviceRoleKey,
+            "authorization": `Bearer ${serviceRoleKey}`,
+            "prefer": "return=minimal",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`insertRequestEvent failed (${res.status}): ${text}`);
+    }
+}
+//# sourceMappingURL=requestEvents.js.map

package/dist/observability/requestEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestEvents.js","sourceRoot":"","sources":["../../src/observability/requestEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,cAAsB,EACtB,KAAmB;IAEnB,MAAM,GAAG,GAAG,GAAG,WAAW,yBAAyB,CAAC;IAEpD,MAAM,IAAI,GAA4B;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IACjE,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;IACpE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IACjE,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,cAAc,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC;IAChF,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;IAC1E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;IACxD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;IAE1E,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,QAAQ,EAAE,cAAc;YACxB,eAAe,EAAE,UAAU,cAAc,EAAE;YAC3C,QAAQ,EAAE,gBAAgB;SAC3B;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;AACH,CAAC"}

package/dist/observability/slowQueryAlert.d.ts

@@ -0,0 +1,25 @@
+/**
+ * slowQueryAlert.ts
+ *
+ * Rolling 5-minute p95 search-latency monitor.
+ * Emits a `[metrics] SLOW` warning to stdout when p95 exceeds the threshold.
+ * Threshold is configurable via SLOW_QUERY_THRESHOLD_MS (default 500 ms).
+ *
+ * Phase 4 speed improvement.
+ */
+/**
+ * Record one search latency sample and emit a slow-query alert if warranted.
+ * Safe to call on every search request — low overhead.
+ */
+export declare function recordSearchLatency(durationMs: number): void;
+/**
+ * Return a snapshot of the current rolling window (for tests and diagnostics).
+ */
+export declare function getSlowQueryStats(): {
+    sampleCount: number;
+    p95Ms: number;
+    thresholdMs: number;
+};
+/** Reset state — used in tests. */
+export declare function resetSlowQueryAlert(): void;
+//# sourceMappingURL=slowQueryAlert.d.ts.map

package/dist/observability/slowQueryAlert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slowQueryAlert.d.ts","sourceRoot":"","sources":["../../src/observability/slowQueryAlert.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6BH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAiB5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CASA;AAED,mCAAmC;AACnC,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}

package/dist/observability/slowQueryAlert.js

@@ -0,0 +1,67 @@
+/**
+ * slowQueryAlert.ts
+ *
+ * Rolling 5-minute p95 search-latency monitor.
+ * Emits a `[metrics] SLOW` warning to stdout when p95 exceeds the threshold.
+ * Threshold is configurable via SLOW_QUERY_THRESHOLD_MS (default 500 ms).
+ *
+ * Phase 4 speed improvement.
+ */
+const WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+const MIN_SAMPLES = 5; // require at least this many samples before alerting
+const ALERT_COOLDOWN_MS = 60_000; // emit at most one alert per minute
+const THRESHOLD_MS = Number(process.env.SLOW_QUERY_THRESHOLD_MS ?? 500);
+const samples = [];
+let lastAlertAt = 0;
+function evictOld(now) {
+    const cutoff = now - WINDOW_MS;
+    let i = 0;
+    while (i < samples.length && samples[i].ts < cutoff)
+        i++;
+    if (i > 0)
+        samples.splice(0, i);
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.floor(sorted.length * p);
+    return sorted[Math.min(idx, sorted.length - 1)];
+}
+/**
+ * Record one search latency sample and emit a slow-query alert if warranted.
+ * Safe to call on every search request — low overhead.
+ */
+export function recordSearchLatency(durationMs) {
+    const now = Date.now();
+    evictOld(now);
+    samples.push({ ts: now, ms: durationMs });
+    if (samples.length < MIN_SAMPLES)
+        return;
+    if (now - lastAlertAt < ALERT_COOLDOWN_MS)
+        return;
+    const sorted = samples.map((s) => s.ms).sort((a, b) => a - b);
+    const p95 = percentile(sorted, 0.95);
+    if (p95 > THRESHOLD_MS) {
+        lastAlertAt = now;
+        console.warn(`[metrics] SLOW p95=${p95}ms threshold=${THRESHOLD_MS}ms window=5m samples=${sorted.length}`);
+    }
+}
+/**
+ * Return a snapshot of the current rolling window (for tests and diagnostics).
+ */
+export function getSlowQueryStats() {
+    const now = Date.now();
+    evictOld(now);
+    const sorted = samples.map((s) => s.ms).sort((a, b) => a - b);
+    return {
+        sampleCount: sorted.length,
+        p95Ms: percentile(sorted, 0.95),
+        thresholdMs: THRESHOLD_MS,
+    };
+}
+/** Reset state — used in tests. */
+export function resetSlowQueryAlert() {
+    samples.length = 0;
+    lastAlertAt = 0;
+}
+//# sourceMappingURL=slowQueryAlert.js.map

package/dist/observability/slowQueryAlert.js.map

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

package/dist/observability/zeroResultTriage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * zeroResultTriage.ts
+ *
+ * Weekly zero-result query reporter.
+ * Queries `request_events` for searches that returned zero results (last 7 days),
+ * groups by query_text, and writes a triage page to the wiki at
+ * `data/zero-results-<YYYY-MM-DD>.md`.
+ *
+ * Phase 4 accuracy improvement.
+ */
+import type { StorageClient } from "../storage/client.js";
+export declare function runZeroResultTriage(supabaseUrl: string, serviceRoleKey: string, drive: StorageClient): Promise<{
+    page: string;
+    rowCount: number;
+} | null>;
+/**
+ * Start a weekly recurring triage job.
+ * Runs immediately on first call, then every 7 days.
+ * Returns a cleanup function that cancels the recurring timer.
+ */
+export declare function startZeroResultTriageCron(supabaseUrl: string, serviceRoleKey: string, getDrive: () => StorageClient): () => void;
+//# sourceMappingURL=zeroResultTriage.d.ts.map

package/dist/observability/zeroResultTriage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zeroResultTriage.d.ts","sourceRoot":"","sources":["../../src/observability/zeroResultTriage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAS1D,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAyFpD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,aAAa,GAC5B,MAAM,IAAI,CAiBZ"}

package/dist/observability/zeroResultTriage.js

@@ -0,0 +1,116 @@
+/**
+ * zeroResultTriage.ts
+ *
+ * Weekly zero-result query reporter.
+ * Queries `request_events` for searches that returned zero results (last 7 days),
+ * groups by query_text, and writes a triage page to the wiki at
+ * `data/zero-results-<YYYY-MM-DD>.md`.
+ *
+ * Phase 4 accuracy improvement.
+ */
+const ZERO_RESULT_TRIAGE_LIMIT = 10;
+export async function runZeroResultTriage(supabaseUrl, serviceRoleKey, drive) {
+    const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    // Fetch zero-result events from the last 7 days.
+    const url = `${supabaseUrl}/rest/v1/request_events` +
+        `?select=query_text` +
+        `&path=eq./api/v1/search` +
+        `&result_count=eq.0` +
+        `&query_text=not.is.null` +
+        `&ts=gte.${since}` +
+        `&limit=2000`;
+    let rows;
+    try {
+        const res = await fetch(url, {
+            headers: {
+                apikey: serviceRoleKey,
+                authorization: `Bearer ${serviceRoleKey}`,
+            },
+        });
+        if (!res.ok) {
+            console.error(`[triage] zero-result fetch failed (${res.status})`);
+            return null;
+        }
+        rows = (await res.json());
+    }
+    catch (err) {
+        console.error("[triage] zero-result fetch error", err.message);
+        return null;
+    }
+    // Aggregate counts.
+    const freq = new Map();
+    for (const row of rows) {
+        const q = row.query_text.trim().toLowerCase();
+        if (q)
+            freq.set(q, (freq.get(q) ?? 0) + 1);
+    }
+    const sorted = [...freq.entries()]
+        .map(([q, cnt]) => ({ query_text: q, cnt }))
+        .sort((a, b) => b.cnt - a.cnt)
+        .slice(0, ZERO_RESULT_TRIAGE_LIMIT);
+    if (sorted.length === 0) {
+        console.log("[triage] no zero-result queries in the last 7 days — skipping report");
+        return null;
+    }
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const pageName = `data/zero-results-${dateStr}.md`;
+    const tableRows = sorted
+        .map((r, i) => `| ${i + 1} | \`${r.query_text}\` | ${r.cnt} |`)
+        .join("\n");
+    const content = `---
+title: Zero-Result Triage ${dateStr}
+updated: ${dateStr}
+tags: [metrics, triage, zero-results]
+summary: Weekly report of the top ${sorted.length} search queries that returned zero results (last 7 days).
+---
+
+# Zero-Result Triage — ${dateStr}
+
+Queries with the highest zero-result frequency over the last 7 days.
+Action per entry: add a missing page, improve a page summary, or add a tag alias.
+
+| # | Query | Count |
+|---|-------|-------|
+${tableRows}
+
+_Generated automatically by zero-result triage. Total zero-result events scanned: ${rows.length}._
+`;
+    try {
+        // Try to create a fresh page; if it already exists (same date, re-run), update it.
+        try {
+            await drive.createFile(pageName, content);
+        }
+        catch {
+            // File may already exist — read current revision and overwrite.
+            const existing = await drive.readFile(pageName);
+            await drive.updateFile(existing.fileId, content, existing.revision);
+        }
+        console.log(`[triage] zero-result report written → ${pageName} (${sorted.length} entries)`);
+        return { page: pageName, rowCount: sorted.length };
+    }
+    catch (err) {
+        console.error("[triage] failed to write report page", err.message);
+        return null;
+    }
+}
+/**
+ * Start a weekly recurring triage job.
+ * Runs immediately on first call, then every 7 days.
+ * Returns a cleanup function that cancels the recurring timer.
+ */
+export function startZeroResultTriageCron(supabaseUrl, serviceRoleKey, getDrive) {
+    const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+    const run = () => {
+        runZeroResultTriage(supabaseUrl, serviceRoleKey, getDrive()).catch((err) => {
+            console.error("[triage] unhandled error", err.message);
+        });
+    };
+    // Run once immediately (non-blocking).
+    setTimeout(run, 0);
+    const timer = setInterval(run, WEEK_MS);
+    // Node timers should not keep the process alive just for telemetry.
+    if (typeof timer.unref === "function")
+        timer.unref();
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=zeroResultTriage.js.map

package/dist/observability/zeroResultTriage.js.map

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

package/dist/search/embeddings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * embeddings.ts
+ *
+ * OpenAI text-embedding-3-small client for wiki page vectors.
+ * Used at ingest time (upsertPage) and at query time (hybrid search).
+ *
+ * Cost: $0.020 / 1M tokens (text-embedding-3-small).
+ * Falls back silently when OPENAI_API_KEY is unset so the server
+ * continues to function with FTS-only search.
+ */
+export declare const EMBEDDING_MODEL = "text-embedding-3-small";
+export declare const EMBEDDING_DIMS = 1536;
+export declare function isEmbeddingEnabled(): boolean;
+/**
+ * Generate a single embedding for `text`.
+ * Returns null when OPENAI_API_KEY is unset or the API call fails.
+ * Text is truncated to ~8000 tokens before sending (model max is 8192).
+ */
+export declare function generateEmbedding(text: string): Promise<number[] | null>;
+/**
+ * Generate embeddings for a batch of texts.
+ * OpenAI allows up to 2048 inputs per request; callers should chunk larger batches.
+ * Returns an array of the same length; failed entries are null.
+ */
+export declare function generateEmbeddings(texts: string[]): Promise<Array<number[] | null>>;
+/**
+ * Build the text to embed for a page: title + summary + (first 2000 chars of content).
+ * Keeping content short reduces token cost while preserving semantic signal.
+ */
+export declare function buildEmbeddingInput(title: string, summary: string, content: string): string;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/search/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/search/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,cAAc,OAAQ,CAAC;AAWpC,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAe9E;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAoBzF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM3F"}