onadit 0.0.1 → 1.0.0

package/dist/src/retrieval/report-demotion.d.ts

@@ -0,0 +1,46 @@
+import type { TableName } from "../storage/tables.js";
+import type { RankedResult } from "./reranker.js";
+import type { SearchScope } from "./vector.js";
+/**
+ * Whether a source table can ever hold a report (i.e. is a document table).
+ * Lets the route skip the source_path fetch entirely for conversation-only
+ * result sets.
+ */
+export declare function isReportCandidateTable(t: TableName): boolean;
+/**
+ * A ranked hit is a report iff it's a document (conversations/digests never
+ * are) whose source_path matches the shared snapshot/report classifier. The
+ * classifier only treats a `reports/` doc as generated when it sits under
+ * Onadit's own reports root (`selfReportsRoot`); see {@link isSnapshotPath}.
+ */
+export declare function isReportHit(sourceTable: TableName, sourcePath: string | undefined, selfReportsRoot?: string): boolean;
+/**
+ * Fetch `source_path` for the document-table rows in `ranked`. Conversations
+ * and digests are skipped — they can never be reports, so we don't pay for a
+ * lookup. Returns a map keyed by row id; ids with no row (or no path) are
+ * simply absent and treated as non-reports by the caller.
+ */
+export declare function fetchDocSourcePaths(ranked: readonly RankedResult[]): Promise<Map<string, string>>;
+/**
+ * Like {@link fetchDocSourcePaths} but also pulls `metadata.title`. Used by the
+ * locator boost, which scores query overlap against path/slug/filename/title.
+ * Conversations and digests are skipped — a locator wants a file, not a
+ * conversation. Keep this projection narrow: the boost must never fetch or
+ * inspect document bodies.
+ */
+export declare function fetchDocFields(ranked: readonly RankedResult[]): Promise<Map<string, {
+    source_path?: string;
+    title?: string;
+}>>;
+/**
+ * Stable-reorder `ranked` so report/snapshot docs sort after all non-report
+ * hits, preserving relative order within each group. Applies to `scope:"all"`
+ * only; every other scope is a no-op. Scores are carried through unchanged.
+ *
+ * `isExempt` (optional) is the locator demotion-exception hook: a report for
+ * which `isExempt(id)` returns true is treated as kept (NOT demoted), because
+ * the query explicitly asked to locate that report. Omitting it preserves the
+ * exact prior behaviour — every report is demoted.
+ */
+export declare function demoteReports(ranked: readonly RankedResult[], sourcePathById: ReadonlyMap<string, string>, scope: SearchScope, selfReportsRoot?: string, isExempt?: (id: string) => boolean): RankedResult[];
+//# sourceMappingURL=report-demotion.d.ts.map

package/dist/src/retrieval/report-demotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-demotion.d.ts","sourceRoot":"","sources":["../../../src/retrieval/report-demotion.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,SAAS,EACtB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyB9B;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAoChE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3C,KAAK,EAAE,WAAW,EAClB,eAAe,CAAC,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GACjC,YAAY,EAAE,CAehB"}

package/dist/src/retrieval/report-demotion.js

