@gmickel/gno 2.12.2 → 2.14.0

package/src/mcp/tools/index.ts

@@ -27,6 +27,7 @@ import {
   readMetadataSummary,
 } from "../../core/metadata-discovery";
 import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
+import { MAX_REINDEX_PATHS } from "../../core/reindex-paths";
 import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
 import {
@@ -255,6 +256,12 @@ export const searchInputSchema = z.object({
     .string()
     .optional()
     .describe("Filter to a single collection name"),
+  collections: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Filter to any of these collection names (1-256); use instead of collection"
+    ),
   limit: z
     .number()
     .int()
@@ -437,6 +444,13 @@ const syncInputSchema = z.object({
     .boolean()
     .default(false)
     .describe("Run the collection's configured update command before syncing"),
+  paths: z
+    .array(z.string())
+    .max(MAX_REINDEX_PATHS)
+    .optional()
+    .describe(
+      "Reindex only these files (1-256, relative to the collection root, or absolute inside it). Requires collection"
+    ),
 });
 
 const embedInputSchema = z.object({
@@ -452,6 +466,13 @@ const indexInputSchema = z.object({
     .optional()
     .describe("Collection name to index. Omit to index all collections"),
   gitPull: z.boolean().default(false).describe("Run git pull before indexing"),
+  paths: z
+    .array(z.string())
+    .max(MAX_REINDEX_PATHS)
+    .optional()
+    .describe(
+      "Reindex only these files (1-256, relative to the collection root, or absolute inside it). Requires collection"
+    ),
 });
 
 const removeCollectionInputSchema = z.object({
@@ -496,6 +517,12 @@ export const vsearchInputSchema = z.object({
     .string()
     .optional()
     .describe("Filter to a single collection name"),
+  collections: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Filter to any of these collection names (1-256); use instead of collection"
+    ),
   limit: z
     .number()
     .int()
@@ -570,6 +597,12 @@ export const queryInputSchema = z.object({
     .string()
     .optional()
     .describe("Filter to a single collection name"),
+  collections: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Filter to any of these collection names (1-256); use instead of collection"
+    ),
   limit: z
     .number()
     .int()
@@ -672,15 +705,17 @@ export const queryInputSchema = z.object({
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });
 
-export const queryDiagnoseInputSchema = queryInputSchema.extend({
-  target: z
-    .string()
-    .trim()
-    .min(1, "Target reference cannot be empty")
-    .describe(
-      "Target document reference to diagnose (gno URI, docid, or collection/path)"
-    ),
-});
+export const queryDiagnoseInputSchema = queryInputSchema
+  .omit({ collections: true })
+  .extend({
+    target: z
+      .string()
+      .trim()
+      .min(1, "Target reference cannot be empty")
+      .describe(
+        "Target document reference to diagnose (gno URI, docid, or collection/path)"
+      ),
+  });
 
 const getInputSchema = z.object({
   ref: z
@@ -1019,7 +1054,8 @@ export async function runTool<T>(
   try {
     assertConfiguredCollections(ctx, name);
     assertInferenceActive();
-    const raw = await (ctx.runWithSnapshot?.(fn) ?? fn());
+    const read = READ_CONNECTION_TOOLS.has(name) ? readConnection(ctx, fn) : fn;
+    const raw = await (ctx.runWithSnapshot?.(read) ?? read());
     assertInferenceActive();
     const traceMetadata =
       raw !== null && typeof raw === "object"
@@ -1048,6 +1084,34 @@ export async function runTool<T>(
   }
 }
 
+/**
+ * Read-only retrieval tools. They read on the store's read connection, so a
+ * sync batch that is still writing is never visible to them.
+ */
+const READ_CONNECTION_TOOLS = new Set([
+  "gno_search",
+  "gno_vsearch",
+  "gno_query",
+  "gno_get",
+  "gno_multi_get",
+  "gno_status",
+  "gno_list_tags",
+  "gno_links",
+  "gno_backlinks",
+  "gno_similar",
+]);
+
+/** Store test doubles may lack the read connection; they read as before. */
+function readConnection<T>(
+  ctx: ToolContext,
+  fn: () => Promise<T>
+): () => Promise<T> {
+  const store = ctx.store as Partial<ToolContext["store"]> | undefined;
+  return typeof store?.withReadConnection === "function"
+    ? () => ctx.store.withReadConnection(fn)
+    : fn;
+}
+
 /**
  * Run a tool without acquiring the mutex.
  * For read-only in-memory tools (job_status, list_jobs) that should not block.

package/src/mcp/tools/job-status.ts

@@ -24,6 +24,7 @@ interface JobStatusResult {
   result?: SyncResult;
   typedResult?: JobResult;
   error?: string;
+  scope?: JobRecord["scope"];
   serverInstanceId: string;
 }
 
@@ -34,6 +35,11 @@ function formatJobStatus(result: JobStatusResult): string {
   lines.push(`Type: ${result.type}`);
   lines.push(`Status: ${result.status}`);
   lines.push(`Started: ${result.startedAt}`);
+  if (result.scope) {
+    lines.push(`Collection: ${result.scope.collection ?? "(all)"}`);
+    if (result.scope.paths)
+      lines.push(`Paths: ${result.scope.paths.join(", ")}`);
+  }
 
   if (result.completedAt) {
     lines.push(`Completed: ${result.completedAt}`);
@@ -92,6 +98,7 @@ function toJobStatusResult(job: JobRecord): JobStatusResult {
     result: job.result,
     typedResult: job.typedResult,
     error: job.error,
+    ...(job.scope ? { scope: job.scope } : {}),
     serverInstanceId: job.serverInstanceId,
   };
 }

package/src/mcp/tools/query.ts

@@ -44,17 +44,23 @@ import {
 } from "../../core/typed-metadata";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
-import { getActivePreset, resolveModelUri } from "../../llm/registry";
+import {
+  getActivePreset,
+  modelCollectionForList,
+  resolveModelUri,
+} from "../../llm/registry";
 import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
 import { createLazyVectorIndex } from "../../store/vector/lazy";
 import { appendRetrievalWarnings } from "../retrieval-warnings";
+import { requestCollections } from "./collection-scope";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface QueryInput {
   query: string;
   projectHints?: string[];
   collection?: string;
+  collections?: string[];
   limit?: number;
   minScore?: number;
   lang?: string;
@@ -198,6 +204,7 @@ export function handleQuery(
           throw new Error(`Collection not found: ${args.collection}`);
         }
       }
+      const collections = requestCollections(args, ctx);
 
       const normalizedInput = normalizeStructuredQueryInput(
         args.query,
@@ -219,11 +226,14 @@ export function handleQuery(
       let rerankPort: RerankPort | null = null;
       let vectorIndex: VectorIndexPort | null = null;
       let traceSession: RetrievalTraceSession | undefined;
+      const modelCollection = (type: "embed" | "expand" | "rerank") =>
+        args.collection ??
+        modelCollectionForList(ctx.config, type, collections);
       const embedUri = resolveModelUri(
         ctx.config,
         "embed",
         undefined,
-        args.collection
+        modelCollection("embed")
       );
       const hasStructuredModes = Boolean(queryModes?.length);
       const depthPolicy = resolveDepthPolicy({
@@ -242,15 +252,26 @@ export function handleQuery(
       );
       const expandUri =
         !noExpand && !hasStructuredModes
-          ? resolveModelUri(ctx.config, "expand", undefined, args.collection)
+          ? resolveModelUri(
+              ctx.config,
+              "expand",
+              undefined,
+              modelCollection("expand")
+            )
           : undefined;
       const rerankUri = !noRerank
-        ? resolveModelUri(ctx.config, "rerank", undefined, args.collection)
+        ? resolveModelUri(
+            ctx.config,
+            "rerank",
+            undefined,
+            modelCollection("rerank")
+          )
         : undefined;
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
         collection: args.collection,
+        collections,
         queryLanguageHint: args.lang,
         intent: args.intent,
         candidateLimit: depthPolicy.candidateLimit,
@@ -289,9 +310,9 @@ export function handleQuery(
         if (!traceStart.ok) throw new Error(traceStart.error.message);
         traceSession = traceStart.value ?? undefined;
         const llm = ctx.getModelAdapter?.() ?? new LlmAdapter(ctx.config);
-        const egressCollections = args.collection
-          ? [args.collection]
-          : ("all" as const);
+        const egressCollections =
+          collections ??
+          (args.collection ? [args.collection] : ("all" as const));
 
         // Resolve download policy from env (MCP has no CLI flags)
         const policy = resolveDownloadPolicy(process.env, {});

package/src/mcp/tools/search.ts

@@ -25,12 +25,14 @@ import {
 } from "../../core/typed-metadata";
 import { searchBm25 } from "../../pipeline/search";
 import { appendRetrievalWarnings } from "../retrieval-warnings";
+import { requestCollections } from "./collection-scope";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface SearchInput {
   query: string;
   projectHints?: string[];
   collection?: string;
+  collections?: string[];
   limit?: number;
   minScore?: number;
   lang?: string;
@@ -123,6 +125,7 @@ export function handleSearch(
           throw new Error(`Collection not found: ${args.collection}`);
         }
       }
+      const collections = requestCollections(args, ctx);
 
       const projectAffinity = await resolveRemoteProjectAffinity(
         ctx.config,
@@ -132,6 +135,7 @@ export function handleSearch(
         limit: args.limit ?? 5,
         minScore: args.minScore,
         collection: args.collection,
+        collections,
         lang: args.lang,
         intent: args.intent,
         exclude: args.exclude,

package/src/mcp/tools/sync.ts

@@ -9,9 +9,9 @@ import type { CollectionSyncResult, SyncResult } from "../../ingestion";
 import type { ToolContext } from "../server";
 
 import { MCP_ERRORS } from "../../core/errors";
-import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
 import { JobError } from "../../core/job-manager";
 import { recordContentMutation } from "../../core/mutation-generations";
+import { resolveReindexScope } from "../../core/reindex-paths";
 import { normalizeCollectionName } from "../../core/validation";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
 import { enforceSyncCommandEgress } from "../sync-egress";
@@ -21,12 +21,14 @@ interface SyncInput {
   collection?: string;
   gitPull?: boolean;
   runUpdateCmd?: boolean;
+  paths?: string[];
 }
 
 interface SyncResultOutput {
   jobId: string;
   collections: string[];
-  status: "started";
+  status: "started" | "queued";
+  paths?: string[];
   options: {
     gitPull: boolean;
     runUpdateCmd: boolean;
@@ -38,6 +40,7 @@ function formatSyncResult(result: SyncResultOutput): string {
   lines.push(`Job: ${result.jobId}`);
   lines.push(`Status: ${result.status}`);
   lines.push(`Collections: ${result.collections.join(", ") || "(none)"}`);
+  if (result.paths) lines.push(`Paths: ${result.paths.join(", ")}`);
   lines.push(`Git pull: ${result.options.gitPull ? "yes" : "no"}`);
   lines.push(`Run update cmd: ${result.options.runUpdateCmd ? "yes" : "no"}`);
   return lines.join("\n");
@@ -77,73 +80,82 @@ export function handleSync(
         throw new Error("Write tools disabled. Start MCP with --enable-write.");
       }
 
-      let lock: WriteLockHandle | null = null;
-      let handedOff = false;
+      const requestedCollection = args.collection?.trim();
+      const collection = requestedCollection
+        ? resolveCollection(requestedCollection, ctx.collections)
+        : null;
 
-      try {
-        lock = await acquireWriteLock(ctx.writeLockPath);
-        if (!lock) {
-          throw new Error(
-            `${MCP_ERRORS.LOCKED.code}: ${MCP_ERRORS.LOCKED.message}`
-          );
-        }
-
-        const requestedCollection = args.collection?.trim();
-        const collection = requestedCollection
-          ? resolveCollection(requestedCollection, ctx.collections)
-          : null;
-
-        if (requestedCollection && !collection) {
-          throw new Error(
-            `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${requestedCollection}`
-          );
-        }
-
-        const collections = collection
-          ? [collection.name]
-          : ctx.collections.map((entry) => entry.name);
-
-        const options = withContentTypeRules(
-          {
-            gitPull: args.gitPull ?? false,
-            runUpdateCmd: args.runUpdateCmd ?? false,
-          },
-          ctx.config
+      if (requestedCollection && !collection) {
+        throw new Error(
+          `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${requestedCollection}`
         );
-        enforceSyncCommandEgress(ctx, {
-          collectionNames: collections,
-          gitPull: options.gitPull,
-          runUpdateCmd: options.runUpdateCmd,
-        });
+      }
 
-        const jobId = await ctx.jobManager.startJobWithLock(
-          "sync",
-          lock,
-          async () => {
+      const collections = collection
+        ? [collection.name]
+        : ctx.collections.map((entry) => entry.name);
+
+      const options = withContentTypeRules(
+        {
+          gitPull: args.gitPull ?? false,
+          runUpdateCmd: args.runUpdateCmd ?? false,
+        },
+        ctx.config
+      );
+      const paths = await resolveReindexScope(collection, args.paths, options);
+      enforceSyncCommandEgress(ctx, {
+        collectionNames: collections,
+        gitPull: options.gitPull,
+        runUpdateCmd: options.runUpdateCmd,
+      });
+
+      // Captured now: a queued pass runs after this call's context is gone.
+      const config = ctx.config;
+      const allCollections = ctx.collections;
+      try {
+        const accepted = await ctx.jobManager.submitReindex({
+          type: "sync",
+          collection: collection?.name ?? null,
+          paths,
+          options: {
+            gitPull: options.gitPull ?? false,
+            runUpdateCmd: options.runUpdateCmd ?? false,
+          },
+          run: async (scope) => {
+            const passOptions = withContentTypeRules(
+              { ...scope.options },
+              config
+            );
             const result = collection
               ? wrapSingleSync(
-                  await defaultSyncService.syncCollection(
-                    collection,
-                    ctx.store,
-                    options
-                  )
+                  scope.paths
+                    ? await defaultSyncService.syncPaths(
+                        collection,
+                        ctx.store,
+                        scope.paths,
+                        passOptions
+                      )
+                    : await defaultSyncService.syncCollection(
+                        collection,
+                        ctx.store,
+                        passOptions
+                      )
                 )
               : await defaultSyncService.syncAll(
-                  ctx.collections,
+                  allCollections,
                   ctx.store,
-                  options
+                  passOptions
                 );
             recordContentMutation(result, ctx.markContentMutation);
-            return result;
-          }
-        );
-
-        handedOff = true;
+            return { kind: "sync" as const, value: result };
+          },
+        });
 
         const result: SyncResultOutput = {
-          jobId,
+          jobId: accepted.jobId,
           collections,
-          status: "started",
+          status: accepted.status === "running" ? "started" : "queued",
+          ...(paths ? { paths } : {}),
           options: {
             gitPull: options.gitPull ?? false,
             runUpdateCmd: options.runUpdateCmd ?? false,
@@ -156,10 +168,6 @@ export function handleSync(
           throw new Error(`${error.code}: ${error.message}`);
         }
         throw error;
-      } finally {
-        if (lock && !handedOff) {
-          await lock.release();
-        }
       }
     },
     formatSyncResult

package/src/mcp/tools/vsearch.ts

@@ -28,7 +28,7 @@ import {
 } from "../../core/typed-metadata";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
-import { resolveModelUri } from "../../llm/registry";
+import { modelCollectionForList, resolveModelUri } from "../../llm/registry";
 import { formatQueryForEmbedding } from "../../pipeline/contextual";
 import {
   searchVectorWithEmbedding,
@@ -36,12 +36,14 @@ import {
 } from "../../pipeline/vsearch";
 import { createVectorIndexPort } from "../../store/vector";
 import { appendRetrievalWarnings } from "../retrieval-warnings";
+import { requestCollections } from "./collection-scope";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface VsearchInput {
   query: string;
   projectHints?: string[];
   collection?: string;
+  collections?: string[];
   limit?: number;
   minScore?: number;
   lang?: string;
@@ -137,13 +139,15 @@ export function handleVsearch(
           throw new Error(`Collection not found: ${args.collection}`);
         }
       }
+      const collections = requestCollections(args, ctx);
 
       // Get model from active preset
       const modelUri = resolveModelUri(
         ctx.config,
         "embed",
         undefined,
-        args.collection
+        args.collection ??
+          modelCollectionForList(ctx.config, "embed", collections)
       );
       const projectAffinity = await resolveRemoteProjectAffinity(
         ctx.config,
@@ -153,6 +157,7 @@ export function handleVsearch(
         limit: args.limit ?? 5,
         minScore: args.minScore,
         collection: args.collection,
+        collections,
         intent: args.intent,
         exclude: args.exclude,
         since: args.since,
@@ -192,7 +197,8 @@ export function handleVsearch(
         // Create LLM adapter for embeddings
         const llm = ctx.getModelAdapter?.() ?? new LlmAdapter(ctx.config);
         const embedResult = await llm.createEmbeddingPort(modelUri, {
-          egressCollections: args.collection ? [args.collection] : "all",
+          egressCollections:
+            collections ?? (args.collection ? [args.collection] : "all"),
           policy,
           onProgress: (progress) => downloadProgress("embed", progress),
         });

package/src/pipeline/filters.ts

@@ -25,13 +25,27 @@ export interface QueryFilterEvaluation {
  * not replace complete ownership lineage or change ranking/deduplication.
  * Managed-memory scopes/supersession must already be enforced by the store.
  */
+/** True when `collection` falls outside the request's collection scope. */
+function outsideCollectionScope(
+  scope: Pick<HybridSearchOptions, "collection" | "collections">,
+  collection: string
+): boolean {
+  if (scope.collection && collection !== scope.collection) return true;
+  return (
+    scope.collections !== undefined && !scope.collections.includes(collection)
+  );
+}
+
 export async function evaluateRetrievalEligibility(
   store: StorePort,
   query: string,
   doc: DocumentRow | undefined,
   chunks: ChunkRow[] | undefined,
   options: HybridSearchOptions,
-  callerScope?: Pick<HybridSearchOptions, "collection" | "retrievalScope">
+  callerScope?: Pick<
+    HybridSearchOptions,
+    "collection" | "collections" | "retrievalScope"
+  >
 ): Promise<QueryFilterEvaluation & { chunks: ChunkRow[] }> {
   if (!doc || !chunks || !doc.mirrorHash) {
     return { matches: false, reasons: ["metadata"], chunks: [] };
@@ -40,7 +54,7 @@ export async function evaluateRetrievalEligibility(
   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) {
+    if (scope && outsideCollectionScope(scope, doc.collection)) {
       reasons.push("collection");
     }
     if (scope?.retrievalScope) {
@@ -98,7 +112,7 @@ export function evaluateDocumentChunkFilters(
     options.until
   );
 
-  if (options.collection && doc.collection !== options.collection) {
+  if (outsideCollectionScope(options, doc.collection)) {
     reasons.push("collection");
   }
   if (!isWithinTemporalRange(doc.sourceMtime, temporalRange)) {
@@ -219,6 +233,7 @@ export async function typedMetadataWarnings(
   const range = resolveTemporalRange(query, options.since, options.until);
   const result = await store.getTypedMetadataCoverage({
     collection: options.collection,
+    collections: options.collections,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
     allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
     chunkLanguage: options.lang,
@@ -235,13 +250,41 @@ export async function typedMetadataWarnings(
     excludeSuperseded: options.memoryFilter?.excludeSuperseded,
   });
   if (!result.ok) return unknown;
-  const { pending, invalid } = result.value;
+  return metadataCoverageWarnings(result.value, "query");
+}
+
+/** The coverage warning for documents a typed metadata filter had to skip. */
+export function metadataCoverageWarnings(
+  coverage: { pending: number; invalid: number },
+  scope: "query" | "listing"
+): { code: string; message: string }[] | undefined {
+  const { pending, invalid } = coverage;
   return pending || invalid
     ? [
         {
           code: "METADATA_COVERAGE_INCOMPLETE",
-          message: `Typed metadata coverage is incomplete: ${pending} documents need re-ingestion and ${invalid} have invalid metadata within the query scope.`,
+          message: `Typed metadata coverage is incomplete: ${pending} documents need re-ingestion and ${invalid} have invalid metadata within the ${scope} scope.`,
         },
       ]
     : undefined;
 }
+
+/**
+ * Keep the documents a typed metadata predicate matches, counting the ones it
+ * could not judge (pending re-ingestion or invalid metadata) for the warning.
+ */
+export function filterDocumentsByMetadata<T extends DocumentRow>(
+  docs: readonly T[],
+  filter: MetadataPredicate
+): { matches: T[]; pending: number; invalid: number } {
+  const matches: T[] = [];
+  let pending = 0;
+  let invalid = 0;
+  for (const doc of docs) {
+    const reason = typedMetadataFilterReason(doc, filter);
+    if (reason === undefined) matches.push(doc);
+    else if (reason === "metadata_backfill") pending += 1;
+    else if (reason === "metadata_invalid") invalid += 1;
+  }
+  return { matches, pending, invalid };
+}

package/src/pipeline/graph-retrieval.ts

@@ -304,6 +304,7 @@ export async function expandGraphCandidates(
     seedHashes,
     {
       collection: options.collection,
+      collections: options.collections,
       activeOnly: true,
     }
   );