@getrift/rift 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/src/retrieval/current-truth.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Current Truth Mode — intent-aware, trust-tiered evidence packaging for
+ * ContextPack. Layered: v0 = intent classifier + bucket partition; v1 =
+ * git-state discounting (untracked/deleted/newer-on-disk); v2 = trust
+ * tiers, claim-type labels, surfaced conflicts, tracker-only caveat, and
+ * staleness demotion.
+ *
+ * Pure, deterministic helpers that classify a query's evidence intent and
+ * partition already-retrieved hits into "current truth" / "past reasoning"
+ * / "older memory" / "discounted" buckets, plus a "recommended live files
+ * to check" hint when the top evidence is mostly old snapshots and the
+ * intent is current-truth.
+ *
+ * v2 load-bearing rule: a conversation can never be sole authority for
+ * current truth — recent conversations route to "Recent discussion", not
+ * `current_truth` — which closes the self-corroboration loop (Rift's own
+ * captured answer can't re-promote itself as current state).
+ *
+ * This module reads metadata that's already on hits (source_path,
+ * indexed_at, source) and a tracker's self-declared `Last touched:` date —
+ * it does NOT invent confidence, run any new retrieval, or change
+ * `rift_search` ranking. It only re-shapes the answer surface of
+ * `rift_context_pack`.
+ *
+ * See docs/evals/current-truth-mode-q1-q8.md (Q1–Q9) for the frozen
+ * regression set this module is targeting.
+ */
+import type { RankedResult } from "./reranker.js";
+import type { GitState } from "./git-state.js";
+export type { GitState } from "./git-state.js";
+export type EvidenceIntent = "current_truth" | "reasoning_archive" | "blended";
+/**
+ * Classify a query's evidence intent. Deterministic and transparent so
+ * v0 can be debugged by eye. Algorithm:
+ *
+ *   1. Lower-case the query.
+ *   2. Check phrase triggers (multi-word) for each intent.
+ *   3. Check single-word triggers (matched as whole words via word
+ *      boundaries — no partial matches like "currently" → "current").
+ *   4. If exactly one intent matches → that intent.
+ *   5. If both match → return `blended` (the asker is conflating
+ *      "what's my taste on the current X").
+ *   6. If neither matches → `blended`.
+ *
+ * Note on Q7 ("difference between second brain and Rift"): only
+ * `relationship between` is in the reasoning-archive trigger list, not
+ * `difference between`. Q7 fires no trigger and falls to `blended`,
+ * which is the deliberate v0 outcome — disambiguation questions surface
+ * both the current product framing and the historical context without
+ * forcing an order.
+ */
+export declare function classifyEvidenceIntent(query: string): EvidenceIntent;
+/**
+ * Coarse claim-type groups (Current Truth Mode v2). Distinct from
+ * {@link EvidenceIntent}: intent drives *section routing*, claim-type
+ * labels *what kind of assertion the asker is after* so the answer can
+ * say which facts are allowed to mean what.
+ *
+ *   - `current_state` — present-tense state. launch/status/version/
+ *     install/customer/current/now. Live state + trackers win; a doc's
+ *     self-declared authority does not.
+ *   - `framing` — how something is/was positioned. pricing/brand/
+ *     framing/history/positioning/narrative. Committed docs are good
+ *     here; a stale framing doc is weak-for-current-state but legitimate
+ *     for "what was the framing".
+ *   - `reasoning` — taste / rationale / relationships. why/decision/
+ *     taste/relationship/philosophy. Conversations are primary.
+ *
+ * Deliberately coarse and keyword-driven (the v2 "implementation
+ * restraint": no semantic claim matcher yet). Used to *label* a surfaced
+ * conflict ("competes for current state"), not to re-route sections —
+ * that stays {@link classifyEvidenceIntent}'s job.
+ */
+export type ClaimType = "current_state" | "framing" | "reasoning";
+/**
+ * Classify the claim-type of a query. Precedence: rationale phrases →
+ * strong reasoning words → ambiguous decision-without-current-qualifier →
+ * current_state → framing → default current_state. A "why did we decide X"
+ * question is reasoning even if it mentions a current-state noun; "latest
+ * decision about X" is a current-state question (P2 fix). An ambiguous
+ * query defaults to the strictest tier discipline (current_state) so we
+ * never under-apply the trust gating.
+ */
+export declare function classifyClaimType(query: string): ClaimType;
+/**
+ * Default freshness cutoff: a hit indexed within `RECENT_WINDOW_DAYS` of
+ * "now" counts as recent. 21 days is wide enough that a paused-but-
+ * active project's tracker still reads as current, and narrow enough
+ * that an April-26 LAUNCH.md (now ~3 weeks old by 2026-05-19) starts
+ * looking stale relative to a 2026-05-19 PROJECT_STATE.md edit.
+ */
+export declare const RECENT_WINDOW_DAYS = 21;
+export declare function isTrackerPath(p: unknown): boolean;
+export declare function isSnapshotPath(p: unknown): boolean;
+/**
+ * Trust tier of a single piece of evidence (Current Truth Mode v2).
+ * Ordered highest → lowest authority:
+ *
+ *   - `live_state`    — executable/observable truth: source code,
+ *                       install scripts, the package manifest, config.
+ *                       The closest retrieval analogue to `git status` /
+ *                       a running daemon's `/version`.
+ *   - `tracker`       — intentional state trackers: PROJECT_STATE.md,
+ *                       TODO.md, dated decision docs. Useful, not
+ *                       absolute — can be stale (see staleness demotion).
+ *   - `committed_doc` — durable committed framing: README, PRD, CLAUDE.md,
+ *                       AGENTS.md. Good for framing, lower for current state.
+ *   - `discussion`    — conversations / agent reasoning. Useful context,
+ *                       never sole authority for current state (hard rule 1).
+ *   - `discounted`    — untracked / deleted / snapshot / generated reports.
+ *                       Historical or provisional unless reaffirmed.
+ *
+ * The tier is a property of the *source*, computed structurally from
+ * kind + git-state + path. Which tier *leads the answer* depends on the
+ * claim — that routing stays with {@link partitionEvidence}. So the same
+ * card can be `committed_doc` and still be superseded by a `tracker` for
+ * a current-state claim: tier labels authority, intent decides order.
+ */
+export type TrustTier = "live_state" | "tracker" | "committed_doc" | "discussion" | "discounted";
+/**
+ * Assign a {@link TrustTier} to one evidence input. Pure, structural,
+ * claim-type-independent: git-state is the strongest signal (an untracked
+ * or deleted document is `discounted` no matter how it's named — the v1
+ * generalization of the LAUNCH.md hack), then snapshot paths, then the
+ * path-pattern ladder. Conversations are always `discussion`.
+ *
+ * Defaults to `committed_doc` for a tracked/unknown document that matches
+ * none of the specific ladders — it's a durable file we just can't place
+ * more precisely, which is a safer default than claiming it's live state.
+ */
+export declare function assignTrustTier(kind: "conversation" | "document", gitState: GitState | undefined, sourcePath: string | undefined): TrustTier;
+/**
+ * Parse a row's `indexed_at` and return whether it falls within the
+ * recency window. Robust to missing / unparseable timestamps — we'd
+ * rather call a row "unknown-age" (treated as not-recent) than blow up
+ * the answer packaging.
+ */
+export declare function isRecent(indexedAt: string | undefined, now?: Date, windowDays?: number): boolean;
+export interface EvidenceCard {
+    id: string;
+    title: string;
+    source: string;
+    snippet: string;
+    timestamp?: string;
+    source_path?: string;
+    /**
+     * v1 git-state classification of `source_path` at the time the pack
+     * was assembled. Surfaced on the card so downstream consumers can
+     * render a "(untracked)" / "(newer on disk)" hint next to the
+     * evidence without re-probing. Absent when no probe was run
+     * (conversation hit, missing source_path, no projectRoot).
+     */
+    git_state?: GitState;
+    /**
+     * v2 trust tier — the authority level of this source (see
+     * {@link TrustTier}). Always set. Lets the answer say which facts are
+     * allowed to mean what (`live_state` outranks `tracker` outranks
+     * `committed_doc` outranks `discussion`).
+     */
+    tier?: TrustTier;
+    /**
+     * v2 staleness anchor (P1 fix): a tracker's *self-declared* freshness,
+     * parsed from its content (`Last touched:` in PROJECT_STATE.md), as an
+     * ISO date. This is "when the tracker says it was last touched", which
+     * is the honest staleness signal — `timestamp` (indexed_at) only says
+     * "when Rift last reindexed the file", so a reindexed-but-stale tracker
+     * would otherwise look fresh and dodge {@link applyStalenessDemotion}.
+     * Absent when the content carries no parseable marker.
+     */
+    tracker_date?: string;
+}
+export interface DiscountedCard extends EvidenceCard {
+    reason: string;
+}
+export interface RecommendedLiveFile {
+    /** Display path — relative if we have it, absolute otherwise. */
+    path: string;
+    /** One-line "why" — e.g. "current project state". Short, no period. */
+    why: string;
+    /**
+     * v1 git-state of the recommended file, when known. Lets the asker
+     * see at a glance whether the suggested live file is itself
+     * canonical (`tracked`) or in an evolving state (`modified` /
+     * `newer_on_disk`). Untracked / deleted paths are never recommended.
+     */
+    git_state?: GitState;
+}
+/**
+ * A surfaced disagreement between sources for the same claim (hard rule
+ * 4: surface conflicts, don't pretend to resolve them). The canonical
+ * case is a high-ranking discounted document (e.g. an untracked
+ * `LAUNCH.md` that self-declares authority) competing with higher-tier
+ * tracker / live-state / live-file evidence for a current-state claim.
+ * We name the tension and attach the tiers; we do not adjudicate the
+ * underlying facts.
+ */
+export interface ConflictCard {
+    /** Coarse claim-type the conflict is about (e.g. `current_state`). */
+    claim: ClaimType;
+    /** The lower-trust source competing to be the answer. */
+    discounted: {
+        title: string;
+        reason: string;
+        source_path?: string;
+    };
+    /** The higher-trust evidence that supersedes it. */
+    superseded_by: {
+        title: string;
+        tier: TrustTier;
+        source_path?: string;
+    };
+}
+export interface EvidencePartition {
+    current_truth: EvidenceCard[];
+    past_reasoning: EvidenceCard[];
+    older_memory: EvidenceCard[];
+    discounted: DiscountedCard[];
+    recommended_live_files: RecommendedLiveFile[];
+    /**
+     * v2 conflicts (hard rule 4). Empty unless a discounted current-state
+     * source is competing with higher-tier evidence.
+     */
+    conflicts: ConflictCard[];
+    /**
+     * v2 caveat (hard rule 3). Set to "tracker-backed, not live-verified"
+     * when `current_truth` is populated but contains no `live_state`-tier
+     * evidence — i.e. the best we have is an intentional tracker, not
+     * executable/observable state. Absent otherwise.
+     */
+    current_truth_caveat?: string;
+}
+/** Hard rule 3 caveat string — single source so renderer + DTO agree. */
+export declare const TRACKER_ONLY_CAVEAT = "tracker-backed, not live-verified";
+/**
+ * Input to {@link partitionEvidence}. Lets the partitioner consume both
+ * conversation hits and document hits in a uniform shape without
+ * re-implementing row lookup — the caller already has rows in hand from
+ * `fetchRowsById`.
+ */
+export interface EvidenceInput {
+    ranked: RankedResult;
+    row: Record<string, unknown> | undefined;
+    kind: "conversation" | "document";
+    /**
+     * v1: pre-probed git state for `row.source_path`. Optional — when
+     * absent, the partitioner falls back to v0 path-pattern heuristics.
+     * Populated by the caller (typically buildContextPack) via
+     * {@link import("./git-state.js").probeGitStates}.
+     */
+    gitState?: GitState;
+}
+/**
+ * Partition retrieved hits according to the resolved evidence intent.
+ *
+ * Rules (v2, transparent and deterministic):
+ *
+ *   - `current_truth` mode:
+ *     - Conversations → `past_reasoning` (recent) / `older_memory` (old),
+ *       NEVER `current_truth` (v2 hard rule 1: no conversation is sole
+ *       authority for current state; closes self-corroboration).
+ *     - Documents with `gitState === "untracked"` → `discounted`
+ *       ("untracked in git"). Catches files like a project-local
+ *       `LAUNCH.md` that exists on disk but hasn't been committed —
+ *       not canonical state.
+ *     - Documents with `gitState === "deleted"` → `discounted`
+ *       ("deleted from disk"). The asker can't open it to verify.
+ *     - Tracker-path docs and recent (<{@link RECENT_WINDOW_DAYS}d) docs
+ *       → `current_truth`.
+ *     - Snapshot/report-style docs and older docs → `discounted`
+ *       (with reason).
+ *     - Post-passes: stale trackers (older than fresher live-state by the
+ *       recency window) demoted to `older_memory`; `tracker-backed, not
+ *       live-verified` caveat set when `current_truth` has no live-state
+ *       card; at most one `## Conflicts` entry pairing the top discounted
+ *       doc against the top higher-tier card.
+ *     - If `current_truth` is empty or dominated by snapshot/older
+ *       evidence → populate `recommended_live_files` with tracker paths
+ *       we already saw in hits (filtered to live git states), or
+ *       canonical defaults.
+ *
+ *   - `reasoning_archive` mode:
+ *     - Conversations (regardless of age) → `past_reasoning` (lead).
+ *     - Tracker-path docs → `current_truth` (background, kept short).
+ *     - Snapshot docs → `older_memory`.
+ *     - No demotion-by-age for conversations. No `discounted`.
+ *     - No `recommended_live_files` — the asker doesn't want trackers.
+ *     - Git-state rules do NOT apply here: the asker is after framing,
+ *       not canonicalness.
+ *
+ *   - `blended` mode:
+ *     - Same git-state discount rules as `current_truth` for documents.
+ *     - Tracker-path docs and recent hits → `current_truth`.
+ *     - Conversations (regardless of age) → `past_reasoning`.
+ *     - Snapshot docs that are clearly stale relative to a tracker →
+ *       `discounted`. Other older docs → `older_memory`.
+ *     - `recommended_live_files` only if `current_truth` is empty.
+ *
+ * Caps per section are derived from {@link maxPerSection} so the caller
+ * controls the overall budget.
+ */
+export interface PartitionOptions {
+    intent: EvidenceIntent;
+    /** Per-section cap (parallels existing maxPerBucket). */
+    maxPerSection: number;
+    /** Injectable for tests. Defaults to `new Date()`. */
+    now?: Date;
+    /** Project-root absolute path used to display paths relatively when possible. */
+    projectRoot?: string;
+    /**
+     * v2 claim-type (see {@link classifyClaimType}). Used to label surfaced
+     * conflicts. Defaults to `current_state` when omitted — the strictest
+     * gating, so callers that forget it never under-apply trust discipline.
+     */
+    claimType?: ClaimType;
+}
+export declare function partitionEvidence(inputs: readonly EvidenceInput[], opts: PartitionOptions): EvidencePartition;
+/**
+ * Best-effort parse of a tracker's self-declared freshness from its
+ * content. Currently the `Last touched: YYYY-MM-DD` line that
+ * PROJECT_STATE.md carries near the top. Returns the matched ISO date
+ * string, or undefined when the chunk doesn't contain the marker (the
+ * caller falls back to `indexed_at`). Tolerates optional markdown
+ * bold/list decoration around the label.
+ */
+export declare function parseTrackerDate(content: string | undefined): string | undefined;
+//# sourceMappingURL=current-truth.d.ts.map

package/dist/src/retrieval/current-truth.d.ts.map

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