@@ -0,0 +1,169 @@
+/**
+ * Report-as-memory demotion for flat `onadit_search` (POST /search).
+ *
+ * The docs-vs-discussions retrieval eval showed generated reports/snapshots
+ * dominating default (`scope:"all"`) results — 42–62% of the top-10 on
+ * discussion-intent queries — burying conversations and trackers as if a
+ * frozen synthesis were current memory. This pushes report/snapshot docs
+ * BEHIND all non-report evidence in the default mixed surface.
+ *
+ * Deliberately narrow (the proven slice, not the whole experiment):
+ *   - It is a STABLE REORDER. Scores are never changed — "all docs score
+ *     worse" is explicitly NOT what this does. A report keeps its score and
+ *     its relative order among other reports; it just sorts after non-report
+ *     evidence of any score.
+ *   - It reuses the EXISTING trust classifier ({@link isSnapshotPath}) — no
+ *     second trust system. Generated-report detection is anchored there to
+ *     Onadit's own reports root (`selfReportsRoot`), so a client's `reports/`
+ *     folder is never demoted by path shape alone.
+ *   - It applies to `scope:"all"` ONLY — the mixed-memory default where
+ *     reports compete with conversations, which is the only surface the eval
+ *     validated. Every explicit doc-like scope (`documents`, `clients`,
+ *     `projects`) is a no-op: those are deliberate document searches where a
+ *     report (incl. a client's own `reports/` folder) may be exactly what the
+ *     asker wants, and we have no eval signal that demoting there is correct.
+ *   - No named-report exception and no discussion/doc tiebreak: those were
+ *     unproven (or, for the tiebreak, actively wrong for locator queries) in
+ *     the eval and are intentionally left out.
+ *
+ * PR2 add-on: {@link demoteReports} takes an optional `isExempt(id)` hook that
+ * exempts a single field-matched report TARGET from demotion when a locator
+ * query explicitly asked to find it. The hook is supplied only by the flag-
+ * gated locator path in the route ({@link ../server/routes/search.ts}); omitted
+ * (the default), demotion behaves exactly as the proven slice above.
+ */
+import { isSnapshotPath } from "./current-truth.js";
+import { getTable } from "../storage/tables.js";
+const DOC_TABLES = ["structured_docs", "structured_docs_local"];
+function isDocTable(t) {
+    return DOC_TABLES.includes(t);
+}
+/**
+ * Whether a source table can ever hold a report (i.e. is a document table).
+ * Lets the route skip the source_path fetch entirely for conversation-only
+ * result sets.
+ */
+export function isReportCandidateTable(t) {
+    return isDocTable(t);
+}
+/**
+ * A ranked hit is a report iff it's a document (conversations/digests never
+ * are) whose source_path matches the shared snapshot/report classifier. The
+ * classifier only treats a `reports/` doc as generated when it sits under
+ * Onadit's own reports root (`selfReportsRoot`); see {@link isSnapshotPath}.
+ */
+export function isReportHit(sourceTable, sourcePath, selfReportsRoot) {
+    return isDocTable(sourceTable) && isSnapshotPath(sourcePath, selfReportsRoot);
+}
+/**
+ * Fetch `source_path` for the document-table rows in `ranked`. Conversations
+ * and digests are skipped — they can never be reports, so we don't pay for a
+ * lookup. Returns a map keyed by row id; ids with no row (or no path) are
+ * simply absent and treated as non-reports by the caller.
+ */
+export async function fetchDocSourcePaths(ranked) {
+    const byTable = new Map();
+    for (const r of ranked) {
+        if (!isDocTable(r.source_table))
+            continue;
+        const arr = byTable.get(r.source_table) ?? [];
+        arr.push(r.id);
+        byTable.set(r.source_table, arr);
+    }
+    const out = new Map();
+    for (const [table, ids] of byTable) {
+        if (ids.length === 0)
+            continue;
+        const quoted = ids.map((i) => `'${i.replace(/'/g, "''")}'`).join(",");
+        const rows = (await getTable(table)
+            .query()
+            .where(`id IN (${quoted})`)
+            .select(["id", "source_path"])
+            .limit(ids.length)
+            .toArray());
+        for (const row of rows) {
+            if (typeof row.id === "string" && typeof row.source_path === "string") {
+                out.set(row.id, row.source_path);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Like {@link fetchDocSourcePaths} but also pulls `metadata.title`. Used by the
+ * locator boost, which scores query overlap against path/slug/filename/title.
+ * Conversations and digests are skipped — a locator wants a file, not a
+ * conversation. Keep this projection narrow: the boost must never fetch or
+ * inspect document bodies.
+ */
+export async function fetchDocFields(ranked) {
+    const byTable = new Map();
+    for (const r of ranked) {
+        if (!isDocTable(r.source_table))
+            continue;
+        const arr = byTable.get(r.source_table) ?? [];
+        arr.push(r.id);
+        byTable.set(r.source_table, arr);
+    }
+    const out = new Map();
+    for (const [table, ids] of byTable) {
+        if (ids.length === 0)
+            continue;
+        const quoted = ids.map((i) => `'${i.replace(/'/g, "''")}'`).join(",");
+        const rows = (await getTable(table)
+            .query()
+            .where(`id IN (${quoted})`)
+            .select(["id", "source_path", "metadata"])
+            .limit(ids.length)
+            .toArray());
+        for (const row of rows) {
+            if (typeof row["id"] !== "string")
+                continue;
+            const entry = {};
+            if (typeof row["source_path"] === "string")
+                entry.source_path = row["source_path"];
+            let title;
+            const meta = row["metadata"];
+            if (typeof meta === "string") {
+                try {
+                    title = JSON.parse(meta).title;
+                }
+                catch {
+                    /* ignore malformed metadata */
+                }
+            }
+            if (title !== undefined)
+                entry.title = title;
+            out.set(row["id"], entry);
+        }
+    }
+    return out;
+}
+/**
+ * Stable-reorder `ranked` so report/snapshot docs sort after all non-report
+ * hits, preserving relative order within each group. Applies to `scope:"all"`
+ * only; every other scope is a no-op. Scores are carried through unchanged.
+ *
+ * `isExempt` (optional) is the locator demotion-exception hook: a report for
+ * which `isExempt(id)` returns true is treated as kept (NOT demoted), because
+ * the query explicitly asked to locate that report. Omitting it preserves the
+ * exact prior behaviour — every report is demoted.
+ */
+export function demoteReports(ranked, sourcePathById, scope, selfReportsRoot, isExempt) {
+    if (scope !== "all")
+        return [...ranked];
+    const kept = [];
+    const demoted = [];
+    for (const r of ranked) {
+        if (isReportHit(r.source_table, sourcePathById.get(r.id), selfReportsRoot) &&
+            !isExempt?.(r.id))
+            demoted.push(r);
+        else
+            kept.push(r);
+    }
+    // Fast path: nothing to move — return the original reference's contents.
+    if (demoted.length === 0)
+        return [...ranked];
+    return [...kept, ...demoted];
+}
+//# sourceMappingURL=report-demotion.js.map

package/dist/src/retrieval/report-demotion.js.map

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

package/dist/src/retrieval/reranker.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Deterministic reranking — PRD Section 6.2, plus a small freshness boost.
+ *
+ * score = (S_sim * 0.55) + (S_rec * 0.10) + (S_qual * 0.10)
+ *       + (B_tier * 0.10) + (fixed neutral B_feed * 0.10)
+ *       + (B_hyb * 0.05) + (B_fresh * 0.05)
+ *
+ * B_fresh is a short-horizon exponential decay (half-life ~14d) on top of
+ * S_rec's gentle long-horizon decay. Added after Slice 5 daily-use
+ * validation showed just-saved rows never surfaced in top-k even for
+ * their own unique phrases: the existing S_rec barely moves (flat across
+ * a month), so freshness couldn't break near-ties against older bulk.
+ * B_fresh is additive, bounded, decays to ~0 past 2 months — it nudges
+ * the write-back loop without overriding strong older matches.
+ *
+ * All factors are deterministic (no randomness).
+ */
+import type { TableName } from "../storage/tables.js";
+import type { RetrievalMethod } from "./hybrid.js";
+/**
+ * Weight of the B_feed term. Exported so the flag-gated retrieval-feedback
+ * post-pass ({@link applyFeedbackBoost}) can re-score by the SAME weight the
+ * composite uses — keeping "apply feedback as a post-pass" mathematically
+ * identical to "rerank with that B_feed".
+ */
+export declare const W_FEED_WEIGHT = 0.1;
+/** Half-life (in days) of the short-horizon freshness decay. 14d so a row
+ *  indexed within a week still carries most of the bump; past ~2 months
+ *  B_fresh collapses to near-zero and effectively disappears. */
+export declare const FRESH_HALF_LIFE_DAYS = 14;
+export interface RerankCandidate {
+    id: string;
+    content: string;
+    /** Raw similarity score from vector search (0-1). 0 if lexical-only. */
+    raw_sim: number;
+    /** Raw BM25 score from lexical search (unnormalized). 0 if vector-only. */
+    raw_bm25: number;
+    source_table: TableName;
+    retrieval_method: RetrievalMethod;
+    /** ISO-8601 timestamp of when the item was indexed. */
+    indexed_at?: string;
+    /** Conversation quality: "high" | "medium" | "low". Absent for structured_docs. */
+    quality?: string;
+    /** Raw JSON-encoded topics array. Used by pre-rerank post-filter. */
+    topics?: string;
+    /** Raw JSON-encoded decisions array. Used by pre-rerank post-filter. */
+    decisions?: string;
+    /**
+     * Shadow retrieval-feedback boost. Positive-only v0: 1.0 is neutral, values
+     * above 1.0 are computed from opened/cited evidence. Slice 15 exposes this
+     * factor for `rift why`; ranking integration is deferred to Slice 16.
+     */
+    feedback_boost?: number;
+}
+export interface RankedResult {
+    id: string;
+    content: string;
+    score: number;
+    retrieval_method: RetrievalMethod;
+    source_table: TableName;
+    /** Breakdown of score factors (for debugging / golden-file tests). */
+    factors: ScoreFactors;
+    /** Raw BM25 score normalized by the max BM25 in the candidate set
+     *  (0 when there was no lexical hit). Exposed so downstream filters
+     *  like ContextPack's relevance floor can combine semantic and
+     *  lexical signals — `factors.S_sim` alone drops to `raw_sim` for
+     *  hybrid hits, which under-reports relevance when keyword overlap
+     *  is the real signal. */
+    bm25_normalized: number;
+}
+export interface ScoreFactors {
+    S_sim: number;
+    S_rec: number;
+    S_qual: number;
+    B_tier: number;
+    B_feed: number;
+    B_hyb: number;
+    /** Short-horizon freshness boost in [0,1]; exp(-days / 14). */
+    B_fresh: number;
+}
+/**
+ * Rerank candidates using the PRD 6.2 deterministic formula.
+ *
+ * @param candidates - merged results from hybrid search
+ * @param now - reference timestamp for recency calculation (defaults to Date.now())
+ * @returns results sorted by final score descending
+ */
+export declare function rerank(candidates: RerankCandidate[], now?: number): RankedResult[];
+export declare function clampFeedbackBoost(boost: number | undefined): number;
+/**
+ * Apply retrieval-feedback boosts to an already-reranked set (Slice 16).
+ *
+ * `rerank()` deliberately uses a FIXED neutral B_feed term (`+ W_FEED`) so the
+ * shadow ledger never moves live ranking. This post-pass is how the gated
+ * feedback flag actually applies the learned boost — kept as a separate,
+ * flag-gated step so `rerank()` and its golden tests stay byte-for-byte the
+ * current behaviour.
+ *
+ * Why a post-pass is exact: the composite score is a SUM and B_feed appears in
+ * exactly one term (`B_feed * W_FEED`). Replacing the old factor `B_old` with a
+ * new `B_new` shifts the score by exactly `(B_new - B_old) * W_FEED` — identical
+ * to having reranked with `B_new` from the start. `B_old` is whatever the prior
+ * pass recorded in `factors.B_feed` (1.0 on the live search path, which never
+ * populates `feedback_boost`), so a neutral boost is a guaranteed no-op.
+ *
+ * Determinism / no-op safety: when no candidate's boost differs from its current
+ * factor (the cold-start / empty-ledger case), the input order is returned
+ * UNCHANGED — no re-score, no re-sort — so "feedback ranking on, no learned
+ * signal yet" is provably indistinguishable from "off".
+ *
+ * @param ranked - results from {@link rerank}, already sorted by score desc
+ * @param boostOf - the learned B_feed for a result, or undefined for neutral
+ * @returns the (possibly reordered) results + how many were actually boosted
+ */
+export declare function applyFeedbackBoost(ranked: readonly RankedResult[], boostOf: (r: Pick<RankedResult, "id" | "source_table">) => number | undefined): {
+    ranked: RankedResult[];
+    appliedCount: number;
+};
+//# sourceMappingURL=reranker.d.ts.map

package/dist/src/retrieval/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/retrieval/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAUnD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,MAAS,CAAC;AAGpC;;iEAEiE;AACjE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAqBvC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,gBAAgB,EAAE,eAAe,CAAC;IAClC,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,eAAe,CAAC;IAClC,YAAY,EAAE,SAAS,CAAC;IACxB,sEAAsE;IACtE,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;8BAK0B;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,UAAU,EAAE,eAAe,EAAE,EAC7B,GAAG,GAAE,MAAmB,GACvB,YAAY,EAAE,CA0ChB;AA6DD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,cAAc,CAAC,KAAK,MAAM,GAAG,SAAS,GAC5E;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAkBlD"}

package/dist/src/retrieval/reranker.js

@@ -0,0 +1,220 @@
+import { isReportCardRowId } from "../ingestion/report-cards.js";
+// --- Weights (PRD 6.2 + Slice 5 freshness boost) ---
+const W_SIM = 0.55;
+const W_REC = 0.10;
+const W_QUAL = 0.10;
+const W_TIER = 0.10;
+const W_FEED = 0.10;
+const W_HYB = 0.05;
+/**
+ * Weight of the B_feed term. Exported so the flag-gated retrieval-feedback
+ * post-pass ({@link applyFeedbackBoost}) can re-score by the SAME weight the
+ * composite uses — keeping "apply feedback as a post-pass" mathematically
+ * identical to "rerank with that B_feed".
+ */
+export const W_FEED_WEIGHT = W_FEED;
+/** Small additive boost for just-indexed rows; see B_fresh doc below. */
+const W_FRESH = 0.05;
+/** Half-life (in days) of the short-horizon freshness decay. 14d so a row
+ *  indexed within a week still carries most of the bump; past ~2 months
+ *  B_fresh collapses to near-zero and effectively disappears. */
+export const FRESH_HALF_LIFE_DAYS = 14;
+const FEEDBACK_MIN = 1.0;
+const FEEDBACK_MAX = 1.25;
+// --- Tier boosts (PRD 6.2 + assumptions A2) ---
+const TIER_BOOST = {
+    conversations_hot: 1.0,
+    digests: 1.1,
+    conversations_cold: 0.7,
+    structured_docs: 1.0, // A2: same as hot
+};
+// --- Quality mapping ---
+const QUALITY_SCORE = {
+    high: 1.0,
+    medium: 0.7,
+    low: 0.4,
+};
+/**
+ * Rerank candidates using the PRD 6.2 deterministic formula.
+ *
+ * @param candidates - merged results from hybrid search
+ * @param now - reference timestamp for recency calculation (defaults to Date.now())
+ * @returns results sorted by final score descending
+ */
+export function rerank(candidates, now = Date.now()) {
+    // Compute max BM25 score across all candidates for normalization.
+    // Lexical-only candidates use normalized BM25 as S_sim so that
+    // stronger keyword matches score higher than weaker ones.
+    const maxBm25 = candidates.reduce((max, c) => Math.max(max, c.raw_bm25), 0);
+    // Keyword scores are put on the vector scale of this pool: the best keyword
+    // match scores like the best semantic match, not a flat 1.0 that no cosine
+    // similarity reaches (voyage-3-lite tops out near 0.7). Without that, once
+    // keyword search covers every row, a pile of older keyword matches buries a
+    // newer row that only vector search found. With no vector hits (no key, or
+    // the embedding was skipped) the scale is 1 and keyword ranking is unchanged.
+    const maxSim = candidates.reduce((max, c) => (c.retrieval_method === "lexical" ? max : Math.max(max, c.raw_sim)), 0);
+    const lexicalScale = maxSim > 0 ? Math.min(1, maxSim) : 1;
+    const ranked = candidates.map((c) => {
+        const factors = computeFactors(c, now, maxBm25, lexicalScale);
+        const score = factors.S_sim * W_SIM +
+            factors.S_rec * W_REC +
+            factors.S_qual * W_QUAL +
+            factors.B_tier * W_TIER +
+            W_FEED + // neutral baseline, preserving the historical fixed B_feed=1.0 term
+            factors.B_hyb * W_HYB +
+            factors.B_fresh * W_FRESH;
+        const bm25_normalized = maxBm25 > 0 ? Math.min(1, c.raw_bm25 / maxBm25) : 0;
+        return {
+            id: c.id,
+            content: c.content,
+            score,
+            retrieval_method: c.retrieval_method,
+            source_table: c.source_table,
+            factors,
+            bm25_normalized,
+        };
+    });
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked;
+}
+function computeFactors(c, now, maxBm25, lexicalScale = 1) {
+    // S_sim: vector hits use cosine similarity (already [0,1]). Keyword hits use
+    // BM25 normalized by the pool max, scaled onto the pool's vector scale (see
+    // rerank). A hybrid hit takes the stronger of its two signals, so matching
+    // both ways never scores below matching by keyword alone.
+    const S_lex = maxBm25 > 0 ? Math.min(1, c.raw_bm25 / maxBm25) * lexicalScale : 0;
+    let S_sim;
+    if (c.retrieval_method === "lexical") {
+        S_sim = S_lex;
+    }
+    else if (c.retrieval_method === "hybrid") {
+        S_sim = Math.max(Math.max(0, Math.min(1, c.raw_sim)), S_lex);
+    }
+    else {
+        S_sim = Math.max(0, Math.min(1, c.raw_sim));
+    }
+    // beta.28 card guard (docs/10): a report index card is a short keyword-dense
+    // pointer, so its BM25 can spike on an incidental token (e.g. a path fragment
+    // in the summary) with ZERO semantic match. A lexical-only card (vector miss
+    // ⇒ raw_sim == 0) must NOT ride the BM25 normalization to a high S_sim and
+    // outrank semantically-matched discussions — that was the gate's one
+    // false-#1. Card-specific: real cards (vector/hybrid hits) keep their cosine
+    // S_sim, so locator coverage is untouched. Identified by the canonical
+    // `report_card:` id, the same marker the SQL retrieval exclusion uses.
+    const isCard = isReportCardRowId(c.id);
+    if (isCard && c.retrieval_method === "lexical") {
+        S_sim = 0;
+    }
+    // S_rec: recency score = 1 / (1 + days_since_indexed * 0.01)
+    const S_rec = computeRecency(c.indexed_at, now);
+    // S_qual: conversation quality; defaults to 1.0 for structured_docs (A1)
+    const S_qual = computeQuality(c.quality, c.source_table);
+    // B_tier: tier boost based on source table. Cards get NO document tier
+    // advantage — a pointer must not outrank a real answer on tier alone. Today
+    // structured_docs is already neutral (1.0 == conversations_hot), so this is a
+    // no-op guard that stays correct if the doc tier is ever raised.
+    const B_tier = isCard
+        ? Math.min(TIER_BOOST[c.source_table] ?? 1.0, 1.0)
+        : (TIER_BOOST[c.source_table] ?? 1.0);
+    // B_feed: positive-only retrieval feedback. Cold start is exactly neutral.
+    const B_feed = clampFeedbackBoost(c.feedback_boost);
+    // B_hyb: 1.3 if found in both vector and lexical paths
+    const B_hyb = c.retrieval_method === "hybrid" ? 1.3 : 1.0;
+    // B_fresh: short-horizon additive freshness boost; see top-of-file doc.
+    const B_fresh = computeFreshness(c.indexed_at, now);
+    return { S_sim, S_rec, S_qual, B_tier, B_feed, B_hyb, B_fresh };
+}
+export function clampFeedbackBoost(boost) {
+    if (typeof boost !== "number" || Number.isNaN(boost))
+        return 1.0;
+    return Math.max(FEEDBACK_MIN, Math.min(FEEDBACK_MAX, boost));
+}
+/**
+ * Apply retrieval-feedback boosts to an already-reranked set (Slice 16).
+ *
+ * `rerank()` deliberately uses a FIXED neutral B_feed term (`+ W_FEED`) so the
+ * shadow ledger never moves live ranking. This post-pass is how the gated
+ * feedback flag actually applies the learned boost — kept as a separate,
+ * flag-gated step so `rerank()` and its golden tests stay byte-for-byte the
+ * current behaviour.
+ *
+ * Why a post-pass is exact: the composite score is a SUM and B_feed appears in
+ * exactly one term (`B_feed * W_FEED`). Replacing the old factor `B_old` with a
+ * new `B_new` shifts the score by exactly `(B_new - B_old) * W_FEED` — identical
+ * to having reranked with `B_new` from the start. `B_old` is whatever the prior
+ * pass recorded in `factors.B_feed` (1.0 on the live search path, which never
+ * populates `feedback_boost`), so a neutral boost is a guaranteed no-op.
+ *
+ * Determinism / no-op safety: when no candidate's boost differs from its current
+ * factor (the cold-start / empty-ledger case), the input order is returned
+ * UNCHANGED — no re-score, no re-sort — so "feedback ranking on, no learned
+ * signal yet" is provably indistinguishable from "off".
+ *
+ * @param ranked - results from {@link rerank}, already sorted by score desc
+ * @param boostOf - the learned B_feed for a result, or undefined for neutral
+ * @returns the (possibly reordered) results + how many were actually boosted
+ */
+export function applyFeedbackBoost(ranked, boostOf) {
+    let appliedCount = 0;
+    const rescored = ranked.map((r) => {
+        const B_new = clampFeedbackBoost(boostOf(r));
+        const B_old = r.factors.B_feed;
+        if (B_new === B_old)
+            return r;
+        appliedCount += 1;
+        return {
+            ...r,
+            score: r.score + (B_new - B_old) * W_FEED,
+            factors: { ...r.factors, B_feed: B_new },
+        };
+    });
+    // No effective boost → preserve the exact input order (no re-sort), so an
+    // empty/neutral ledger can never perturb ranking.
+    if (appliedCount === 0)
+        return { ranked: rescored, appliedCount };
+    rescored.sort((a, b) => b.score - a.score);
+    return { ranked: rescored, appliedCount };
+}
+/**
+ * B_fresh = exp(-daysSince / FRESH_HALF_LIFE_DAYS).
+ *
+ * Returns 0 (no boost) when `indexed_at` is missing or unparseable — that
+ * matches the "row has no freshness signal" case. The formula collapses to
+ * near-zero past ~2 months, so older rows see essentially no effect.
+ */
+function computeFreshness(indexedAt, now) {
+    if (!indexedAt)
+        return 0;
+    const indexedMs = new Date(indexedAt).getTime();
+    if (Number.isNaN(indexedMs))
+        return 0;
+    const daysSince = Math.max(0, (now - indexedMs) / (1000 * 60 * 60 * 24));
+    return Math.exp(-daysSince / FRESH_HALF_LIFE_DAYS);
+}
+/**
+ * S_rec = 1 / (1 + days_since_indexed * 0.01)
+ *
+ * If indexed_at is missing, returns 0.5 (neutral).
+ */
+function computeRecency(indexedAt, now) {
+    if (!indexedAt)
+        return 0.5;
+    const indexedMs = new Date(indexedAt).getTime();
+    if (Number.isNaN(indexedMs))
+        return 0.5;
+    const daysSince = Math.max(0, (now - indexedMs) / (1000 * 60 * 60 * 24));
+    return 1 / (1 + daysSince * 0.01);
+}
+/**
+ * S_qual: quality score from conversation metadata.
+ * Defaults to 1.0 for structured_docs (A1) and digests.
+ */
+function computeQuality(quality, sourceTable) {
+    if (sourceTable === "structured_docs" || sourceTable === "digests") {
+        return 1.0;
+    }
+    if (!quality)
+        return 1.0;
+    return QUALITY_SCORE[quality] ?? 1.0;
+}
+//# sourceMappingURL=reranker.js.map

package/dist/src/retrieval/reranker.js.map

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

package/dist/src/retrieval/stitch-chunks.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Read-side reassembly of chunk siblings for the `expand` path.
+ *
+ * Index-time chunking seeds every chunk N+1 with an overlap tail copied from the
+ * end of chunk N (see `overlapTail` in `../ingestion/chunk-text.ts`): the start of
+ * one chunk literally duplicates a suffix of the previous one. Naively
+ * concatenating adjacent chunks would print that shared region twice and read as
+ * broken. `stitchChunkContents` joins an ordered run of chunks back together,
+ * removing the duplicated seam so each overlap region appears exactly once.
+ *
+ * Only contiguous index ranges are stitched (the `middle`/`full` expand windows
+ * are both contiguous). A genuine gap (a missing index — e.g. a partially-written
+ * set) is rendered with an explicit boundary marker rather than de-overlapped
+ * across, since non-adjacent chunks share no seam.
+ *
+ * Interior gaps fall out naturally (a missing index between two present ones).
+ * Edge gaps do not: chunks present for [1,2] of an expected [0,2] range have no
+ * absent index *between* siblings, so a caller that knows the expected range
+ * passes it via `expectedStart`/`expectedEnd` to render the missing leading or
+ * trailing section explicitly, instead of returning a partial body that reads as
+ * a whole one.
+ */
+/**
+ * Maximum seam length searched when de-overlapping. The index-time overlap tail
+ * is bounded by `DEFAULT_CHUNK_OPTIONS.overlapChars` (216), so a real seam is
+ * always well under this; the cap is generous slack against future chunker
+ * tuning while keeping the longest-common-overlap scan cheap (≤ cap² char
+ * comparisons per seam). We take the LONGEST matching suffix/prefix so a real
+ * 216-char seam is removed in full; a coincidental longer match in prose is
+ * vanishingly unlikely and would only ever drop genuinely duplicated text.
+ */
+export declare const MAX_SEAM_OVERLAP_CHARS = 512;
+export interface StitchChunk {
+    /** 0-based chunk ordinal within the parent set. */
+    index: number;
+    /** The chunk's stored content. */
+    content: string;
+}
+export interface StitchResult {
+    /** Reassembled, de-overlapped content. */
+    text: string;
+    /** How many chunk rows were combined into {@link text}. */
+    sectionsUsed: number;
+    /** True when one or more index gaps were bridged with a boundary marker. */
+    hasGaps: boolean;
+    /** Raw chunk offsets in the returned body, including de-overlapped seams. */
+    chunkStarts?: Map<number, number>;
+}
+export interface StitchOptions {
+    trackPositions?: boolean;
+    /** Longest seam searched when de-overlapping adjacent chunks. */
+    maxSeam?: number;
+    /**
+     * Lowest chunk index the caller expected in this run. When the lowest present
+     * index is greater, the leading section(s) are rendered as an explicit
+     * omission marker (an edge gap a between-siblings scan can't detect).
+     */
+    expectedStart?: number;
+    /**
+     * Highest chunk index the caller expected in this run. When the highest
+     * present index is lower, the trailing section(s) are rendered as an explicit
+     * omission marker.
+     */
+    expectedEnd?: number;
+}
+/**
+ * Stitch an ordered run of chunk siblings into one body, removing the duplicated
+ * overlap at each adjacent seam. Input need not be pre-sorted; duplicate indices
+ * keep the first occurrence. Returns the empty string for an empty input.
+ *
+ * Pass `expectedStart`/`expectedEnd` to also surface missing leading/trailing
+ * sections (edge gaps) as omission markers; without them only interior gaps are
+ * marked.
+ */
+export declare function stitchChunkContents(chunks: StitchChunk[], opts?: StitchOptions): StitchResult;
+//# sourceMappingURL=stitch-chunks.d.ts.map