@gmickel/gno 2.12.2 → 2.14.0

package/src/pipeline/hybrid.ts

@@ -150,6 +150,7 @@ async function checkBm25Strength(
   query: string,
   options?: {
     collection?: string;
+    collections?: string[];
     lang?: string;
     tagsAll?: string[];
     tagsAny?: string[];
@@ -168,6 +169,7 @@ async function checkBm25Strength(
   const result = await store.searchFts(query, {
     limit: 5,
     collection: options?.collection,
+    collections: options?.collections,
     relPathPrefix: options?.relPathPrefix,
     language: options?.lang,
     chunkLanguage: options?.lang,
@@ -225,6 +227,7 @@ async function searchFtsChunks(
   options: {
     limit: number;
     collection?: string;
+    collections?: string[];
     lang?: string;
     tagsAll?: string[];
     tagsAny?: string[];
@@ -243,6 +246,7 @@ async function searchFtsChunks(
   const result = await store.searchFts(query, {
     limit: options.limit,
     collection: options.collection,
+    collections: options.collections,
     relPathPrefix: options.relPathPrefix,
     language: options.lang,
     chunkLanguage: options.lang,
@@ -500,6 +504,7 @@ async function searchHybridWithHydration(
       ? false
       : await checkBm25Strength(store, query, {
           collection: options.collection,
+          collections: options.collections,
           lang: options.lang,
           memoryScopesAny: options.memoryFilter?.scopes,
           excludeSuperseded: options.memoryFilter?.excludeSuperseded,
@@ -550,6 +555,7 @@ async function searchHybridWithHydration(
 
   const vectorEligibility: VectorSearchOptions["eligibility"] = {
     collection: options.collection,
+    collections: options.collections,
     memoryScopesAny: options.memoryFilter?.scopes,
     excludeSuperseded: options.memoryFilter?.excludeSuperseded,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
@@ -575,6 +581,7 @@ async function searchHybridWithHydration(
     exclude: options.exclude,
     allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
     collection: options.collection,
+    collections: options.collections,
     lang: options.lang,
     tagsAll: options.tagsAll,
     tagsAny: options.tagsAny,
@@ -615,6 +622,7 @@ async function searchHybridWithHydration(
           exclude: options.exclude,
           allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
           collection: options.collection,
+          collections: options.collections,
           lang: options.lang,
           tagsAll: options.tagsAll,
           tagsAny: options.tagsAny,
@@ -806,7 +814,7 @@ async function searchHybridWithHydration(
     fusedCandidates,
     {
       collection: options.collection,
-      collections: options.graphCollections,
+      collections: options.graphCollections ?? options.collections,
       includeSimilar: vectorAvailable,
       eligibility: vectorEligibility,
       limit,
@@ -879,6 +887,7 @@ async function searchHybridWithHydration(
         [...new Set(fusedCandidates.map((candidate) => candidate.mirrorHash))],
         {
           collection: options.collection,
+          collections: options.collections,
           activeOnly: true,
         }
       );
@@ -991,6 +1000,7 @@ async function searchHybridWithHydration(
       [...neededHashes],
       {
         collection: options.collection,
+        collections: options.collections,
         activeOnly: true,
       }
     );
@@ -1374,7 +1384,9 @@ async function searchHybridWithHydration(
     {
       ownershipHashes: [...neededHashes],
       ownershipDocuments:
-        options.collection === undefined ? documents : undefined,
+        options.collection === undefined && options.collections === undefined
+          ? documents
+          : undefined,
       collections: collectionsResult.ok ? collectionsResult.value : undefined,
     }
   );
@@ -1394,6 +1406,7 @@ async function searchHybridWithHydration(
       intent: options.intent,
       exclude: options.exclude,
       collection: options.collection,
+      collections: options.collections,
       lang: options.lang,
       since: temporalRange.since,
       until: temporalRange.until,

package/src/pipeline/hydration.ts

@@ -142,13 +142,18 @@ export class RequestHydration {
     const store = this.store;
     if (!store) return err("QUERY_FAILED", "Hydration request released");
     // Capture caller-owned options before any asynchronous read. Collection
-    // and activity are part of the lookup identity; titles never key by hash.
-    const scope = { ...options };
+    // scope and activity are part of the lookup identity; titles never key by
+    // hash.
+    const scope = {
+      ...options,
+      collections: options?.collections ? [...options.collections] : undefined,
+    };
     // Cache the exact lookup, retaining the adapter's ordering (including SQL
     // batch boundaries). Regrouping by content hash would reorder documents.
     const requested = [...hashes];
     const identity = JSON.stringify([
       scope.collection ?? null,
+      scope.collections ?? null,
       scope.activeOnly ?? null,
       requested,
     ]);

package/src/pipeline/owner-fusion.ts

@@ -30,6 +30,7 @@ export async function resolveFusionOwners(
   ];
   const documents = await hydration.getDocumentsByMirrorHashes(hashes, {
     collection: options.collection,
+    collections: options.collections,
     activeOnly: true,
   });
   const chunks = await hydration.getChunksBatch(hashes);

package/src/pipeline/search.ts

@@ -341,6 +341,7 @@ export async function searchBm25(
   const ftsResult = await store.searchFts(query, {
     limit: retrievalLimit,
     collection: options.collection,
+    collections: options.collections,
     allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
     exclude: options.exclude,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
@@ -621,6 +622,7 @@ export async function searchBm25(
       intent: options.intent,
       exclude: options.exclude,
       collection: options.collection,
+      collections: options.collections,
       lang: options.lang,
       since: temporalRange.since,
       until: temporalRange.until,

package/src/pipeline/types.ts

@@ -114,6 +114,8 @@ export interface SearchMeta {
   totalResults: number;
   intent?: string;
   collection?: string;
+  /** Normalized collection allowlist; present only when the request set one. */
+  collections?: string[];
   lang?: string;
   /** Detected/overridden query language for prompt selection (typically BCP-47; may be user-provided via --lang) */
   queryLanguage?: string;
@@ -193,6 +195,11 @@ export interface SearchOptions extends InferenceOptions {
   minScore?: number;
   /** Filter by collection */
   collection?: string;
+  /**
+   * Filter to documents in ANY of these collections, before candidate limits.
+   * Never combined with `collection`; surfaces reject that pairing.
+   */
+  collections?: string[];
   /**
    * Internal graph allowlist for a request partitioned into one retrieval per
    * collection (Context Capsules, replay): graph neighbours may come from any

package/src/pipeline/vsearch.ts

@@ -176,6 +176,7 @@ async function searchVectorWithEmbeddingOwned(
         excludeMetadata: true,
         semanticMetadata: true,
         collection: options.collection,
+        collections: options.collections,
         memoryScopesAny: options.memoryFilter?.scopes,
         excludeSuperseded: options.memoryFilter?.excludeSuperseded,
         relPathPrefix: options.retrievalScope?.relPathPrefix,
@@ -215,6 +216,7 @@ async function searchVectorWithEmbeddingOwned(
   const { documents: docsByMirrorHash, ownershipDocuments } =
     await buildDocumentMap(store, {
       collection: options.collection,
+      collections: options.collections,
       relPathPrefix: options.retrievalScope?.relPathPrefix,
       tagsAll: options.tagsAll,
       tagsAny: options.tagsAny,
@@ -547,6 +549,7 @@ async function searchVectorWithEmbeddingOwned(
       intent: options.intent,
       exclude: options.exclude,
       collection: options.collection,
+      collections: options.collections,
       lang: options.lang,
       since: temporalRange.since,
       until: temporalRange.until,
@@ -666,6 +669,7 @@ interface DocumentInfo {
 
 interface DocumentMapOptions {
   collection?: string;
+  collections?: string[];
   relPathPrefix?: string;
   tagsAll?: string[];
   tagsAny?: string[];
@@ -718,11 +722,12 @@ async function buildDocumentMap(
   const ownershipDocuments = options.mirrorHashes
     ? docs.value.filter((d) => d.mirrorHash)
     : docs.value.filter((d) => d.mirrorHash && d.active);
-  const activeDocs = options.collection
-    ? ownershipDocuments.filter(
-        (document) => document.collection === options.collection
-      )
-    : ownershipDocuments;
+  const activeDocs = ownershipDocuments.filter(
+    (document) =>
+      (!options.collection || document.collection === options.collection) &&
+      (options.collections === undefined ||
+        options.collections.includes(document.collection))
+  );
   const temporalRange: TemporalRange = {
     since: options.since,
     until: options.until,

package/src/sdk/client.ts

@@ -110,6 +110,7 @@ import {
 import { publishCapture } from "../core/capture-publish";
 import { projectCollectionEgressPolicy } from "../core/collection-egress-policy-projection";
 import { CollectionEgressPolicyService } from "../core/collection-egress-policy-service";
+import { resolveCollectionScope } from "../core/collection-scope";
 import { applyConfigChange } from "../core/config-mutation";
 import { getDocumentCapabilities } from "../core/document-capabilities";
 import { EgressAuditService } from "../core/egress-audit";
@@ -196,7 +197,7 @@ import {
 } from "../llm/inference-scope";
 import { LlmAdapter } from "../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../llm/policy";
-import { resolveModelUri } from "../llm/registry";
+import { modelCollectionForList, resolveModelUri } from "../llm/registry";
 import {
   answerTraceTerminalStatus,
   generateGroundedAnswer,
@@ -476,6 +477,27 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  /** Normalize and validate a search/vsearch/query `collections` allowlist. */
+  private withCollectionScope<
+    T extends { collection?: string; collections?: string[] },
+  >(options: T): T {
+    const scope = resolveCollectionScope(options, this.config.collections);
+    if (!scope.ok) throw sdkError("VALIDATION", scope.message);
+    return scope.collections === undefined
+      ? options
+      : { ...options, collections: scope.collections };
+  }
+
+  private modelCollection(
+    type: "embed" | "expand" | "rerank",
+    options: { collection?: string; collections?: string[] }
+  ): string | undefined {
+    return (
+      options.collection ??
+      modelCollectionForList(this.config, type, options.collections)
+    );
+  }
+
   private getCollections(collection?: string) {
     if (!collection) {
       return this.config.collections;
@@ -541,6 +563,7 @@ class GnoClientImpl implements GnoClient {
     answer?: boolean;
     rerank?: boolean;
     collection?: string;
+    collections?: string[];
     requiredEmbed?: boolean;
     requiredExpand?: boolean;
     requiredAnswer?: boolean;
@@ -551,9 +574,9 @@ class GnoClientImpl implements GnoClient {
     rerankModel?: string;
   }): Promise<RuntimePorts> {
     this.assertOpen();
-    const egressCollections = options.collection
-      ? [options.collection]
-      : ("all" as const);
+    const egressCollections =
+      options.collections ??
+      (options.collection ? [options.collection] : ("all" as const));
 
     let embedPort: EmbeddingPort | null = null;
     let expandPort: GenerationPort | null = null;
@@ -567,7 +590,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "embed",
           options.embedModel,
-          options.collection
+          this.modelCollection("embed", options)
         ),
         {
           egressCollections,
@@ -612,7 +635,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "expand",
           options.expandModel ?? options.genModel,
-          options.collection
+          this.modelCollection("expand", options)
         ),
         {
           egressCollections,
@@ -665,7 +688,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "rerank",
           options.rerankModel,
-          options.collection
+          this.modelCollection("rerank", options)
         ),
         {
           egressCollections,
@@ -735,6 +758,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
     let traceSession: RetrievalTraceSession | null = null;
     try {
       const { projectHints, ...searchOptions } = options;
@@ -789,6 +813,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoVectorSearchOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
 
     let ports: RuntimePorts | null = null;
     let traceSession: RetrievalTraceSession | null = null;
@@ -805,7 +830,7 @@ class GnoClientImpl implements GnoClient {
         this.config,
         "embed",
         options.model,
-        options.collection
+        this.modelCollection("embed", options)
       );
       traceSession = unwrapStore(
         await startRetrievalTraceRequest({
@@ -823,6 +848,7 @@ class GnoClientImpl implements GnoClient {
         requiredEmbed: true,
         embedModel: options.model,
         collection: options.collection,
+        collections: options.collections,
       });
       if (!ports.embedPort || !ports.vectorIndex) {
         throw sdkError(
@@ -882,6 +908,7 @@ class GnoClientImpl implements GnoClient {
     options: GnoQueryOptions
   ): Promise<SearchResults> {
     this.assertOpen();
+    options = this.withCollectionScope(options);
 
     const normalizedInput = normalizeStructuredQueryInput(
       query,
@@ -905,14 +932,14 @@ class GnoClientImpl implements GnoClient {
       this.config,
       "embed",
       options.embedModel,
-      options.collection
+      this.modelCollection("embed", options)
     );
     const expandUri = expandRequested
       ? resolveModelUri(
           this.config,
           "expand",
           options.expandModel ?? options.genModel,
-          options.collection
+          this.modelCollection("expand", options)
         )
       : undefined;
     const rerankUri = rerankRequested
@@ -920,7 +947,7 @@ class GnoClientImpl implements GnoClient {
           this.config,
           "rerank",
           options.rerankModel,
-          options.collection
+          this.modelCollection("rerank", options)
         )
       : undefined;
     let ports: RuntimePorts | null = null;
@@ -956,6 +983,7 @@ class GnoClientImpl implements GnoClient {
         genModel: options.genModel,
         rerankModel: options.rerankModel,
         collection: options.collection,
+        collections: options.collections,
       });
       return attachRetrievalTraceMetadata(
         this.decorateSearchResults(
@@ -1496,7 +1524,12 @@ class GnoClientImpl implements GnoClient {
 
   async list(options: GnoListOptions = {}) {
     this.assertOpen();
-    const result = await listDocuments(this.store, options);
+    const result = await listDocuments(
+      this.store,
+      options.filter === undefined
+        ? options
+        : { ...options, filter: normalizeSdkMetadataFilter(options.filter) }
+    );
     return {
       ...result,
       documents: result.documents.map((doc) => ({

package/src/sdk/convert.ts

@@ -0,0 +1,27 @@
+/**
+ * SDK conversion of one file to the Markdown GNO would index (no client,
+ * config or index needed).
+ *
+ * @module src/sdk/convert
+ */
+
+import {
+  type ConvertFileResult,
+  convertFile as convertOneFile,
+} from "../ingestion/convert-file";
+import { sdkError } from "./errors";
+
+/**
+ * Convert one file to the Markdown GNO would index for it; nothing is
+ * persisted. Failures throw `GnoSdkError` with `details.reason` set to the
+ * same reason `gno convert` reports.
+ */
+export async function convertFile(path: string): Promise<ConvertFileResult> {
+  const result = await convertOneFile(path);
+  if (result.ok) return result.value;
+  const { reason, message, validation, details } = result.error;
+  let code: "NOT_FOUND" | "VALIDATION" | "RUNTIME" = "RUNTIME";
+  if (reason === "NOT_FOUND") code = "NOT_FOUND";
+  else if (validation) code = "VALIDATION";
+  throw sdkError(code, message, { details: { reason, ...details } });
+}

package/src/sdk/documents.ts

@@ -30,6 +30,10 @@ import {
   evidenceFromExactDocument,
   RetrievalTraceSession,
 } from "../core/retrieval-trace-session";
+import {
+  filterDocumentsByMetadata,
+  metadataCoverageWarnings,
+} from "../pipeline/filters";
 import { supersedingUri } from "../pipeline/result-context";
 import { sdkError } from "./errors";
 
@@ -388,11 +392,19 @@ export async function listDocuments(
     });
   }
 
-  const allActive = docsResult.value
+  const inScope = docsResult.value
     .filter((d) => d.active)
     .filter((d) =>
       !scope?.startsWith("gno://") ? true : d.uri.startsWith(scope)
-    )
+    );
+  const filtered = options.filter
+    ? filterDocumentsByMetadata(inScope, options.filter)
+    : undefined;
+  const warnings = filtered
+    ? metadataCoverageWarnings(filtered, "listing")
+    : undefined;
+
+  const allActive = (filtered?.matches ?? inScope)
     .map((d) => ({
       docid: d.docid,
       uri: d.uri,
@@ -415,6 +427,7 @@ export async function listDocuments(
       total: allActive.length,
       returned: paged.length,
       offset,
+      ...(warnings ? { warnings } : {}),
     },
   };
 }

package/src/sdk/index.ts

@@ -27,6 +27,8 @@ export type { IndexStatus } from "../store/types";
 
 export { GnoSdkError, sdkError } from "./errors";
 export { createGnoClient } from "./client";
+export { convertFile } from "./convert";
+export type { ConvertFileResult } from "../ingestion/convert-file";
 export type {
   DocumentSection,
   GnoAskOptions,

package/src/sdk/types.ts

@@ -89,6 +89,7 @@ import type {
   SectionTargetResolveResult,
   SectionTargetV1,
 } from "../core/sections";
+import type { MetadataPredicate } from "../core/typed-metadata";
 import type { SyncResult } from "../ingestion";
 import type { CollectionRootError } from "../ingestion/source-availability/root";
 import type { DownloadPolicy } from "../llm/policy";
@@ -179,7 +180,7 @@ export type GnoQueryOptions = Omit<
   GnoProjectHintOptions;
 export type GnoAskOptions = Omit<
   AskOptions,
-  "contentTypeRules" | "projectAffinity"
+  "collections" | "contentTypeRules" | "projectAffinity"
 > &
   GnoModelOverrides &
   GnoProjectHintOptions;
@@ -223,6 +224,8 @@ export interface GnoListOptions {
   scope?: string;
   limit?: number;
   offset?: number;
+  /** Typed metadata predicate, as for search `filter`. */
+  filter?: MetadataPredicate;
 }
 
 export interface GnoUpdateOptions {

package/src/serve/jobs.ts

@@ -16,11 +16,13 @@ export interface JobProgress {
 export interface JobStatus {
   id: string;
   type: JobType;
-  status: "running" | "completed" | "failed";
+  status: "queued" | "running" | "completed" | "failed";
   createdAt: number;
   progress?: JobProgress;
   result?: SyncResult;
   error?: string;
+  /** Reindex jobs: the collection (null = all) and merged paths (null = whole). */
+  scope?: JobRecord["scope"];
 }
 
 export interface StartJobSuccess {
@@ -49,6 +51,7 @@ const fromResidentRecord = (record: JobRecord): JobStatus => ({
   progress: record.progress,
   result: record.result,
   error: record.error,
+  ...(record.scope ? { scope: record.scope } : {}),
 });
 
 function cleanupExpiredJobs(now = Date.now()): void {

package/src/serve/public/components/IndexingProgress.tsx

@@ -24,7 +24,7 @@ import { Badge } from "./ui/badge";
 export interface JobStatus {
   id: string;
   type: "add" | "sync";
-  status: "running" | "completed" | "failed";
+  status: "queued" | "running" | "completed" | "failed";
   createdAt: number;
   result?: SyncResult;
   error?: string;
@@ -138,7 +138,7 @@ export function IndexingProgress({
       setStatus(data);
       setFetchError(null);
 
-      if (data.status === "running") {
+      if (data.status === "queued" || data.status === "running") {
         pollTimeout = setTimeout(() => {
           void poll();
         }, 1000);
@@ -187,6 +187,20 @@ export function IndexingProgress({
 
   // Compact mode
   if (compact) {
+    if (status?.status === "queued") {
+      return (
+        <div
+          aria-live="polite"
+          className={cn("flex items-center gap-2 text-sm", className)}
+        >
+          <Loader2Icon className="size-4 animate-spin text-muted-foreground" />
+          <span className="text-muted-foreground">
+            Queued... {formatElapsed(elapsed)}
+          </span>
+        </div>
+      );
+    }
+
     if (status?.status === "running") {
       return (
         <div
@@ -237,6 +251,14 @@ export function IndexingProgress({
       {/* Status header */}
       <div className="flex items-center justify-between">
         <div className="flex items-center gap-2">
+          {status?.status === "queued" && (
+            <>
+              <Loader2Icon className="size-5 animate-spin text-muted-foreground" />
+              <span className="font-medium">
+                Queued behind another indexing job
+              </span>
+            </>
+          )}
           {status?.status === "running" && (
             <>
               <Loader2Icon className="size-5 animate-spin text-primary" />
@@ -264,7 +286,7 @@ export function IndexingProgress({
         <div className="flex items-center gap-1.5 text-muted-foreground text-sm">
           <TimerIcon className="size-4" />
           <span>
-            {status?.status === "running"
+            {status?.status === "queued" || status?.status === "running"
               ? formatElapsed(elapsed)
               : formatDuration(status?.result?.totalDurationMs ?? elapsed)}
           </span>