@gmickel/gno 1.46.0 → 2.1.0

package/src/mcp/tools/index.ts

@@ -1,11 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/server";
 /**
  * MCP tool registration and shared utilities.
  *
  * @module src/mcp/tools
  */
 
-import type { McpServer } from "@modelcontextprotocol/server";
-
 import { z } from "zod";
 
 import type { ToolContext } from "../server";
@@ -18,6 +17,10 @@ import { CAPTURE_MAX_TEXT_BYTES } from "../../core/capture";
 import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
 import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
+import {
+  assertInferenceActive,
+  acquireInferencePermit,
+} from "../../llm/inference-scope";
 import { profileToolDescription } from "../tool-descriptions-core";
 import {
   createProfileToolRegistrar,
@@ -940,10 +943,11 @@ export async function runTool<T>(
   }
 
   // Sequential execution via mutex
-  const release = await ctx.toolMutex.acquire();
-  const modelLease = ctx.acquireModelLease?.();
+  const release = await acquireInferencePermit(() => ctx.toolMutex.acquire());
   try {
+    assertInferenceActive();
     const data = await (ctx.runWithSnapshot?.(fn) ?? fn());
+    assertInferenceActive();
     const traceMetadata =
       data !== null && typeof data === "object"
         ? (data as Record<PropertyKey, unknown>)[RETRIEVAL_TRACE_METADATA]
@@ -966,7 +970,6 @@ export async function runTool<T>(
       structuredContent: parsedError,
     };
   } finally {
-    modelLease?.release();
     release();
   }
 }
@@ -990,9 +993,10 @@ export async function runToolNoMutex<T>(
     };
   }
 
-  const modelLease = ctx.acquireModelLease?.();
   try {
+    assertInferenceActive();
     const data = await (ctx.runWithSnapshot?.(fn) ?? fn());
+    assertInferenceActive();
     return {
       content: [{ type: "text", text: formatText(data) }],
       structuredContent: data as { [x: string]: unknown },
@@ -1007,8 +1011,6 @@ export async function runToolNoMutex<T>(
       content: [{ type: "text", text: `Error: ${message}` }],
       structuredContent: parsedError,
     };
-  } finally {
-    modelLease?.release();
   }
 }
 

package/src/mcp/tools/query.ts

@@ -17,6 +17,7 @@ import type {
   SearchResult,
   SearchResults,
 } from "../../pipeline/types";
+import type { VectorIndexPort } from "../../store/vector";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
@@ -42,10 +43,7 @@ import { resolveDownloadPolicy } from "../../llm/policy";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
 import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
-import {
-  createVectorIndexPort,
-  type VectorIndexPort,
-} from "../../store/vector";
+import { createLazyVectorIndex } from "../../store/vector/lazy";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface QueryInput {
@@ -278,7 +276,7 @@ export function handleQuery(
         });
         if (!traceStart.ok) throw new Error(traceStart.error.message);
         traceSession = traceStart.value ?? undefined;
-        const llm = new LlmAdapter(ctx.config);
+        const llm = ctx.getModelAdapter?.() ?? new LlmAdapter(ctx.config);
         const egressCollections = args.collection
           ? [args.collection]
           : ("all" as const);
