@gmickel/gno 2.12.2 → 2.14.0

package/src/serve/routes/api.ts

@@ -16,7 +16,6 @@ import type {
   EgressPolicy,
   ModelPreset,
 } from "../../config/types";
-import type { JobManager } from "../../core/job-manager";
 import type { ProjectAffinityScoringInput } from "../../pipeline/project-affinity";
 import type {
   AskResult,
@@ -57,6 +56,7 @@ import {
   type EgressRelaxationConfirmation,
 } from "../../core/collection-egress-policy-service";
 import { parsePolicySetBody } from "../../core/collection-egress-policy-validation";
+import { resolveCollectionScope } from "../../core/collection-scope";
 import {
   type ConnectorVerificationCode,
   getConnectorVerificationRemediation,
@@ -82,6 +82,7 @@ import {
   planCreateFolder,
   planDuplicateRefactor,
 } from "../../core/file-refactors";
+import { JobError, type JobManager } from "../../core/job-manager";
 import {
   MemoryError,
   type MemoryErrorCode,
@@ -111,6 +112,7 @@ import {
   resolveRemoteProjectAffinity,
 } from "../../core/project-affinity-surface";
 import { projectRecordEvidenceMetadata } from "../../core/record-metadata";
+import { resolveReindexScope } from "../../core/reindex-paths";
 import {
   isLeaseBusy,
   localRequestLedger,
@@ -303,6 +305,8 @@ export interface SearchRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  /** Collection allowlist (1-256 names); not combined with `collection`. */
+  collections?: string[];
   intent?: string;
   exclude?: string;
   since?: string;
@@ -323,6 +327,8 @@ export interface QueryRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  /** Collection allowlist (1-256 names); not combined with `collection`. */
+  collections?: string[];
   lang?: string;
   intent?: string;
   candidateLimit?: number;
@@ -496,6 +502,7 @@ export interface ImportPreviewRequestBody {
 export interface SyncRequestBody {
   collection?: string;
   gitPull?: boolean;
+  paths?: string[];
 }
 
 export interface CreateDocRequestBody {
@@ -651,6 +658,42 @@ function parseRestMetadataFilter(
   return { ok: true, filter: normalizeMetadataPredicate(parsed.data) };
 }
 
+/**
+ * Resolve a search/query `collections` allowlist: 400 VALIDATION for malformed
+ * input or `collection` with `collections`, 404 NOT_FOUND for unknown names.
+ */
+async function parseRestCollectionScope(
+  body: { collection?: unknown; collections?: unknown },
+  configured: readonly { name: string }[] | null,
+  store: SqliteAdapter
+): Promise<
+  | { ok: true; collections: string[] | undefined }
+  | { ok: false; response: Response }
+> {
+  if (body.collections === undefined)
+    return { ok: true, collections: undefined };
+  let names = configured;
+  if (!names) {
+    const stored = await store.getCollections();
+    if (!stored.ok) {
+      return {
+        ok: false,
+        response: errorResponse("RUNTIME", stored.error.message, 500),
+      };
+    }
+    names = stored.value;
+  }
+  const scope = resolveCollectionScope(body, names);
+  if (scope.ok) return { ok: true, collections: scope.collections };
+  return {
+    ok: false,
+    response:
+      scope.kind === "validation"
+        ? errorResponse("VALIDATION", scope.message)
+        : errorResponse("NOT_FOUND", scope.message, 404),
+  };
+}
+
 function fileRefactorHttpErrorResponse(error: FileRefactorHttpError): Response {
   return errorResponse(error.code, error.message, error.status, error.details);
 }
@@ -1780,6 +1823,9 @@ export async function handleSync(
   if (body.gitPull !== undefined && typeof body.gitPull !== "boolean") {
     return errorResponse("VALIDATION", "gitPull must be a boolean");
   }
+  if (body.paths !== undefined && !Array.isArray(body.paths)) {
+    return errorResponse("VALIDATION", "paths must be an array of strings");
+  }
 
   // Get collections to sync (case-insensitive matching)
   const collectionName = body.collection?.toLowerCase();
@@ -1801,31 +1847,95 @@ export async function handleSync(
     return errorResponse("VALIDATION", "No collections to sync");
   }
 
-  // Start background sync job
-  const jobResult = await startJob(
-    "sync",
-    async (): Promise<SyncResult> => {
-      const result = await defaultSyncService.syncAll(
-        collections,
-        store,
-        withContentTypeRules(
-          {
-            gitPull: body.gitPull,
-            runUpdateCmd: true,
-          },
-          ctxHolder.config
-        )
-      );
-      recordContentMutation(result, ctxHolder.markContentMutation);
-      if (hasContentMutation(result)) {
-        if (ctxHolder.scheduler) {
-          await ctxHolder.scheduler.triggerNow();
-        }
-      }
-      return result;
+  const options = withContentTypeRules(
+    {
+      gitPull: body.gitPull,
+      runUpdateCmd: true,
     },
-    ctxHolder.jobManager
+    ctxHolder.config
   );
+  let paths: string[] | null;
+  try {
+    // A path-level sync runs no update command; only git pull conflicts.
+    paths = await resolveReindexScope(
+      body.collection ? (collections[0] ?? null) : null,
+      body.paths,
+      { gitPull: body.gitPull }
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const separator = message.indexOf(": ");
+    const code = separator > 0 ? message.slice(0, separator) : "";
+    return errorResponse(
+      code === "INVALID_PATH" ? "INVALID_PATH" : "VALIDATION",
+      separator > 0 ? message.slice(separator + 2) : message
+    );
+  }
+
+  // Captured now: a queued pass runs after this request's context is gone.
+  const config = ctxHolder.config;
+  const runSync = async (
+    scopedPaths: string[] | null,
+    passOptions: { gitPull?: boolean; runUpdateCmd?: boolean }
+  ): Promise<SyncResult> => {
+    const collection = collections[0];
+    const result =
+      scopedPaths && collection
+        ? wrapCollectionSync(
+            await defaultSyncService.syncPaths(
+              collection,
+              store,
+              scopedPaths,
+              withContentTypeRules({}, config)
+            )
+          )
+        : await defaultSyncService.syncAll(
+            collections,
+            store,
+            withContentTypeRules({ ...passOptions }, config)
+          );
+    recordContentMutation(result, ctxHolder.markContentMutation);
+    if (hasContentMutation(result)) {
+      if (ctxHolder.scheduler) {
+        await ctxHolder.scheduler.triggerNow();
+      }
+    }
+    return result;
+  };
+
+  const manager = ctxHolder.jobManager;
+  if (manager) {
+    try {
+      const accepted = await manager.submitReindex({
+        type: "sync",
+        collection: body.collection ? (collections[0]?.name ?? null) : null,
+        paths,
+        // A whole sync over REST always runs the collection's update command.
+        options: { gitPull: body.gitPull ?? false, runUpdateCmd: true },
+        run: async (scope) => ({
+          kind: "sync",
+          value: await runSync(scope.paths, scope.options),
+        }),
+      });
+      return jsonResponse(
+        { jobId: accepted.jobId, status: accepted.status },
+        202
+      );
+    } catch (error) {
+      if (error instanceof JobError && error.code === "QUEUE_FULL") {
+        return errorResponse("QUEUE_FULL", error.message, 429);
+      }
+      if (error instanceof JobError) {
+        return errorResponse("CONFLICT", error.message, 409, {
+          activeJobId: manager.getActiveJob()?.id ?? "",
+        });
+      }
+      throw error;
+    }
+  }
+
+  // Standalone fallback (unit fixtures without a resident job manager).
+  const jobResult = startJob("sync", () => runSync(paths, options));
 
   if (!jobResult.ok) {
     return jobConflictResponse(jobResult);
@@ -1834,6 +1944,20 @@ export async function handleSync(
   return jsonResponse({ jobId: jobResult.jobId }, 202);
 }
 
+function wrapCollectionSync(
+  result: Awaited<ReturnType<typeof defaultSyncService.syncPaths>>
+): SyncResult {
+  return {
+    collections: [result],
+    totalDurationMs: result.durationMs,
+    totalFilesProcessed: result.filesProcessed,
+    totalFilesAdded: result.filesAdded,
+    totalFilesUpdated: result.filesUpdated,
+    totalFilesErrored: result.filesErrored,
+    totalFilesSkipped: result.filesSkipped,
+  };
+}
+
 /**
  * GET /api/docs
  * Query params: collection, limit (default 20), offset (default 0), tagsAll, tagsAny
@@ -4587,6 +4711,13 @@ export async function handleSearch(
   const parsedFilter = parseRestMetadataFilter(body.filter);
   if (!parsedFilter.ok) return parsedFilter.response;
   const filter = parsedFilter.filter;
+  const collectionScope = await parseRestCollectionScope(
+    body,
+    context?.config.collections ?? null,
+    store
+  );
+  if (!collectionScope.ok) return collectionScope.response;
+  const { collections } = collectionScope;
   let projectAffinity: ProjectAffinityScoringInput | undefined;
   try {
     projectAffinity = context
@@ -4606,6 +4737,7 @@ export async function handleSearch(
     limit: Math.min(body.limit || 10, 50),
     minScore: body.minScore,
     collection: body.collection,
+    collections,
     intent: body.intent?.trim() || undefined,
     exclude,
     tagsAll,
@@ -4785,6 +4917,13 @@ export async function handleQuery(
   const parsedFilter = parseRestMetadataFilter(body.filter);
   if (!parsedFilter.ok) return parsedFilter.response;
   const filter = parsedFilter.filter;
+  const collectionScope = await parseRestCollectionScope(
+    body,
+    ctx.config.collections,
+    ctx.store
+  );
+  if (!collectionScope.ok) return collectionScope.response;
+  const { collections } = collectionScope;
   let projectAffinity: ProjectAffinityScoringInput | undefined;
   try {
     projectAffinity = await resolveRemoteProjectAffinity(
@@ -4804,6 +4943,7 @@ export async function handleQuery(
     limit: Math.min(body.limit ?? 20, 50),
     minScore: body.minScore,
     collection: body.collection,
+    collections,
     lang: body.lang,
     intent: body.intent?.trim() || undefined,
     candidateLimit:

package/src/store/sqlite/adapter.ts

@@ -164,7 +164,7 @@ import {
 import { getSchemaVersion, migrations, runMigrations } from "../migrations";
 import { err, ok } from "../types";
 import { getStoredEmbeddingFingerprint } from "../vector/freshness";
-import { modelTableName } from "../vector/sqlite-vec";
+import { bindReadConnection, modelTableName } from "../vector/sqlite-vec";
 import {
   getVariantStatus,
   listVectorPartitions,
@@ -622,7 +622,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   private activeTransaction?: {
     token: { revoked: boolean };
     release: () => void;
+    db: Database;
   };
+  /** Set while a read-only caller runs; its reads use `readDb`. */
+  private readonly readScope = new AsyncLocalStorage<true>();
+  /** Second connection for read-only callers, opened on first use. */
+  private readDb: Database | null = null;
   private shutdownFenced = false;
   private shutdownDeadline?: number;
   private contextGeneration = 0;
@@ -741,6 +746,8 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
   async close(): Promise<void> {
     this.fenceForShutdown();
+    this.readDb?.close(false);
+    this.readDb = null;
     if (this.db) {
       try {
         // Current Bun finalizes all statements and releases Windows handles now.
@@ -791,7 +798,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     // JS cannot interleave this synchronous rollback with a running callback.
     // A callback suspended at await must never commit or use the store again.
     transaction.token.revoked = true;
-    this.db?.exec("ROLLBACK");
+    transaction.db.exec("ROLLBACK");
     transaction.release();
     this.activeTransaction = undefined;
   }
@@ -800,6 +807,47 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     return this.db !== null;
   }
 
+  /**
+   * Run a read-only caller on a second connection to the same index. All
+   * writes stay on the shared connection, so a write transaction there (a
+   * sync batch held open across file conversions) is never visible to these
+   * reads: WAL gives this connection the last committed state. An in-memory
+   * index has no second connection and reads on the shared one.
+   */
+  withReadConnection<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.dbPath === "" || this.dbPath === ":memory:") return fn();
+    return this.readScope.run(true, fn);
+  }
+
+  private openReadDb(main: Database): Database {
+    if (this.readDb) return this.readDb;
+    const db = new Database(this.dbPath);
+    try {
+      // A write here would wait out the busy timeout while the shared
+      // connection's batch, on the same event loop, cannot commit: fail fast.
+      db.exec("PRAGMA query_only = ON");
+      db.exec("PRAGMA foreign_keys = ON");
+      const busyTimeout =
+        main.query<{ timeout: number }, []>("PRAGMA busy_timeout").get()
+          ?.timeout ?? DEFAULT_BUSY_TIMEOUT_MS;
+      db.exec(`PRAGMA busy_timeout = ${busyTimeout}`);
+      if (this.ftsTokenizer.startsWith("snowball")) {
+        const snowball = loadFts5Snowball(db);
+        if (!snowball.loaded)
+          throw new Error(`Failed to load fts5-snowball: ${snowball.error}`);
+      }
+    } catch (cause) {
+      db.close(false);
+      throw cause;
+    }
+    bindReadConnection(db, main, async () => {
+      const release = await this.acquireTransactionWriter();
+      release();
+    });
+    this.readDb = db;
+    return db;
+  }
+
   /**
    * Run an async function within a single SQLite transaction.
    * Uses SAVEPOINT for nesting safety.
@@ -808,6 +856,9 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
    * explicit BEGIN/COMMIT to support async callbacks.
    */
   async withTransaction<T>(fn: () => Promise<T>): Promise<StoreResult<T>> {
+    // Writes always run on the shared connection, even from a read scope.
+    if (this.readScope.getStore())
+      return this.readScope.exit(() => this.withTransaction(fn));
     const parent = this.txContext.getStore();
     const connection = this.ensureOpen();
     const isOuter = parent === undefined;
@@ -826,7 +877,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       if (isOuter) {
         // IMMEDIATE reduces lock churn for bulk writes
         db.exec("BEGIN IMMEDIATE");
-        this.activeTransaction = { token, release: releaseWriter! };
+        this.activeTransaction = { token, release: releaseWriter!, db };
       } else {
         db.exec(`SAVEPOINT ${savepoint}`);
       }
@@ -872,6 +923,11 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  /** Write outside a transaction, on the shared connection even from a read scope. */
+  private async admitWrite<T>(write: (db: Database) => T): Promise<T> {
+    return this.readScope.exit(() => write(this.ensureOpen()));
+  }
+
   private async acquireTransactionWriter(): Promise<() => void> {
     const previous = this.txTail;
     let release!: () => void;
@@ -913,8 +969,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     if (!this.db) {
       throw new Error("Database not open");
     }
-    this.capShutdownBusyWait(this.db);
-    return this.db;
+    const db =
+      this.readScope.getStore() && !this.txContext.getStore()
+        ? this.openReadDb(this.db)
+        : this.db;
+    this.capShutdownBusyWait(db);
+    return db;
   }
 
   // ─────────────────────────────────────────────────────────────────────────
@@ -1507,14 +1567,16 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   async createRetrievalTrace(
     input: RetrievalTraceInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return createStoredTrace(this.ensureOpen(), input);
+    return this.admitWrite((db) => createStoredTrace(db, input));
   }
 
   async mergeRetrievalTraceEgressLineage(
     traceId: string,
     lineage: EgressLineage
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return mergeStoredTraceEgressLineage(this.ensureOpen(), traceId, lineage);
+    return this.admitWrite((db) =>
+      mergeStoredTraceEgressLineage(db, traceId, lineage)
+    );
   }
 
   async getRetrievalTrace(
@@ -1542,37 +1604,39 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     status: RetrievalTraceTerminalStatus,
     updatedAtMs: number
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return finalizeStoredTrace(this.ensureOpen(), traceId, status, updatedAtMs);
+    return this.admitWrite((db) =>
+      finalizeStoredTrace(db, traceId, status, updatedAtMs)
+    );
   }
 
   async appendRetrievalTraceRun(
     input: RetrievalTraceRunInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredTraceRun(this.ensureOpen(), input);
+    return this.admitWrite((db) => appendStoredTraceRun(db, input));
   }
 
   async appendRetrievalTraceEvent(
     input: RetrievalTraceEventInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredTraceEvent(this.ensureOpen(), input);
+    return this.admitWrite((db) => appendStoredTraceEvent(db, input));
   }
 
   async appendRetrievalTraceJudgment(
     input: RetrievalTraceJudgmentInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredTraceJudgment(this.ensureOpen(), input);
+    return this.admitWrite((db) => appendStoredTraceJudgment(db, input));
   }
 
   async appendRetrievalTraceExport(
     input: RetrievalTraceExportInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredTraceExport(this.ensureOpen(), input);
+    return this.admitWrite((db) => appendStoredTraceExport(db, input));
   }
 
   async appendRetrievalTraceExportManifest(
     input: RetrievalTraceExportManifestInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredTraceExportManifest(this.ensureOpen(), input);
+    return this.admitWrite((db) => appendStoredTraceExportManifest(db, input));
   }
 
   async getRetrievalTraceExportManifest(
@@ -1590,32 +1654,34 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   async getOrCreateRetrievalTraceRedactionSecret(): Promise<
     StoreResult<string>
   > {
-    return getOrCreateStoredTraceRedactionSecret(this.ensureOpen());
+    return this.admitWrite((db) => getOrCreateStoredTraceRedactionSecret(db));
   }
 
   async deleteRetrievalTrace(
     traceId: string
   ): Promise<StoreResult<RetrievalTraceDeleteCounts>> {
-    return deleteStoredTrace(this.ensureOpen(), traceId);
+    return this.admitWrite((db) => deleteStoredTrace(db, traceId));
   }
 
   async purgeRetrievalTraces(): Promise<
     StoreResult<RetrievalTracePurgeResult>
   > {
-    return purgeStoredTraces(this.ensureOpen());
+    return this.admitWrite((db) => purgeStoredTraces(db));
   }
 
   async enforceRetrievalTraceRetention(
     policy: RetrievalTraceRetentionPolicy,
     nowMs: number
   ): Promise<StoreResult<RetrievalTraceRetentionResult>> {
-    return enforceStoredTraceRetention(this.ensureOpen(), policy, nowMs);
+    return this.admitWrite((db) =>
+      enforceStoredTraceRetention(db, policy, nowMs)
+    );
   }
 
   async appendEgressAuditReceipt(
     receipt: EgressAuditReceiptInput
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredEgressAuditReceipt(this.ensureOpen(), receipt);
+    return this.admitWrite((db) => appendStoredEgressAuditReceipt(db, receipt));
   }
 
   async appendEgressAuditReceiptWithRetention(
@@ -1623,11 +1689,8 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     policy: EgressAuditRetentionPolicy,
     nowMs: number
   ): Promise<StoreResult<RetrievalTraceAppendResult>> {
-    return appendStoredEgressAuditReceiptWithRetention(
-      this.ensureOpen(),
-      receipt,
-      policy,
-      nowMs
+    return this.admitWrite((db) =>
+      appendStoredEgressAuditReceiptWithRetention(db, receipt, policy, nowMs)
     );
   }
 
@@ -1647,7 +1710,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   async deleteEgressAuditReceipt(
     auditId: string
   ): Promise<StoreResult<EgressAuditDeleteResult>> {
-    return deleteStoredEgressAuditReceipt(this.ensureOpen(), auditId);
+    return this.admitWrite((db) => deleteStoredEgressAuditReceipt(db, auditId));
   }
 
   async getEgressAuditStatus(): Promise<StoreResult<EgressAuditStatusResult>> {
@@ -1658,13 +1721,15 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     policy: EgressAuditRetentionPolicy,
     nowMs: number
   ): Promise<StoreResult<EgressAuditRetentionResult>> {
-    return enforceStoredEgressAuditRetention(this.ensureOpen(), policy, nowMs);
+    return this.admitWrite((db) =>
+      enforceStoredEgressAuditRetention(db, policy, nowMs)
+    );
   }
 
   async purgeEgressAuditReceipts(): Promise<
     StoreResult<EgressAuditPurgeResult>
   > {
-    return purgeStoredEgressAuditReceipts(this.ensureOpen());
+    return this.admitWrite((db) => purgeStoredEgressAuditReceipts(db));
   }
 
   getContextGeneration(): number {
@@ -2330,6 +2395,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     mirrorHashes: string[],
     options: {
       collection?: string;
+      collections?: string[];
       activeOnly?: boolean;
     } = {}
   ): Promise<StoreResult<DocumentRow[]>> {
@@ -2350,7 +2416,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
       // SQLite SQLITE_LIMIT_VARIABLE_NUMBER defaults to 999.
       // Reserve headroom for optional non-IN parameters.
-      const SQL_PARAM_LIMIT = options.collection ? 899 : 900;
+      const SQL_PARAM_LIMIT = 898;
 
       for (let i = 0; i < uniqueHashes.length; i += SQL_PARAM_LIMIT) {
         const batch = uniqueHashes.slice(i, i + SQL_PARAM_LIMIT);
@@ -2365,6 +2431,10 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           clauses.push("collection = ?");
           params.push(options.collection);
         }
+        if (options.collections !== undefined) {
+          clauses.push("collection IN (SELECT value FROM json_each(?))");
+          params.push(JSON.stringify(options.collections));
+        }
 
         const sql = `SELECT * FROM documents INDEXED BY idx_documents_mirror_hash WHERE ${clauses.join(" AND ")} ORDER BY id`;
         rows.push(...db.query<DbDocumentRow, string[]>(sql).all(...params));

package/src/store/sqlite/eligibility.ts

@@ -90,6 +90,10 @@ export function buildEligibleDocumentQuery(
     conditions.push("d.collection = ?");
     params.push(options.collection);
   }
+  if (options.collections !== undefined) {
+    conditions.push("d.collection IN (SELECT value FROM json_each(?))");
+    params.push(JSON.stringify(options.collections));
+  }
   if (options.relPathPrefix !== undefined) {
     conditions.push(
       "(COALESCE(NULLIF(d.record_source_path, ''), d.rel_path) = ? OR substr(COALESCE(NULLIF(d.record_source_path, ''), d.rel_path), 1, length(?) + 1) = ? || '/')"

package/src/store/types.ts

@@ -718,6 +718,11 @@ export interface DocumentEligibilityOptions {
   exclude?: string[];
   /** Filter by collection */
   collection?: string;
+  /**
+   * Filter to documents in ANY of these collections, before ranking and LIMIT.
+   * Undefined is unrestricted; an empty array denies all.
+   */
+  collections?: string[];
   /** Internal exact relative-path boundary applied before ranking and LIMIT. */
   relPathPrefix?: string;
   /** Filter to docs with ANY of these tags */
@@ -1945,6 +1950,8 @@ export interface StorePort {
     mirrorHashes: string[],
     options?: {
       collection?: string;
+      /** Keep only documents in ANY of these collections; empty denies all. */
+      collections?: string[];
       activeOnly?: boolean;
     }
   ): Promise<StoreResult<DocumentRow[]>>;