@getrift/rift 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/src/observability/retrieval-feedback.js

@@ -0,0 +1,231 @@
+/**
+ * Retrieval feedback ledger.
+ *
+ * This is append-only JSONL by design. v0 records positive signals only:
+ * evidence opened via `rift_open_evidence` and evidence cited via
+ * `rift_log_outcome`. Returned-but-not-opened hits are not credit; they are
+ * only the denominator/rank context that lets us discount position bias.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { FRESH_HALF_LIFE_DAYS } from "../retrieval/reranker.js";
+export const RETRIEVAL_FEEDBACK_FILE = "retrieval-feedback.jsonl";
+export const B_FEED_NEUTRAL = 1.0;
+export const B_FEED_MAX = 1.25;
+const BOOST_SATURATION_CREDIT = 4;
+export function retrievalFeedbackPath(dataDir) {
+    return path.join(dataDir, "observability", RETRIEVAL_FEEDBACK_FILE);
+}
+export function appendRetrievalFeedbackEvent(dataDir, input) {
+    const timestamp = (input.now ?? new Date()).toISOString();
+    const event = {
+        timestamp,
+        type: input.type,
+        stable_evidence_key: input.identity.stable_evidence_key,
+        evidence_kind: input.identity.evidence_kind,
+        source_table: input.identity.source_table,
+        source_id: input.identity.source_id,
+        ...(input.identity.source_path ? { source_path: input.identity.source_path } : {}),
+        ...(input.identity.parent_id ? { parent_id: input.identity.parent_id } : {}),
+        ...(input.identity.digest_id ? { digest_id: input.identity.digest_id } : {}),
+        ...(input.session_id ? { session_id: input.session_id } : {}),
+        ...(input.tool_call_id ? { tool_call_id: input.tool_call_id } : {}),
+        ...(input.outcome_id ? { outcome_id: input.outcome_id } : {}),
+        ...(input.project ? { project: input.project } : {}),
+        ...(input.intent ? { intent: input.intent } : {}),
+        ...(input.query ? { query: input.query } : {}),
+        ...(input.task ? { task: input.task } : {}),
+        ...(input.rank_at_retrieval !== undefined
+            ? { rank_at_retrieval: input.rank_at_retrieval }
+            : {}),
+        ...(input.result_count !== undefined ? { result_count: input.result_count } : {}),
+        ...(input.context_pack_bucket ? { context_pack_bucket: input.context_pack_bucket } : {}),
+        ...(input.position_in_bucket !== undefined
+            ? { position_in_bucket: input.position_in_bucket }
+            : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
+    };
+    const dedupe = input.dedupe_key ?? defaultDedupeKey(event);
+    if (dedupe)
+        event.dedupe_key = dedupe;
+    if (event.type !== "feedback_reset" && dedupe) {
+        // v0 is single-user and append-only: read the small local ledger to dedupe
+        // repeated tool calls. Replace with an indexed/locked projection before
+        // high-volume or multi-writer use.
+        const existing = readRetrievalFeedbackEvents(dataDir).find((e) => e.dedupe_key === dedupe);
+        if (existing)
+            return { event: existing, written: false, duplicate: true };
+    }
+    const file = retrievalFeedbackPath(dataDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(event) + "\n", "utf-8");
+    return { event, written: true, duplicate: false };
+}
+export function appendFeedbackReset(dataDir, input) {
+    return appendRetrievalFeedbackEvent(dataDir, {
+        type: "feedback_reset",
+        identity: input.identity,
+        ...(input.session_id ? { session_id: input.session_id } : {}),
+        ...(input.project ? { project: input.project } : {}),
+        ...(input.intent ? { intent: input.intent } : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.now ? { now: input.now } : {}),
+        dedupe_key: `reset:${input.identity.stable_evidence_key}:${input.now?.toISOString() ?? crypto.randomUUID()}`,
+    });
+}
+export function readRetrievalFeedbackEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(retrievalFeedbackPath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed["timestamp"] === "string" &&
+                typeof parsed["type"] === "string" &&
+                typeof parsed["stable_evidence_key"] === "string") {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Tolerate corrupt lines; one bad append must not erase the ledger.
+        }
+    }
+    return out;
+}
+export function computeFeedbackBoosts(events, stableEvidenceKeys, scope = {}) {
+    const nowMs = (scope.now ?? new Date()).getTime();
+    const out = new Map();
+    for (const key of stableEvidenceKeys) {
+        const scopedEvents = events.filter((e) => e.stable_evidence_key === key);
+        // Only events that have actually occurred (parseable, not future-dated)
+        // count. A future-dated reset must not suppress real past feedback, and a
+        // future-dated positive must not earn (undecayed) credit before its time.
+        const resets = scopedEvents.filter((e) => e.type === "feedback_reset" &&
+            scopeMatches(e, scope) &&
+            hasOccurred(eventTimeMs(e), nowMs));
+        const positives = scopedEvents.filter((e) => isPositiveEvent(e) &&
+            scopeMatches(e, scope) &&
+            hasOccurred(eventTimeMs(e), nowMs) &&
+            !isResetBy(e, resets));
+        const credit = positives.reduce((sum, e) => sum + eventCredit(e, nowMs), 0);
+        const positiveCount = positives.length;
+        const B_feed = credit <= 0
+            ? B_FEED_NEUTRAL
+            : B_FEED_NEUTRAL +
+                (B_FEED_MAX - B_FEED_NEUTRAL) *
+                    (1 - Math.exp(-credit / BOOST_SATURATION_CREDIT));
+        out.set(key, {
+            stable_evidence_key: key,
+            B_feed,
+            weighted_credit: credit,
+            positive_event_count: positiveCount,
+            reset_count: resets.length,
+            applied: false,
+        });
+    }
+    return out;
+}
+export function explainFeedback(dataDir, stableEvidenceKey, scope = {}) {
+    const events = readRetrievalFeedbackEvents(dataDir);
+    const boost = computeFeedbackBoosts(events, [stableEvidenceKey], scope).get(stableEvidenceKey) ?? {
+        stable_evidence_key: stableEvidenceKey,
+        B_feed: B_FEED_NEUTRAL,
+        weighted_credit: 0,
+        positive_event_count: 0,
+        reset_count: 0,
+        applied: false,
+    };
+    return {
+        ...boost,
+        events: events
+            .filter((e) => e.stable_evidence_key === stableEvidenceKey)
+            .filter((e) => scopeMatches(e, scope)),
+    };
+}
+function defaultDedupeKey(event) {
+    if (event.type === "feedback_reset")
+        return undefined;
+    const session = event.session_id ?? event.tool_call_id;
+    if (!session)
+        return undefined;
+    // Dedupe is scope-aware: the same evidence opened/cited in the same session
+    // but under a different (project, intent) is a distinct positive signal for
+    // that scope, not a duplicate. Keying only on type:session:key would silently
+    // drop the second scope's credit and make scoped why/reset lie.
+    const project = event.project ?? "";
+    const intent = event.intent ?? "";
+    return `${event.type}:${session}:${project}:${intent}:${event.stable_evidence_key}`;
+}
+function isPositiveEvent(e) {
+    return e.type === "evidence_opened" || e.type === "evidence_cited";
+}
+function scopeMatches(e, scope) {
+    if (scope.project !== undefined && e.project !== scope.project)
+        return false;
+    if (!intentMatches(e.intent, scope.intent))
+        return false;
+    return true;
+}
+function intentMatches(eventIntent, scopeIntent) {
+    if (scopeIntent === undefined)
+        return true;
+    if (scopeIntent === "blended")
+        return eventIntent !== undefined;
+    return eventIntent === scopeIntent || eventIntent === "blended";
+}
+function isResetBy(event, resets) {
+    const eventMs = new Date(event.timestamp).getTime();
+    return resets.some((reset) => {
+        const resetMs = new Date(reset.timestamp).getTime();
+        if (Number.isNaN(resetMs) || Number.isNaN(eventMs))
+            return false;
+        if (resetMs < eventMs)
+            return false;
+        if (reset.project !== undefined && event.project !== reset.project)
+            return false;
+        if (!intentMatches(event.intent, reset.intent))
+            return false;
+        return true;
+    });
+}
+function eventTimeMs(event) {
+    return new Date(event.timestamp).getTime();
+}
+/**
+ * Whether an event has actually occurred relative to the evaluation time.
+ * False for unparseable (NaN) timestamps and for future-dated rows — neither
+ * should earn credit, and a future-dated reset must not retroactively suppress
+ * real past feedback up to its timestamp.
+ */
+function hasOccurred(eventMs, nowMs) {
+    return !Number.isNaN(eventMs) && eventMs <= nowMs;
+}
+function eventCredit(event, nowMs) {
+    const eventMs = new Date(event.timestamp).getTime();
+    // A corrupt/unparseable timestamp earns no credit. Returning 0 (rather than
+    // treating it as days=0 → full undecayed credit) keeps a malformed row from
+    // silently inflating B_feed, and mirrors how isResetBy() skips NaN resets.
+    if (Number.isNaN(eventMs))
+        return 0;
+    const days = Math.max(0, (nowMs - eventMs) / 86_400_000);
+    const decay = Math.exp(-days / FRESH_HALF_LIFE_DAYS);
+    const typeWeight = event.type === "evidence_cited" ? 1.5 : 1.0;
+    return typeWeight * positionBiasWeight(event) * decay;
+}
+export function positionBiasWeight(event) {
+    const position = event.context_pack_bucket && typeof event.position_in_bucket === "number"
+        ? event.position_in_bucket
+        : event.rank_at_retrieval;
+    if (typeof position !== "number" || position < 1)
+        return 1.0;
+    return Math.min(3, Math.sqrt(position));
+}
+//# sourceMappingURL=retrieval-feedback.js.map