@@ -325,18 +323,11 @@ export function handleQuery(
 
         // Create vector index (optional)
         if (embedPort) {
-          const embedInitResult = await embedPort.init();
-          if (embedInitResult.ok) {
-            const dimensions = embedPort.dimensions();
-            const db = ctx.store.getRawDb();
-            const vectorResult = await createVectorIndexPort(db, {
-              model: embedUri,
-              dimensions,
-            });
-            if (vectorResult.ok) {
-              vectorIndex = vectorResult.value;
-            }
-          }
+          vectorIndex = await createLazyVectorIndex(
+            ctx.store.getRawDb(),
+            embedUri,
+            embedPort
+          );
         }
 
         const deps: HybridSearchDeps = {
@@ -428,7 +419,7 @@ export function handleQueryDiagnose(
           : undefined;
 
       const preset = getActivePreset(ctx.config);
-      const llm = new LlmAdapter(ctx.config);
+      const llm = ctx.getModelAdapter?.() ?? new LlmAdapter(ctx.config);
       const policy = resolveDownloadPolicy(process.env, {});
       const downloadProgress = createNonTtyProgressRenderer();
       const egressCollections = collection ? [collection] : ("all" as const);
@@ -501,18 +492,11 @@ export function handleQueryDiagnose(
         }
 
         if (embedPort) {
-          const embedInitResult = await embedPort.init();
-          if (embedInitResult.ok) {
-            const dimensions = embedPort.dimensions();
-            const db = ctx.store.getRawDb();
-            const vectorResult = await createVectorIndexPort(db, {
-              model: embedUri,
-              dimensions,
-            });
-            if (vectorResult.ok) {
-              vectorIndex = vectorResult.value;
-            }
-          }
+          vectorIndex = await createLazyVectorIndex(
+            ctx.store.getRawDb(),
+            embedUri,
+            embedPort
+          );
         }
 
         const deps: HybridSearchDeps = {

package/src/mcp/tools/vsearch.ts

@@ -178,7 +178,7 @@ export function handleVsearch(
         const downloadProgress = createNonTtyProgressRenderer();
 
         // Create LLM adapter for embeddings
-        const llm = new LlmAdapter(ctx.config);
+        const llm = ctx.getModelAdapter?.() ?? new LlmAdapter(ctx.config);
         const embedResult = await llm.createEmbeddingPort(modelUri, {
           egressCollections: args.collection ? [args.collection] : "all",
           policy,

package/src/pipeline/answer.ts

@@ -1,13 +1,13 @@
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 /**
  * Grounded answer generation.
  * Shared between CLI ask command and web API.
  *
  * @module src/pipeline/answer
  */
-
-import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { GenerationPort } from "../llm/types";
 import type { StorePort } from "../store/types";
+import type { RequestHydration } from "./hydration";
 import type {
   AnswerContextEntry,
   AnswerContextExplain,
@@ -15,6 +15,10 @@ import type {
   SearchResult,
 } from "./types";
 
+import {
+  assertInferenceActive,
+  assertInferenceResult,
+} from "../llm/inference-scope";
 import { buildAnswerPrompt, type AnswerPromptSource } from "./answer-prompt";
 import { attachCitationTraceMetadata } from "./trace-metadata";
 import {
@@ -117,6 +121,7 @@ const completeLinePrefix = (
   const selected: string[] = [];
   let characters = 0;
   for (const line of lines) {
+    assertInferenceActive();
     const addition = selected.length === 0 ? line.length : line.length + 1;
     if (characters + addition > maxChars) break;
     selected.push(line);
@@ -172,6 +177,7 @@ export function extractValidCitationNumbers(
   const re = /\[(\d+)\]/g;
   const matches = answer.matchAll(re);
   for (const match of matches) {
+    assertInferenceActive();
     const n = Number(match[1]);
     if (Number.isInteger(n) && n >= 1 && n <= maxCitation) {
       nums.add(n);
@@ -231,6 +237,8 @@ export interface AnswerGenerationResult {
 export interface AnswerGenerationDeps {
   genPort: GenerationPort;
   store: StorePort | null;
+  /** Raw request-owned content only; passage/hash validation still runs. */
+  hydration?: Pick<RequestHydration, "getContent">;
 }
 
 function normalizeScore(score: number): number {
@@ -273,6 +281,7 @@ function buildCandidates(
 
     const matchedQueryTokens = new Set<string>();
     for (const token of queryTokenSet) {
+      assertInferenceActive();
       if (signalTokenSet.has(token)) {
         matchedQueryTokens.add(token);
       }
@@ -280,7 +289,9 @@ function buildCandidates(
 
     const matchedFacetIndexes = new Set<number>();
     for (const [index, facetTokenSet] of facetTokenSets.entries()) {
+      assertInferenceActive();
       for (const token of facetTokenSet) {
+        assertInferenceActive();
         if (signalTokenSet.has(token)) {
           matchedFacetIndexes.add(index);
           break;
@@ -301,6 +312,7 @@ function dedupeByDocidBestScore(results: SearchResult[]): SearchResult[] {
   const bestByDocid = new Map<string, SearchResult>();
 
   for (const result of results) {
+    assertInferenceActive();
     const existing = bestByDocid.get(result.docid);
     if (!existing || result.score > existing.score) {
       bestByDocid.set(result.docid, result);
@@ -358,6 +370,7 @@ function selectAdaptiveSources(
     let bestReason = "relevance";
 
     for (const candidate of candidates) {
+      assertInferenceActive();
       const docid = candidate.result.docid;
       if (selectedDocids.has(docid)) {
         continue;
@@ -418,15 +431,18 @@ function selectAdaptiveSources(
     selected.push({ candidate: bestCandidate, reason: bestReason });
     selectedDocids.add(bestCandidate.result.docid);
     for (const token of bestCandidate.matchedQueryTokens) {
+      assertInferenceActive();
       coveredTokens.add(token);
     }
     for (const index of bestCandidate.matchedFacetIndexes) {
+      assertInferenceActive();
       coveredFacets.add(index);
     }
   }
 
   if (comparisonIntent && selected.length < 2) {
     for (const candidate of candidates) {
+      assertInferenceActive();
       if (selectedDocids.has(candidate.result.docid)) {
         continue;
       }
@@ -501,6 +517,7 @@ export async function generateGroundedAnswer(
   let citationIndex = 0;
 
   for (const r of sourceSelection.selected) {
+    assertInferenceActive();
     let passage: ExactAnswerPassage | null = null;
     const plannerMetadata = r[SEARCH_RESULT_PLANNER_METADATA];
     const sourceHash = r.source.sourceHash;
@@ -508,7 +525,9 @@ export async function generateGroundedAnswer(
 
     // Try to fetch full document content if store available
     if (store && mirrorHash) {
-      const contentResult = await store.getContent(mirrorHash);
+      const contentResult = await (deps.hydration ?? store).getContent(
+        mirrorHash
+      );
       if (contentResult.ok && contentResult.value) {
         if (sha256(contentResult.value) === mirrorHash) {
           passage =
@@ -578,6 +597,7 @@ export async function generateGroundedAnswer(
     maxTokens,
   });
 
+  assertInferenceResult(result);
   if (!result.ok) {
     return null;
   }

package/src/pipeline/claim-verifier.ts

@@ -8,6 +8,10 @@ import type {
 } from "./claim-verification";
 
 import { sha256Text } from "../core/context-capsule-validation";
+import {
+  assertInferenceActive,
+  assertInferenceResult,
+} from "../llm/inference-scope";
 import {
   semanticClaimJudgmentSchema,
   verifyClaimsDeterministically,
@@ -251,6 +255,7 @@ const parseEnvelope = (
   }
   const judgments: SemanticClaimJudgment[] = [];
   for (const rawJudgment of parsed.data.judgments) {
+    assertInferenceActive();
     const candidate = candidatesById.get(rawJudgment.claimId);
     const allowed = new Set(
       candidate?.evidence.map((item) => item.evidenceId) ?? []
@@ -416,6 +421,7 @@ export const verifyClaimsSemantically = async (
     maxTokens: MAX_OUTPUT_TOKENS,
     jsonSchema: schema,
   });
+  assertInferenceResult(generated);
   if (!generated.ok) {
     return failedResult(
       deterministic,

package/src/pipeline/expansion.ts

@@ -1,16 +1,21 @@
+import { createHash } from "node:crypto"; // No Bun alternative for hashing
+
+import type { InferenceOptions } from "../llm/types";
 /**
  * Query expansion for hybrid search.
  * Uses GenerationPort to generate query variants.
  *
  * @module src/pipeline/expansion
  */
-
-import { createHash } from "node:crypto"; // No Bun alternative for hashing
-
 import type { GenerationPort } from "../llm/types";
 import type { StoreResult } from "../store/types";
 import type { ExpansionResult } from "./types";
 
+import {
+  assertInferenceActive,
+  assertInferenceResult,
+  inferenceOptions,
+} from "../llm/inference-scope";
 import { ok } from "../store/types";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -449,7 +454,7 @@ export function parseExpansionOutput(
 // Expansion Function
 // ─────────────────────────────────────────────────────────────────────────────
 
-export interface ExpansionOptions {
+export interface ExpansionOptions extends InferenceOptions {
   /** Language hint for prompt selection */
   lang?: string;
   /** Timeout in milliseconds */
@@ -474,49 +479,47 @@ export async function expandQuery(
   // Build prompt
   const prompt = buildExpansionPrompt(query, options);
 
-  // Run with timeout (clear timer to avoid resource leak)
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  const timeoutPromise = new Promise<null>((resolve) => {
-    timeoutId = setTimeout(() => resolve(null), timeout);
-  });
-
+  assertInferenceActive(options);
+  const operational = inferenceOptions(options);
+  const budget = new AbortController();
+  const expiresAt = performance.now() + timeout;
+  const timer = setTimeout(() => budget.abort(), timeout);
   try {
-    const result = await Promise.race([
-      genPort.generate(prompt, {
+    const result = await genPort.generate(
+      prompt,
+      {
         temperature: 0,
         seed: 42,
         maxTokens: 512,
         contextSize: options.contextSize,
-      }),
-      timeoutPromise,
-    ]);
-
-    // Clear timeout if generation completed first
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-
-    // Timeout
-    if (result === null) {
+      },
+      {
+        ...operational,
+        signal: operational.signal
+          ? AbortSignal.any([operational.signal, budget.signal])
+          : budget.signal,
+      }
+    );
+    // The independent expansion budget preserves its existing fallback. Caller
+    // cancellation/deadline always wins and cannot become a lexical success.
+    assertInferenceActive(options);
+    if (budget.signal.aborted || performance.now() >= expiresAt)
       return ok(null);
-    }
-
-    // Generation failed
-    if (!result.ok) {
-      return ok(null); // Graceful degradation
-    }
-
-    // Parse result
-    const parsed = parseExpansionOutput(result.value, query);
-    if (!parsed) {
+    assertInferenceResult(result);
+    if (!result.ok) return ok(null);
+    return ok(parseExpansionOutput(result.value, query));
+  } catch (cause) {
+    assertInferenceActive(options);
+    if (budget.signal.aborted || performance.now() >= expiresAt)
       return ok(null);
-    }
-    return ok(parsed);
-  } catch {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-    return ok(null); // Graceful degradation
+    if (
+      cause instanceof Error &&
+      ["AbortError", "TimeoutError"].includes(cause.name)
+    )
+      throw cause;
+    return ok(null);
+  } finally {
+    clearTimeout(timer);
   }
 }
 

package/src/pipeline/explain.ts

@@ -234,7 +234,11 @@ export function buildExplainResults(
       const candidate = candidates.find(
         (entry) =>
           entry.mirrorHash === result.conversion?.mirrorHash &&
-          entry.seq === (planner?.retrievalSeq ?? planner?.seq)
+          entry.seq === (planner?.retrievalSeq ?? planner?.seq) &&
+          (entry.documentId === undefined ||
+            docidMap.get(
+              `${entry.mirrorHash}:${entry.seq}:${entry.documentId}`
+            ) === result.docid)
       );
       return {
         ...buildExplainResult(result.docid, result.score, index, candidate),
@@ -244,7 +248,7 @@ export function buildExplainResults(
     });
   }
   return candidates.slice(0, 20).map((candidate, index) => {
-    const key = `${candidate.mirrorHash}:${candidate.seq}`;
+    const key = `${candidate.mirrorHash}:${candidate.seq}${candidate.documentId === undefined ? "" : `:${candidate.documentId}`}`;
     return buildExplainResult(
       docidMap.get(key) ?? "#unknown",
       candidate.blendedScore,

package/src/pipeline/filters.ts

@@ -15,6 +15,69 @@ export interface QueryFilterEvaluation {
   reasons: string[];
 }
 
+/** Internal pre-budget contract. Undefined metadata is a failed lookup, never
+ * an unrestricted candidate. Owners must be evaluated separately; this does
+ * not replace complete ownership lineage or change ranking/deduplication.
+ * Managed-memory scopes/supersession must already be enforced by the store.
+ */
+export async function evaluateRetrievalEligibility(
+  store: StorePort,
+  query: string,
+  doc: DocumentRow | undefined,
+  chunks: ChunkRow[] | undefined,
+  options: HybridSearchOptions,
+  callerScope?: Pick<HybridSearchOptions, "collection" | "retrievalScope">
+): Promise<QueryFilterEvaluation & { chunks: ChunkRow[] }> {
+  if (!doc || !chunks || !doc.mirrorHash) {
+    return { matches: false, reasons: ["metadata"], chunks: [] };
+  }
+  const reasons: string[] = [];
+  if (!doc.active) reasons.push("inactive");
+  const sourcePath = doc.recordSourcePath ?? doc.relPath;
+  for (const scope of [callerScope, options]) {
+    if (scope?.collection && doc.collection !== scope.collection) {
+      reasons.push("collection");
+    }
+    if (scope?.retrievalScope) {
+      if (!scope.retrievalScope.allowedMirrorHashes.includes(doc.mirrorHash)) {
+        reasons.push("scope");
+      }
+      const prefix = scope.retrievalScope.relPathPrefix;
+      if (
+        prefix !== undefined &&
+        sourcePath !== prefix &&
+        !sourcePath.startsWith(`${prefix}/`)
+      ) {
+        reasons.push("path");
+      }
+    }
+  }
+  // Whole-document exclusions inspect every chunk before language selection.
+  // A mismatched hash is incomplete/corrupt metadata, not a usable owner.
+  if (chunks.some((chunk) => chunk.mirrorHash !== doc.mirrorHash)) {
+    reasons.push("metadata");
+  }
+  if (reasons.length === 0) {
+    try {
+      reasons.push(
+        ...(
+          await evaluateQueryTargetFilters(store, query, doc, chunks, options)
+        ).reasons
+      );
+    } catch {
+      reasons.push("metadata");
+    }
+  }
+  const eligibleChunks = chunks.filter(
+    (chunk) => !options.lang || chunk.language === options.lang
+  );
+  return {
+    matches: reasons.length === 0,
+    reasons,
+    chunks: reasons.length === 0 ? eligibleChunks : [],
+  };
+}
+
 export function evaluateDocumentChunkFilters(
   query: string,
   doc: DocumentRow,

package/src/pipeline/fusion.ts

@@ -15,6 +15,8 @@ import type { FusionCandidate, FusionSource, RrfConfig } from "./types";
 export interface RankedInput {
   source: FusionSource;
   results: Array<{
+    sourceDocid?: string;
+    documentId?: number;
     mirrorHash: string;
     seq: number;
     rank: number; // 1-based rank
@@ -73,11 +75,14 @@ export function rrfFuse(
         : config.bm25Weight * 0.5;
 
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}`;
+      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
       let candidate = candidates.get(key);
 
       if (!candidate) {
         candidate = {
+          ...(result.documentId === undefined
+            ? {}
+            : { documentId: result.documentId }),
           mirrorHash: result.mirrorHash,
           seq: result.seq,
           bm25Rank: null,
@@ -112,11 +117,14 @@ export function rrfFuse(
     }
 
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}`;
+      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
       let candidate = candidates.get(key);
 
       if (!candidate) {
         candidate = {
+          ...(result.documentId === undefined
+            ? {}
+            : { documentId: result.documentId }),
           mirrorHash: result.mirrorHash,
           seq: result.seq,
           bm25Rank: null,
@@ -145,11 +153,14 @@ export function rrfFuse(
     const weight = config.bm25Weight * 0.8;
 
     for (const result of input.results) {
-      const key = `${result.mirrorHash}:${result.seq}`;
+      const key = `${result.mirrorHash}:${result.seq}:${result.documentId ?? ""}`;
       let candidate = candidates.get(key);
 
       if (!candidate) {
         candidate = {
+          ...(result.documentId === undefined
+            ? {}
+            : { documentId: result.documentId }),
           mirrorHash: result.mirrorHash,
           seq: result.seq,
           bm25Rank: null,
@@ -211,14 +222,23 @@ export function rrfFuse(
  */
 export function toRankedInput(
   source: FusionSource,
-  results: Array<{ mirrorHash: string; seq: number }>
+  results: Array<{
+    mirrorHash: string;
+    seq: number;
+    documentIds?: number[];
+    sourceDocid?: string;
+  }>
 ): RankedInput {
   return {
     source,
-    results: results.map((r, i) => ({
-      mirrorHash: r.mirrorHash,
-      seq: r.seq,
-      rank: i + 1,
-    })),
+    results: results.flatMap((r, i) =>
+      (r.documentIds ?? [undefined]).map((documentId) => ({
+        ...(documentId === undefined ? {} : { documentId }),
+        ...(r.sourceDocid === undefined ? {} : { sourceDocid: r.sourceDocid }),
+        mirrorHash: r.mirrorHash,
+        seq: r.seq,
+        rank: i + 1,
+      }))
+    ),
   };
 }