@gmickel/gno 0.16.0 → 0.18.0

package/src/pipeline/temporal.ts

@@ -0,0 +1,257 @@
+/**
+ * Temporal range parsing helpers for retrieval filters.
+ *
+ * @module src/pipeline/temporal
+ */
+
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+const RECENCY_SORT_RE =
+  /\b(latest|newest|most recent|recent|today|yesterday|this week|last week|this month|last month)\b/;
+
+export interface TemporalRange {
+  since?: string;
+  until?: string;
+}
+
+type BoundKind = "since" | "until";
+
+function startOfDay(d: Date): Date {
+  const out = new Date(d);
+  out.setUTCHours(0, 0, 0, 0);
+  return out;
+}
+
+function endOfDay(d: Date): Date {
+  const out = new Date(d);
+  out.setUTCHours(23, 59, 59, 999);
+  return out;
+}
+
+function startOfWeekUtc(d: Date): Date {
+  const out = startOfDay(d);
+  const day = out.getUTCDay(); // 0 = Sunday
+  const mondayOffset = day === 0 ? -6 : 1 - day;
+  out.setUTCDate(out.getUTCDate() + mondayOffset);
+  return out;
+}
+
+function endOfWeekUtc(d: Date): Date {
+  const start = startOfWeekUtc(d);
+  const out = new Date(start);
+  out.setUTCDate(out.getUTCDate() + 6);
+  return endOfDay(out);
+}
+
+function startOfMonthUtc(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1, 0, 0, 0, 0));
+}
+
+function endOfMonthUtc(d: Date): Date {
+  return new Date(
+    Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0, 23, 59, 59, 999)
+  );
+}
+
+function normalizeParsedDate(value: string, kind: BoundKind): string | null {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return null;
+  }
+
+  if (DATE_ONLY_RE.test(value)) {
+    return (
+      kind === "since" ? startOfDay(parsed) : endOfDay(parsed)
+    ).toISOString();
+  }
+
+  return parsed.toISOString();
+}
+
+function parseRelative(
+  value: string,
+  kind: BoundKind,
+  now: Date
+): string | null {
+  const v = value.trim().toLowerCase();
+
+  if (v === "today") {
+    return (kind === "since" ? startOfDay(now) : endOfDay(now)).toISOString();
+  }
+  if (v === "yesterday") {
+    const d = new Date(now);
+    d.setUTCDate(d.getUTCDate() - 1);
+    return (kind === "since" ? startOfDay(d) : endOfDay(d)).toISOString();
+  }
+  if (v === "this week") {
+    return (kind === "since" ? startOfWeekUtc(now) : now).toISOString();
+  }
+  if (v === "last week") {
+    const d = new Date(now);
+    d.setUTCDate(d.getUTCDate() - 7);
+    return (
+      kind === "since" ? startOfWeekUtc(d) : endOfWeekUtc(d)
+    ).toISOString();
+  }
+  if (v === "this month") {
+    return (kind === "since" ? startOfMonthUtc(now) : now).toISOString();
+  }
+  if (v === "last month") {
+    const d = new Date(now);
+    d.setUTCMonth(d.getUTCMonth() - 1);
+    return (
+      kind === "since" ? startOfMonthUtc(d) : endOfMonthUtc(d)
+    ).toISOString();
+  }
+  if (v === "recent") {
+    if (kind === "until") {
+      return now.toISOString();
+    }
+    const d = new Date(now);
+    d.setUTCDate(d.getUTCDate() - 30);
+    return d.toISOString();
+  }
+
+  return null;
+}
+
+function parseBound(
+  input: string | undefined,
+  kind: BoundKind,
+  now: Date
+): string | undefined {
+  if (!input) {
+    return undefined;
+  }
+  const relative = parseRelative(input, kind, now);
+  if (relative) {
+    return relative;
+  }
+  return normalizeParsedDate(input, kind) ?? undefined;
+}
+
+function inferFromQuery(query: string, now: Date): TemporalRange {
+  const q = query.toLowerCase();
+
+  if (/\btoday\b/.test(q)) {
+    return {
+      since: parseRelative("today", "since", now) ?? undefined,
+      until: parseRelative("today", "until", now) ?? undefined,
+    };
+  }
+  if (/\byesterday\b/.test(q)) {
+    return {
+      since: parseRelative("yesterday", "since", now) ?? undefined,
+      until: parseRelative("yesterday", "until", now) ?? undefined,
+    };
+  }
+  if (/\bthis week\b/.test(q)) {
+    return {
+      since: parseRelative("this week", "since", now) ?? undefined,
+      until: parseRelative("this week", "until", now) ?? undefined,
+    };
+  }
+  if (/\blast week\b/.test(q)) {
+    return {
+      since: parseRelative("last week", "since", now) ?? undefined,
+      until: parseRelative("last week", "until", now) ?? undefined,
+    };
+  }
+  if (/\bthis month\b/.test(q)) {
+    return {
+      since: parseRelative("this month", "since", now) ?? undefined,
+      until: parseRelative("this month", "until", now) ?? undefined,
+    };
+  }
+  if (/\blast month\b/.test(q)) {
+    return {
+      since: parseRelative("last month", "since", now) ?? undefined,
+      until: parseRelative("last month", "until", now) ?? undefined,
+    };
+  }
+  if (/\brecent\b/.test(q)) {
+    return {
+      since: parseRelative("recent", "since", now) ?? undefined,
+      until: parseRelative("recent", "until", now) ?? undefined,
+    };
+  }
+
+  return {};
+}
+
+/**
+ * Resolve temporal bounds from explicit flags or query text.
+ */
+export function resolveTemporalRange(
+  query: string,
+  sinceInput?: string,
+  untilInput?: string,
+  now = new Date()
+): TemporalRange {
+  const since = parseBound(sinceInput, "since", now);
+  const until = parseBound(untilInput, "until", now);
+
+  if (since || until) {
+    return { since, until };
+  }
+
+  return inferFromQuery(query, now);
+}
+
+/**
+ * Return true when timestamp falls inside optional range.
+ */
+export function isWithinTemporalRange(
+  timestamp: string | undefined,
+  range: TemporalRange
+): boolean {
+  if (!timestamp) {
+    return true;
+  }
+  const t = new Date(timestamp).getTime();
+  if (Number.isNaN(t)) {
+    return true;
+  }
+  if (range.since) {
+    const since = new Date(range.since).getTime();
+    if (!Number.isNaN(since) && t < since) {
+      return false;
+    }
+  }
+  if (range.until) {
+    const until = new Date(range.until).getTime();
+    if (!Number.isNaN(until) && t > until) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Return true when query intent implies newest-first ordering.
+ */
+export function shouldSortByRecency(query: string): boolean {
+  return RECENCY_SORT_RE.test(query.toLowerCase());
+}
+
+/**
+ * Prefer canonical doc date; fallback to source modified time.
+ * Returns 0 when neither value is valid.
+ */
+export function resolveRecencyTimestamp(
+  docDate?: string | null,
+  sourceModifiedAt?: string | null
+): number {
+  if (docDate) {
+    const parsed = new Date(docDate).getTime();
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+  if (sourceModifiedAt) {
+    const parsed = new Date(sourceModifiedAt).getTime();
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+  return 0;
+}

package/src/pipeline/types.ts

@@ -18,6 +18,7 @@ export interface SearchResultSource {
   mime: string;
   ext: string;
   modifiedAt?: string;
+  documentDate?: string;
   sizeBytes?: number;
   sourceHash?: string;
 }
@@ -61,10 +62,23 @@ export interface SearchMeta {
   reranked?: boolean;
   vectorsUsed?: boolean;
   totalResults: number;
+  intent?: string;
   collection?: string;
   lang?: string;
   /** Detected/overridden query language for prompt selection (typically BCP-47; may be user-provided via --lang) */
   queryLanguage?: string;
+  /** Summary of structured query modes applied (if provided) */
+  queryModes?: QueryModeSummary;
+  /** Temporal filter lower bound (ISO 8601) */
+  since?: string;
+  /** Temporal filter upper bound (ISO 8601) */
+  until?: string;
+  /** Category filters applied */
+  categories?: string[];
+  /** Author filter applied */
+  author?: string;
+  /** Rerank candidate limit used */
+  candidateLimit?: number;
   /** Explain data (when --explain is used) */
   explain?: {
     lines: ExplainLine[];
@@ -100,6 +114,32 @@ export interface SearchOptions {
   tagsAll?: string[];
   /** Filter to docs with ANY of these tags (OR) */
   tagsAny?: string[];
+  /** Filter by modified time lower bound (ISO 8601 or relative token) */
+  since?: string;
+  /** Filter by modified time upper bound (ISO 8601 or relative token) */
+  until?: string;
+  /** Filter to docs matching ANY category */
+  categories?: string[];
+  /** Filter by author value */
+  author?: string;
+  /** Optional disambiguating context that steers scoring/snippets, but is not searched directly */
+  intent?: string;
+}
+
+/** Structured query mode identifier */
+export type QueryMode = "term" | "intent" | "hyde";
+
+/** Structured query mode entry */
+export interface QueryModeInput {
+  mode: QueryMode;
+  text: string;
+}
+
+/** Structured query mode summary for metadata/explain */
+export interface QueryModeSummary {
+  term: number;
+  intent: number;
+  hyde: boolean;
 }
 
 /** Options for hybrid search (gno query) */
@@ -108,6 +148,10 @@ export type HybridSearchOptions = SearchOptions & {
   noExpand?: boolean;
   /** Disable reranking */
   noRerank?: boolean;
+  /** Optional structured mode entries; when set, used as expansion inputs */
+  queryModes?: QueryModeInput[];
+  /** Max candidates passed to reranking */
+  candidateLimit?: number;
   /** Enable explain output */
   explain?: boolean;
   /** Language hint for prompt selection (does NOT filter retrieval, only affects expansion prompts) */
@@ -247,13 +291,35 @@ export interface Citation {
   endLine?: number;
 }
 
+/** Source selection entry for answer-generation explain */
+export interface AnswerContextEntry {
+  docid: string;
+  uri: string;
+  score: number;
+  queryTokenHits: number;
+  facetHits: number;
+  reason: string;
+}
+
+/** Answer-generation context selection explain payload */
+export interface AnswerContextExplain {
+  strategy: "adaptive_coverage_v1";
+  targetSources: number;
+  facets: string[];
+  selected: AnswerContextEntry[];
+  dropped: AnswerContextEntry[];
+}
+
 /** Ask result metadata */
 export interface AskMeta {
   expanded: boolean;
   reranked: boolean;
   vectorsUsed: boolean;
+  intent?: string;
+  candidateLimit?: number;
   answerGenerated?: boolean;
   totalResults?: number;
+  answerContext?: AnswerContextExplain;
 }
 
 /** Ask command result */
@@ -323,6 +389,7 @@ export interface ExplainResult {
   rank: number;
   docid: string;
   score: number;
+  fusionScore?: number;
   bm25Score?: number;
   vecScore?: number;
   rerankScore?: number;

package/src/pipeline/vsearch.ts

@@ -14,7 +14,15 @@ import type { SearchOptions, SearchResult, SearchResults } from "./types";
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
 import { formatQueryForEmbedding } from "./contextual";
+import { selectBestChunkForSteering } from "./intent";
 import { detectQueryLanguage } from "./query-language";
+import {
+  resolveRecencyTimestamp,
+  isWithinTemporalRange,
+  resolveTemporalRange,
+  shouldSortByRecency,
+  type TemporalRange,
+} from "./temporal";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Score Normalization
@@ -58,6 +66,13 @@ export async function searchVectorWithEmbedding(
   const { store, vectorIndex } = deps;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
+  const recencySort = shouldSortByRecency(query);
+  const retrievalLimit = recencySort ? limit * 3 : limit;
+  const temporalRange = resolveTemporalRange(
+    query,
+    options.since,
+    options.until
+  );
 
   // Detect query language for metadata (DOES NOT affect retrieval filtering)
   const detection = detectQueryLanguage(query);
@@ -72,15 +87,20 @@ export async function searchVectorWithEmbedding(
   }
 
   // Search nearest neighbors
-  const searchResult = await vectorIndex.searchNearest(queryEmbedding, limit, {
-    minScore,
-  });
+  const searchResult = await vectorIndex.searchNearest(
+    queryEmbedding,
+    retrievalLimit,
+    {
+      minScore,
+    }
+  );
 
   if (!searchResult.ok) {
     return err("QUERY_FAILED", searchResult.error.message);
   }
 
   const vecResults = searchResult.value;
+  const uniqueHashes = [...new Set(vecResults.map((v) => v.mirrorHash))];
 
   // Get collection paths for absPath resolution
   const collectionsResult = await store.getCollections();
@@ -96,10 +116,14 @@ export async function searchVectorWithEmbedding(
     collection: options.collection,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
+    since: temporalRange.since,
+    until: temporalRange.until,
+    categories: options.categories,
+    author: options.author,
+    mirrorHashes: uniqueHashes,
   });
 
   // Pre-fetch all chunks in one batch query (eliminates N+1)
-  const uniqueHashes = [...new Set(vecResults.map((v) => v.mirrorHash))];
   const chunksMapResult = await store.getChunksBatch(uniqueHashes);
   if (!chunksMapResult.ok) {
     return err("QUERY_FAILED", chunksMapResult.error.message);
@@ -123,7 +147,18 @@ export async function searchVectorWithEmbedding(
     }
 
     // Get chunk via O(1) lookup
-    const chunk = getChunk(vec.mirrorHash, vec.seq);
+    const rawChunk = getChunk(vec.mirrorHash, vec.seq);
+    const chunk = options.intent
+      ? (selectBestChunkForSteering(
+          chunksMap.get(vec.mirrorHash) ?? [],
+          query,
+          options.intent,
+          {
+            preferredSeq: rawChunk?.seq ?? vec.seq,
+            intentWeight: 0.3,
+          }
+        ) ?? rawChunk)
+      : rawChunk;
     if (!chunk) {
       continue;
     }
@@ -178,6 +213,7 @@ export async function searchVectorWithEmbedding(
         mime: doc.sourceMime,
         ext: doc.sourceExt,
         modifiedAt: doc.sourceMtime,
+        documentDate: doc.frontmatterDate ?? undefined,
         sizeBytes: doc.sourceSize,
         sourceHash: doc.sourceHash,
       },
@@ -223,6 +259,7 @@ export async function searchVectorWithEmbedding(
           mime: doc.sourceMime,
           ext: doc.sourceExt,
           modifiedAt: doc.sourceMtime,
+          documentDate: doc.frontmatterDate ?? undefined,
           sizeBytes: doc.sourceSize,
           sourceHash: doc.sourceHash,
         },
@@ -237,15 +274,39 @@ export async function searchVectorWithEmbedding(
     }
   }
 
+  if (recencySort) {
+    results.sort((a, b) => {
+      const aTs = resolveRecencyTimestamp(
+        a.source.documentDate,
+        a.source.modifiedAt
+      );
+      const bTs = resolveRecencyTimestamp(
+        b.source.documentDate,
+        b.source.modifiedAt
+      );
+      if (aTs !== bTs) {
+        return bTs - aTs;
+      }
+      return b.score - a.score;
+    });
+  }
+
+  const finalResults = results.slice(0, limit);
+
   return ok({
-    results,
+    results: finalResults,
     meta: {
       query,
       mode: "vector",
       vectorsUsed: true,
-      totalResults: results.length,
+      totalResults: finalResults.length,
+      intent: options.intent,
       collection: options.collection,
       lang: options.lang,
+      since: temporalRange.since,
+      until: temporalRange.until,
+      categories: options.categories,
+      author: options.author,
       queryLanguage,
     },
   });
@@ -305,6 +366,7 @@ interface DocumentInfo {
   sourceMime: string;
   sourceExt: string;
   sourceMtime: string;
+  frontmatterDate?: string | null;
   sourceSize: number;
   mirrorHash: string | null;
   converterId: string | null;
@@ -319,6 +381,25 @@ interface DocumentMapOptions {
   collection?: string;
   tagsAll?: string[];
   tagsAny?: string[];
+  since?: string;
+  until?: string;
+  categories?: string[];
+  author?: string;
+  mirrorHashes?: string[];
+}
+
+function matchesCategoryFilter(
+  doc: { contentType?: string | null; categories?: string[] | null },
+  categories?: string[]
+): boolean {
+  if (!categories || categories.length === 0) {
+    return true;
+  }
+  const allowed = new Set(categories.map((c) => c.toLowerCase()));
+  if (doc.contentType && allowed.has(doc.contentType.toLowerCase())) {
+    return true;
+  }
+  return (doc.categories ?? []).some((c) => allowed.has(c.toLowerCase()));
 }
 
 async function buildDocumentMap(
@@ -327,13 +408,29 @@ async function buildDocumentMap(
 ): Promise<Map<string, DocumentInfo>> {
   const result = new Map<string, DocumentInfo>();
 
-  const docs = await store.listDocuments(options.collection);
+  if (options.mirrorHashes && options.mirrorHashes.length === 0) {
+    return result;
+  }
+
+  const docs = options.mirrorHashes
+    ? await store.getDocumentsByMirrorHashes(options.mirrorHashes, {
+        collection: options.collection,
+        activeOnly: true,
+      })
+    : await store.listDocuments(options.collection);
   if (!docs.ok) {
     return result;
   }
 
-  // Filter active docs with mirrorHash
-  const activeDocs = docs.value.filter((d) => d.mirrorHash && d.active);
+  // Filter docs with mirrorHash.
+  // listDocuments path still needs explicit active filter.
+  const activeDocs = options.mirrorHashes
+    ? docs.value.filter((d) => d.mirrorHash)
+    : docs.value.filter((d) => d.mirrorHash && d.active);
+  const temporalRange: TemporalRange = {
+    since: options.since,
+    until: options.until,
+  };
 
   // Apply tag filters if specified (batch fetch to avoid N+1)
   const needsTagFilter = options.tagsAll?.length || options.tagsAny?.length;
@@ -370,6 +467,19 @@ async function buildDocumentMap(
   }
 
   for (const doc of activeDocs) {
+    if (!isWithinTemporalRange(doc.sourceMtime, temporalRange)) {
+      continue;
+    }
+    if (!matchesCategoryFilter(doc, options.categories)) {
+      continue;
+    }
+    if (
+      options.author &&
+      !doc.author?.toLowerCase().includes(options.author.toLowerCase())
+    ) {
+      continue;
+    }
+
     // Skip if tag filter excluded this doc
     if (allowedDocIds !== null && !allowedDocIds.has(doc.id)) {
       continue;
@@ -385,6 +495,7 @@ async function buildDocumentMap(
       sourceMime: doc.sourceMime,
       sourceExt: doc.sourceExt,
       sourceMtime: doc.sourceMtime,
+      frontmatterDate: doc.frontmatterDate,
       sourceSize: doc.sourceSize,
       mirrorHash: doc.mirrorHash,
       converterId: doc.converterId,

package/src/serve/public/app.tsx

@@ -58,8 +58,6 @@ function App() {
     }
     window.history.pushState({}, "", to);
     setLocation(to);
-    // Dispatch event for components that need to react to URL changes
-    window.dispatchEvent(new CustomEvent("locationchange", { detail: to }));
   }, []);
 
   // Global keyboard shortcuts (single-key, GitHub/Gmail pattern)
@@ -98,7 +96,7 @@ function App() {
     <CaptureModalProvider>
       <div className="flex min-h-screen flex-col">
         <div className="flex-1">
-          <Page navigate={navigate} />
+          <Page key={location} navigate={navigate} />
         </div>
         <footer className="border-t border-border/50 bg-background/80 py-4 text-center text-muted-foreground text-sm">
           <div className="flex items-center justify-center gap-4">