package/dist/src/observability/retrieval-feedback.js.map

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

package/dist/src/observability/rift-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rift-context.d.ts","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAcrE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,MAAM,CAqER;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAU/B"}
+{"version":3,"file":"rift-context.d.ts","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAcrE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,MAAM,CA8ER;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAU/B"}

package/dist/src/observability/rift-context.js

@@ -87,6 +87,9 @@ export function generateCapabilityMap(counts, opts) {
     lines.push("- `rift_search` — broad search across all memory classes. Start here when you do not know which class holds the answer.");
     lines.push("- `rift_conversations_search` — conversation-specific search with structured filters (source, domain, intent, decisions, topics). Use when the question is clearly about prior chats.");
     lines.push("- `rift_context_pack` — compact bucketed context for an active task (decisions / constraints / examples / rules). Byte-bounded; never returns raw transcripts. Use to steer an agent, not to fetch a ranked hit list.");
+    lines.push("- `rift_open_evidence` — open one exact compact hit when it is worth inspecting; records a shadow-only feedback event after a successful open.");
+    lines.push("- `rift_log_outcome` — after substantive work, log what happened and cite only evidence actually used; this records shadow feedback without counting returned-but-unused hits.");
+    lines.push("- `rift_why_evidence` / `rift_forget_evidence_feedback` — inspect or reset learned retrieval feedback for a source.");
     lines.push("- `rift_status` — system and capability overview (this map). Not for content retrieval.");
     lines.push("");
     lines.push("## Default Behavior");

package/dist/src/observability/rift-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"rift-context.js","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,IAAI,MAAM,WAAW,CAAC;AAiB7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,uEAAuE;AACvE,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1D,QAAQ,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE;QACvC,QAAQ,CAAC,uBAAuB,CAAC,CAAC,SAAS,EAAE;QAC7C,QAAQ,CAAC,mBAAmB,CAAC,CAAC,SAAS,EAAE;QACzC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,SAAS,EAAE;QAC1C,QAAQ,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE;KAChC,CAAC,CAAC;IACH,OAAO;QACL,eAAe,EAAE,EAAE,GAAG,OAAO;QAC7B,iBAAiB,EAAE,GAAG;QACtB,kBAAkB,EAAE,IAAI;QACxB,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAwB,EACxB,IAA2B;IAE3B,MAAM,kBAAkB,GAAG,MAAM,CAAC,iBAAiB,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAEhF,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,4RAA4R,CAC7R,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CACR,gHAAgH,CACjH,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CACR,uEAAuE,kBAAkB,WAAW,CACrG,CAAC;IACF,KAAK,CAAC,IAAI,CACR,4DAA4D,MAAM,CAAC,OAAO,WAAW,CACtF,CAAC;IACF,KAAK,CAAC,IAAI,CACR,wEAAwE,MAAM,CAAC,eAAe,WAAW,CAC1G,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CACR,yHAAyH,CAC1H,CAAC;IACF,KAAK,CAAC,IAAI,CACR,uLAAuL,CACxL,CAAC;IACF,KAAK,CAAC,IAAI,CACR,uNAAuN,CACxN,CAAC;IACF,KAAK,CAAC,IAAI,CACR,yFAAyF,CAC1F,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;IAC1E,KAAK,CAAC,IAAI,CACR,0GAA0G,CAC3G,CAAC;IACF,KAAK,CAAC,IAAI,CACR,wFAAwF,CACzF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CACR,gHAAgH,CACjH,CAAC;IACF,KAAK,CAAC,IAAI,CACR,0GAA0G,CAC3G,CAAC;IACF,KAAK,CAAC,IAAI,CACR,iFAAiF,CAClF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAe,EACf,aAAqB;IAErB,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,EAAE,aAAa,CAAC,CAAC;QACxE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oCAAoC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACzF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"rift-context.js","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/tool-usage-stats.d.ts

@@ -35,6 +35,19 @@ export interface UsageWindow {
      * (no fabricated number) and naturally age out as fresh rows accumulate.
      */
     context_tokens_delivered_estimate: number;
+    /**
+     * The honest "reading saved" figure: summed `max(0, source − delivered)`
+     * over context hits, where `source` is the full token size of the rows a
+     * recall was drawn from (`source_tokens_estimate`) and `delivered` is the
+     * compact slice Rift actually returned. This is the menu's headline value
+     * number — it grows with the haystack a recall searched, not with how much
+     * text Rift handed back, so precise retrieval reads as strength rather than
+     * a suspiciously small count. Self-zeroes on `detail=full` pulls (the agent
+     * asked for the whole row, so nothing was saved) and on legacy rows lacking
+     * `source_tokens_estimate` (contributes 0, ages in as fresh rows land — no
+     * fabricated number).
+     */
+    context_tokens_saved_estimate: number;
 }
 /**
  * Precise-lookup health: aggregates over rift_search calls whose

package/dist/src/observability/tool-usage-stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAsBtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,4BAA4B,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,iCAAiC,EAAE,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,kBAAkB,CAAC;CACpC;AA8ED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CA2Fd"}
+{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAsBtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,4BAA4B,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,iCAAiC,EAAE,MAAM,CAAC;IAC1C;;;;;;;;;;;OAWG;IACH,6BAA6B,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,kBAAkB,CAAC;CACpC;AA+ED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CA0Gd"}

package/dist/src/observability/tool-usage-stats.js

@@ -21,6 +21,7 @@ function emptyWindow() {
         context_hits: 0,
         context_tokens_measured_hits: 0,
         context_tokens_delivered_estimate: 0,
+        context_tokens_saved_estimate: 0,
     };
 }
 /**
@@ -112,8 +113,19 @@ export function aggregateUsage(entries, now = new Date()) {
             ? tokensFromBytes(entry.response_text_bytes)
             : 0;
         const measuredHit = hit && typeof entry.response_text_bytes === "number" ? 1 : 0;
+        // Reading saved = full source size of the recalled rows minus the slice
+        // Rift delivered. Needs BOTH the source advisory and the delivered bytes;
+        // missing either (legacy rows, shapes without per-hit size) contributes 0.
+        // Clamped at 0 so a `detail=full` pull (delivered ≈ source) never reads as
+        // negative savings.
+        const saved = hit &&
+            typeof entry.source_tokens_estimate === "number" &&
+            typeof entry.response_text_bytes === "number"
+            ? Math.max(0, entry.source_tokens_estimate - delivered)
+            : 0;
         summary.all_time.calls += 1;
         summary.all_time.context_tokens_delivered_estimate += delivered;
+        summary.all_time.context_tokens_saved_estimate += saved;
         summary.all_time.context_tokens_measured_hits += measuredHit;
         summary.all_time.context_hits += hit;
         summary.by_tool[tool] = (summary.by_tool[tool] ?? 0) + 1;
@@ -142,18 +154,21 @@ export function aggregateUsage(entries, now = new Date()) {
         if (ts >= monthStartMs) {
             summary.month.calls += 1;
             summary.month.context_tokens_delivered_estimate += delivered;
+            summary.month.context_tokens_saved_estimate += saved;
             summary.month.context_tokens_measured_hits += measuredHit;
             summary.month.context_hits += hit;
         }
         if (ts >= weekStartMs) {
             summary.week.calls += 1;
             summary.week.context_tokens_delivered_estimate += delivered;
+            summary.week.context_tokens_saved_estimate += saved;
             summary.week.context_tokens_measured_hits += measuredHit;
             summary.week.context_hits += hit;
         }
         if (ts >= todayStartMs && ts < todayEndMs) {
             summary.today.calls += 1;
             summary.today.context_tokens_delivered_estimate += delivered;
+            summary.today.context_tokens_saved_estimate += saved;
             summary.today.context_tokens_measured_hits += measuredHit;
             summary.today.context_hits += hit;
         }

package/dist/src/observability/tool-usage-stats.js.map

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

package/dist/src/observability/tool-usage.d.ts

@@ -59,8 +59,35 @@ export interface ToolUsageEntry {
      * duplicates the same data) so the resulting tokens-delivered estimate
      * isn't double-counted. Recorded on every successful call so it can
      * survive retrieval-tool / non-retrieval-tool reclassifications later.
+     *
+     * NOTE (Slice 1, point-of-use receipt): when `RIFT_RECEIPT` is on, the
+     * retrieval handlers prepend a short `_Rift recalled …_` line to this text
+     * BEFORE the logger runs, so those bytes are included here and thus in
+     * `delivered`. This is intentional — Rift genuinely sent that text to the
+     * model — and only makes the "reading saved" figure slightly more
+     * conservative (delivered grows, saved shrinks). It does mean toggling
+     * `RIFT_RECEIPT` perturbs delivered/saved by ~the receipt's size; that is
+     * accepted rather than special-cased, because this field is defined as the
+     * literal model-visible text and must not under-report what was sent.
      */
     response_text_bytes?: number;
+    /**
+     * Retrieval tools only: summed full-parent `content_tokens_estimate`
+     * behind every returned hit (search/conversations: `results[]`;
+     * context_pack: `examples[]` + `rules[]`), preferring the
+     * `expand.params` size advisory so stitched chunked `detail="middle"`
+     * hits count the full parent rather than the returned window. This is the
+     * haystack a compact recall was drawn from — the reading the agent would
+     * have faced to find the same answer by hand. Paired with
+     * `response_text_bytes` it yields the honest "reading saved" figure
+     * (`source − delivered`), which self-zeroes on `detail=full` pulls (where
+     * the agent asked for the whole row, so nothing was saved). Computed with
+     * the same `ceil(bytes/4)` estimator as delivered tokens, so the two are
+     * directly comparable. Absent on legacy rows and on tools/shapes that
+     * carry no per-hit size advisory (contributes 0, never a fabricated
+     * number).
+     */
+    source_tokens_estimate?: number;
 }
 export declare function sanitizeArgs(raw: Record<string, unknown>): Record<string, unknown>;
 /**
@@ -119,6 +146,35 @@ export declare function extractSearchResultMeta(mcpResult: {
     has_truncated_content?: boolean;
     max_content_tokens_estimate?: number;
 };
+/**
+ * Sum the full-source-row token estimate across every returned hit, for any
+ * retrieval tool. Search and conversations-search expose hits on
+ * `structuredContent.results[]`; context_pack carries its sized rows on
+ * `examples[]` and `rules[]` (decisions/constraints/evidence are inline
+ * snippets with no backing-row size, so they contribute nothing). The size
+ * advisory (`content_tokens_estimate`) is already computed per hit by the
+ * compact DTO builder, so this is a cheap walk.
+ *
+ * Per hit we take the FULL-PARENT size advisory: `expand.params
+ * .content_tokens_estimate` when present, else the top-level
+ * `content_tokens_estimate`. They are equal for ordinary single-row hits, but
+ * for a stitched chunked `detail="middle"` hit the top-level value is only the
+ * returned window while `expand.params` advertises the full parent body the
+ * recall was drawn from (see compact.ts buildStitched*). Using the parent size
+ * keeps "reading saved" honest — it's the haystack a recall searched, not the
+ * slice it happened to return.
+ *
+ * Returns `undefined` — not `0` — for non-retrieval tools and for response
+ * shapes that carry no per-hit size at all, so the caller can omit the field
+ * rather than log a fabricated zero (mirroring how legacy rows stay absent).
+ */
+export declare function extractSourceTokens(tool: string, mcpResult: {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}): number | undefined;
 /**
  * Try to parse the typed error code (`id_not_found`, `ambiguous_id`, …)
  * out of a failure response's text channel. `formatError` formats typed

package/dist/src/observability/tool-usage.d.ts.map

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

package/dist/src/observability/tool-usage.js

@@ -49,6 +49,7 @@ const RETRIEVAL_TOOLS = new Set([
     "rift_search",
     "rift_conversations_search",
     "rift_context_pack",
+    "rift_open_evidence",
 ]);
 /**
  * Per-tool extractor for `(result_count, degraded)` derived from the MCP
@@ -89,6 +90,12 @@ function extractRetrievalSignal(tool, mcpResult) {
             out.degraded = sc["degraded"];
         return out;
     }
+    if (tool === "rift_open_evidence") {
+        if (!sc)
+            return {};
+        const count = sc["result"] && typeof sc["result"] === "object" ? 1 : 0;
+        return { count };
+    }
     // Search tools: prefer structuredContent, fall back to JSON-on-text for
     // backwards compatibility with the pre-Slice-1 response shape.
     const fromStructured = sc?.["results"];
@@ -185,6 +192,81 @@ export function extractSearchResultMeta(mcpResult) {
         out.max_content_tokens_estimate = maxTokens;
     return out;
 }
+/**
+ * Sum the full-source-row token estimate across every returned hit, for any
+ * retrieval tool. Search and conversations-search expose hits on
+ * `structuredContent.results[]`; context_pack carries its sized rows on
+ * `examples[]` and `rules[]` (decisions/constraints/evidence are inline
+ * snippets with no backing-row size, so they contribute nothing). The size
+ * advisory (`content_tokens_estimate`) is already computed per hit by the
+ * compact DTO builder, so this is a cheap walk.
+ *
+ * Per hit we take the FULL-PARENT size advisory: `expand.params
+ * .content_tokens_estimate` when present, else the top-level
+ * `content_tokens_estimate`. They are equal for ordinary single-row hits, but
+ * for a stitched chunked `detail="middle"` hit the top-level value is only the
+ * returned window while `expand.params` advertises the full parent body the
+ * recall was drawn from (see compact.ts buildStitched*). Using the parent size
+ * keeps "reading saved" honest — it's the haystack a recall searched, not the
+ * slice it happened to return.
+ *
+ * Returns `undefined` — not `0` — for non-retrieval tools and for response
+ * shapes that carry no per-hit size at all, so the caller can omit the field
+ * rather than log a fabricated zero (mirroring how legacy rows stay absent).
+ */
+export function extractSourceTokens(tool, mcpResult) {
+    if (!RETRIEVAL_TOOLS.has(tool))
+        return undefined;
+    const sc = mcpResult.structuredContent;
+    if (!sc)
+        return undefined;
+    let total = 0;
+    let found = false;
+    const hitSourceTokens = (hit) => {
+        const expand = hit["expand"];
+        const params = expand && typeof expand === "object"
+            ? expand["params"]
+            : undefined;
+        const fromExpand = params && typeof params === "object"
+            ? params["content_tokens_estimate"]
+            : undefined;
+        if (typeof fromExpand === "number")
+            return fromExpand;
+        const topLevel = hit["content_tokens_estimate"];
+        return typeof topLevel === "number" ? topLevel : undefined;
+    };
+    const addFrom = (arr) => {
+        if (!Array.isArray(arr))
+            return;
+        for (const item of arr) {
+            if (!item || typeof item !== "object")
+                continue;
+            const tokens = hitSourceTokens(item);
+            if (typeof tokens === "number") {
+                total += tokens;
+                found = true;
+            }
+        }
+    };
+    if (tool === "rift_context_pack") {
+        addFrom(sc["examples"]);
+        addFrom(sc["rules"]);
+    }
+    else if (tool === "rift_open_evidence") {
+        const result = sc["result"];
+        if (result && typeof result === "object") {
+            const tokens = hitSourceTokens(result);
+            if (typeof tokens === "number") {
+                total += tokens;
+                found = true;
+            }
+        }
+    }
+    else {
+        addFrom(sc["results"]);
+    }
+    return found ? total : undefined;
+}
 /**
  * Try to parse the typed error code (`id_not_found`, `ambiguous_id`, …)
  * out of a failure response's text channel. `formatError` formats typed
@@ -262,6 +344,10 @@ export class ToolUsageLogger {
                     }
                 }
                 entry.response_text_bytes = textBytes;
+                const sourceTokens = extractSourceTokens(tool, result);
+                if (sourceTokens !== undefined) {
+                    entry.source_tokens_estimate = sourceTokens;
+                }
             }
             if (tool === "rift_search") {
                 const meta = deriveSearchModeMeta(args);