@gmickel/gno 2.12.2 → 2.14.0

package/spec/mcp.md

@@ -230,6 +230,50 @@ All write tools acquire an OS-backed advisory lock at `.mcp-write.lock` under th
 If another process holds the lock, tools return `LOCKED`.
 For async jobs, the lock is held for the full job duration.
 
+### Reindex Queue
+
+`gno_sync` and `gno_index` (and REST `POST /api/sync`) never reject a request
+because another job in the same server is running:
+
+- With no job running or waiting, the request starts at once (`status:
+"started"`), taking the write lock as above; another process holding it
+  returns `LOCKED`.
+- Otherwise it is queued (`status: "queued"`) and starts when the jobs ahead
+  of it finish, taking the write lock then. A queued job that cannot get the
+  lock fails with `LOCKED` in its job status.
+- A request joins a waiting job of the same tool and collection and returns
+  its `jobId`, so any number of requests cause at most one more pass:
+  - a request with `paths` joins any such job (its files are added to the
+    pass, or covered by a whole-collection pass);
+  - a whole-collection request joins a job that only has path requests
+    (widening it and setting its options) or a whole-collection job with the
+    same `gitPull` / `runUpdateCmd`. Whole-collection requests with different
+    options stay separate passes, and a path-only pass never runs `gitPull`
+    or an update command.
+  - a path-only job whose merged files pass 256 becomes a whole-collection
+    pass with no `gitPull` or update command.
+- A queued pass uses the configuration of the latest request that joined it;
+  `gno_index` resolves its embedding model when the pass starts, so a model
+  or preset change while it waits is picked up.
+- At most 64 distinct scopes wait at once; a new scope beyond that returns
+  `QUEUE_FULL`. Retry after the running job finishes.
+- The queue lives in the server process. Jobs still waiting when it stops are
+  failed at shutdown and unknown after a restart (`NOT_FOUND` from
+  `gno_job_status`); the index stays consistent.
+
+### Path-Level Reindex
+
+`paths` on `gno_sync` / `gno_index` reindexes only the listed files of one
+collection: each path is relative to the collection root or absolute inside
+it, and only those files are re-read. A listed file that no longer exists is
+marked inactive. `paths` requires `collection` and cannot be combined with
+`gitPull` or `runUpdateCmd`; an empty list, more than 256 paths, a
+directory, a path outside the root (including through a symlink) or a
+non-string entry is rejected before anything is queued (`INVALID_INPUT` /
+`INVALID_PATH`), and so is a path the collection's own `pattern`, `include`
+or `exclude` rules leave out. To reindex a directory or more than 256 files,
+reindex the whole collection.
+
 `gno_remember` is the one write tool whose adapter takes no lock of its own:
 the core memory service acquires the same `.mcp-write.lock` lease for every
 memory write, so an MCP remember and a CLI writer serialise on one lease. A
@@ -294,6 +338,13 @@ compatible collection policy. Policy denial returns HTTP 403 with stable
 `EGRESS_DENIED` data and a redacted evaluator audit. Write authorization remains
 an independent additional requirement.
 
+The check covers the request's collection scope: the collections it names, or
+every configured collection when it names none. One decision covers at most 64
+collections and one policy lineage at most 128. A scope over either bound is
+denied with reason `COLLECTION_LIMIT_EXCEEDED` through the same 403 response,
+whose audit names no collection; it is never an internal error. A request that
+names a few collections is evaluated normally however many are configured.
+
 The MCP tool and resource registry is paired with a callsite-level
 network-boundary inventory. A TypeScript AST scan covers shipped TS, TSX, JS,
 and JSX and recognizes direct, qualified, bracketed, imported, and aliased
@@ -367,7 +418,10 @@ Rules report `pass`, `fail`, `skip`, `unavailable`, or `inconclusive`; reports
 are `complete`, `partial`, `changed_during_audit`, or `failed`. A passing rule
 may carry `info` findings (`links.outside-index`: link targets that exist as
 files in the link workspace but are not indexed); only `warning` and `error`
-findings fail a rule. Link semantics match `gno audit` (spec/cli.md). Unavailable or
+findings fail a rule. Link semantics match `gno audit` (spec/cli.md),
+including the opt-in `links.collection-policy`, `links.external-url` and
+`links.path-layout` rules read from collection `audit` config; they add no
+tool inputs. Unavailable or
 changing evidence never appears healthy. Stable finding IDs are derived from
 rule, normalized subject/location, and evidence fingerprint. Responses are
 canonically ordered and bounded while retaining exact pre-truncation totals.
@@ -603,6 +657,19 @@ opaque remote hints. The server never stats, realpaths, discovers repositories,
 or infers its cwd from them; remote hints produce redacted zero-affinity
 metadata and no ranking change.
 
+`gno_search`, `gno_vsearch` and `gno_query` also accept an optional
+`collections` allowlist. The filter applies before every candidate limit (BM25,
+vector, fusion, graph expansion, hydration and rerank), so unlisted collections
+never take result slots. Names are trimmed, lowercased, de-duplicated and
+sorted; responses echo them as `meta.collections`, and `meta.collection` keeps
+its single-collection meaning. Passing both `collection` and `collections`, an
+empty list, a non-string member, or more than 256 names after normalization is
+a `VALIDATION` error; unconfigured names give `Collection not found: <name>` /
+`Collections not found: <a>, <b>`. Over HTTP the egress check covers exactly
+the listed collections, so the most restrictive listed collection decides.
+When the listed collections resolve different models for a role, that role uses
+the unscoped default. `gno_query_diagnose` does not accept `collections`.
+
 **Input Schema:**
 
 ```json
@@ -617,6 +684,11 @@ metadata and no ranking change.
       "type": "string",
       "description": "Optional collection name to filter results"
     },
+    "collections": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional allowlist: filter to any of these collection names (1-256); use instead of collection"
+    },
     "limit": {
       "type": "integer",
       "description": "Maximum number of results (1-100)",
@@ -738,6 +810,11 @@ Vector semantic search over indexed documents.
       "type": "string",
       "description": "Optional collection name to filter results"
     },
+    "collections": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional allowlist: filter to any of these collection names (1-256); use instead of collection"
+    },
     "limit": {
       "type": "integer",
       "description": "Maximum number of results (1-100)",
@@ -822,6 +899,11 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
       "type": "string",
       "description": "Optional collection name to filter results"
     },
+    "collections": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional allowlist: filter to any of these collection names (1-256); use instead of collection"
+    },
     "limit": {
       "type": "integer",
       "description": "Maximum number of results (1-100)",
@@ -2719,6 +2801,12 @@ Reindex one or all collections (write-enabled).
       "type": "boolean",
       "description": "Run updateCmd before indexing (default: false for MCP)",
       "default": false
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "maxItems": 256,
+      "description": "Reindex only these files of the collection (see Path-Level Reindex); requires collection"
     }
   }
 }
@@ -2726,6 +2814,9 @@ Reindex one or all collections (write-enabled).
 
 **Output Schema:** `gno://schemas/mcp-sync-result@1.0`
 
+`status` is `started` or `queued` (see [Reindex Queue](#reindex-queue));
+`paths` echoes the resolved collection-relative paths of a path-level sync.
+
 ---
 
 ### gno_embed
@@ -2818,6 +2909,12 @@ Full index: sync files + generate embeddings (write-enabled). Runs as background
       "type": "boolean",
       "description": "Run git pull before sync",
       "default": false
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "maxItems": 256,
+      "description": "Reindex only these files of the collection (see Path-Level Reindex); requires collection"
     }
   }
 }
@@ -2852,6 +2949,7 @@ Full index: sync files + generate embeddings (write-enabled). Runs as background
 
 - Requires `--enable-write` flag
 - Runs sync phase first, then embed phase
+- `status` is `started` or `queued` (see [Reindex Queue](#reindex-queue)); a path-level index adds `paths`
 - `runUpdateCmd` is always false for MCP (security)
 - Fails fast if embedding model not cached
 - Poll job status with `gno_job_status`
@@ -2902,6 +3000,11 @@ Get status of a background job.
 
 **Output Schema:** `gno://schemas/mcp-job-status@1.0`
 
+`status` is `queued` while a reindex job waits behind another job, then
+`running`, `completed` or `failed`. Reindex jobs also report `scope`: the
+collection (`null` for all) and the merged `paths` (`null` for the whole
+collection).
+
 ---
 
 ### gno_list_jobs
@@ -3062,8 +3165,9 @@ Resource errors use standard MCP error responses.
 - `HAS_REFERENCES` — Collection referenced by contexts
 - `INVALID_PATH` — Path violates safety rules
 - `PATH_NOT_FOUND` — Path does not exist
-- `JOB_CONFLICT` — Another job is already running
+- `JOB_CONFLICT` — Another job is already running (not returned by `gno_sync` / `gno_index`, which queue instead)
 - `LOCKED` — Another MCP process holds the write lock
+- `QUEUE_FULL` — Too many reindex scopes are already waiting; retry later
 - `CAPTURE_SYNC_FAILED` — `gno_capture` wrote the file but lexical sync failed
 - `WRITE_DISABLED` — Write tool dispatched while writes are disabled
 - `MEMORY_*` — Memory contract errors from `gno_recall` / `gno_remember`;
@@ -3106,6 +3210,7 @@ Clients should check schema version for compatibility.
 - No persistent state between tool calls
 - Each tool call is independent
 - Server handles concurrent tool calls sequentially; an accepted background job (`gno_sync`, `gno_embed`, `gno_index`) waits for the call in progress, then runs without holding that queue, so reads are not blocked while it runs
+- The retrieval tools (`gno_search`, `gno_vsearch`, `gno_query`, `gno_get`, `gno_multi_get`, `gno_status`, `gno_list_tags`, `gno_links`, `gno_backlinks`, `gno_similar`) read on a second connection, so they see only committed index data, never a sync batch still being written
 
 ---
 
@@ -3291,7 +3396,10 @@ Read tools:
   caller authentication/authorization, content class, and partial mode. It
   performs no action and returns the canonical decision/explanation contract.
   An explicit scope is a non-empty, duplicate-free list of at most 64 canonical
-  collection names; omitted scope means all configured collections.
+  collection names; omitted scope means all configured collections. Omitted
+  scope with more than 64 configured collections returns a denied decision
+  with reason `COLLECTION_LIMIT_EXCEEDED`; with more than 128 it returns a
+  `VALIDATION` error asking for named collections.
 - `gno_egress_audit_list`, `gno_egress_audit_show`, and
   `gno_egress_audit_status` expose only content-free local receipts.
 

package/spec/output-schemas/collection-list.schema.json

@@ -57,6 +57,34 @@
         "type": "string",
         "enum": ["none", "detected", "configured", "disabled", "unavailable"],
         "description": "CLI list only: how the link workspace was set"
+      },
+      "audit": {
+        "type": "object",
+        "description": "Opt-in report-only link and path rules for gno audit links. Absent when not configured.",
+        "additionalProperties": false,
+        "properties": {
+          "linkCollections": {
+            "type": "array",
+            "description": "Other collections this one may link to; its own is always allowed",
+            "maxItems": 256,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+            }
+          },
+          "externalUrls": {
+            "type": "string",
+            "enum": ["report", "ignore"],
+            "description": "report lists external URLs written in documents"
+          },
+          "paths": {
+            "type": "array",
+            "description": "Relative globs; each document path must match at least one",
+            "minItems": 1,
+            "maxItems": 64,
+            "items": { "type": "string", "maxLength": 1024 }
+          }
+        }
       }
     }
   }

package/spec/output-schemas/convert.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/convert@1.0",
+  "title": "GNO Convert Result",
+  "description": "Output of gno convert --json and SDK convertFile: the Markdown GNO would index for one file",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "source",
+    "converter",
+    "title",
+    "languageHint",
+    "markdown",
+    "mirrorHash",
+    "warnings"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "convert@1.0"
+    },
+    "source": {
+      "type": "object",
+      "required": ["path", "mime", "ext", "sizeBytes"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute path of the converted file"
+        },
+        "mime": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Detected MIME type"
+        },
+        "ext": {
+          "type": "string",
+          "description": "File extension, including the dot"
+        },
+        "sizeBytes": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "converter": {
+      "type": "object",
+      "required": ["id", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "title": {
+      "type": ["string", "null"],
+      "description": "Title from conversion, or null"
+    },
+    "languageHint": {
+      "type": ["string", "null"],
+      "description": "BCP-47 language hint from conversion, or null"
+    },
+    "markdown": {
+      "type": "string",
+      "description": "Canonical Markdown, identical to the mirror indexing stores"
+    },
+    "mirrorHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "SHA-256 hex of the canonical Markdown, as stored by indexing"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/ls.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/ls@1.0",
+  "title": "GNO Document Listing",
+  "description": "Output of gno ls --json and SDK list(): one page of active documents in URI order",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["documents", "meta"],
+  "properties": {
+    "documents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["docid", "uri", "source"],
+        "properties": {
+          "docid": { "type": "string", "pattern": "^#[a-f0-9]+$" },
+          "uri": { "type": "string", "pattern": "^gno://" },
+          "title": { "type": "string" },
+          "source": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["relPath", "mime", "ext"],
+            "properties": {
+              "relPath": { "type": "string" },
+              "mime": { "type": "string" },
+              "ext": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "returned", "offset"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Documents in scope that match the filter, before pagination"
+        },
+        "returned": { "type": "integer", "minimum": 0 },
+        "offset": { "type": "integer", "minimum": 0 },
+        "warnings": {
+          "type": "array",
+          "description": "Present only with a typed metadata filter when some documents could not be judged",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "message"],
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": ["METADATA_COVERAGE_INCOMPLETE"]
+              },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/mcp-job-status.schema.json

@@ -223,7 +223,7 @@
     "status": {
       "type": "string",
       "description": "Job status",
-      "enum": ["running", "completed", "failed"]
+      "enum": ["queued", "running", "completed", "failed"]
     },
     "startedAt": {
       "type": "string",
@@ -247,6 +247,22 @@
       "type": "string",
       "description": "Error message if failed"
     },
+    "scope": {
+      "type": "object",
+      "description": "Reindex jobs: what the job covers after merging requests",
+      "required": ["collection", "paths"],
+      "properties": {
+        "collection": {
+          "type": ["string", "null"],
+          "description": "Collection name, or null for all collections"
+        },
+        "paths": {
+          "type": ["array", "null"],
+          "description": "Collection-relative files, or null for the whole collection",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "serverInstanceId": {
       "type": "string",
       "description": "Server instance UUID",

package/spec/output-schemas/mcp-sync-result.schema.json

@@ -19,8 +19,15 @@
     },
     "status": {
       "type": "string",
-      "description": "Job status",
-      "enum": ["started"]
+      "description": "started: the job is running; queued: it waits behind another write job (requests for the same scope share one queued job)",
+      "enum": ["started", "queued"]
+    },
+    "paths": {
+      "type": "array",
+      "description": "Collection-relative files this sync reindexes; absent for a whole-collection sync",
+      "items": {
+        "type": "string"
+      }
     },
     "options": {
       "type": "object",

package/spec/output-schemas/search-results.schema.json

@@ -454,6 +454,13 @@
           "type": "string",
           "description": "Collection filter if applied"
         },
+        "collections": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "maxItems": 256,
+          "description": "Normalized collection allowlist if applied (sorted, lowercase)"
+        },
         "intent": {
           "type": "string",
           "description": "Disambiguating context used to steer retrieval without being searched directly"

package/src/cli/commands/index-cmd.ts

@@ -7,6 +7,7 @@
  * @module src/cli/commands/indexCmd
  */
 
+import { resolveReindexScope } from "../../core/reindex-paths";
 import {
   type CliWriteLeaseOptions,
   type WriteLeaseContention,
@@ -27,6 +28,7 @@ import {
   type SyncResult,
   withContentTypeRules,
 } from "../../ingestion";
+import { CliError } from "../errors";
 import { type EmbedResult, embedStageOutcome } from "./embed";
 import {
   formatSyncResultLines,
@@ -44,6 +46,8 @@ export interface IndexOptions extends CliWriteLeaseOptions {
   indexName?: string;
   /** Scope to single collection */
   collection?: string;
+  /** Reindex only these files of `collection` */
+  paths?: string[];
   /** Run ingestion only, skip embedding */
   noEmbed?: boolean;
   /** Download models if missing */
@@ -186,6 +190,18 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
     }
 
     const { store, collections, config } = initResult;
+    let paths: string[] | null;
+    try {
+      paths = await resolveReindexScope(
+        options.collection ? (collections[0] ?? null) : null,
+        options.paths,
+        { gitPull: options.gitPull }
+      );
+    } catch (e) {
+      await store.close();
+      const message = e instanceof Error ? e.message : String(e);
+      throw new CliError("VALIDATION", message.replace(/^[A-Z_]+: /, ""));
+    }
     const db = store.getRawDb();
     const embedSkipped = options.noEmbed ?? false;
 
@@ -202,18 +218,40 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
       markIndexStageRunning(db, "lexical", { collection: options.collection });
       let syncResult: SyncResult;
       try {
-        syncResult = await defaultSyncService.syncAll(
-          collections,
-          store,
-          withContentTypeRules(
-            {
-              gitPull: options.gitPull,
-              runUpdateCmd: true,
-              onSlowConversion: reportSlowConversion,
-            },
-            config
-          )
-        );
+        const collection = collections[0];
+        if (paths && collection) {
+          const pathResult = await defaultSyncService.syncPaths(
+            collection,
+            store,
+            paths,
+            withContentTypeRules(
+              { onSlowConversion: reportSlowConversion },
+              config
+            )
+          );
+          syncResult = {
+            collections: [pathResult],
+            totalDurationMs: pathResult.durationMs,
+            totalFilesProcessed: pathResult.filesProcessed,
+            totalFilesAdded: pathResult.filesAdded,
+            totalFilesUpdated: pathResult.filesUpdated,
+            totalFilesErrored: pathResult.filesErrored,
+            totalFilesSkipped: pathResult.filesSkipped,
+          };
+        } else {
+          syncResult = await defaultSyncService.syncAll(
+            collections,
+            store,
+            withContentTypeRules(
+              {
+                gitPull: options.gitPull,
+                runUpdateCmd: true,
+                onSlowConversion: reportSlowConversion,
+              },
+              config
+            )
+          );
+        }
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         markIndexStageFinished(db, "lexical", "failed");

package/src/cli/commands/ls.ts

@@ -5,9 +5,14 @@
  * @module src/cli/commands/ls
  */
 
+import type { MetadataPredicate } from "../../core/typed-metadata";
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 
 import { decorateUriForIndex } from "../../app/constants";
+import {
+  filterDocumentsByMetadata,
+  metadataCoverageWarnings,
+} from "../../pipeline/filters";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -23,6 +28,8 @@ export interface LsCommandOptions {
   limit?: number;
   /** Skip first N results */
   offset?: number;
+  /** Typed metadata predicate (same semantics as search --filter) */
+  filter?: MetadataPredicate;
   /** JSON output */
   json?: boolean;
   /** File protocol output */
@@ -48,6 +55,8 @@ export interface LsResponse {
     total: number;
     returned: number;
     offset: number;
+    /** Only with a filter, when documents could not be judged. */
+    warnings?: { code: string; message: string }[];
   };
 }
 
@@ -128,9 +137,16 @@ export async function ls(
       return { success: false, error: docs.error.message };
     }
 
-    // Filter active only, sort by URI
-    const allActive = docs.value
-      .filter((d) => d.active)
+    const active = docs.value.filter((d) => d.active);
+    const filtered = options.filter
+      ? filterDocumentsByMetadata(active, options.filter)
+      : undefined;
+    const warnings = filtered
+      ? metadataCoverageWarnings(filtered, "listing")
+      : undefined;
+
+    // Sort by URI
+    const allActive = (filtered?.matches ?? active)
       .map((d) => ({
         docid: d.docid,
         uri: d.uri,
@@ -160,6 +176,7 @@ export async function ls(
           total: allActive.length,
           returned: paged.length,
           offset,
+          ...(warnings ? { warnings } : {}),
         },
       },
     };

package/src/cli/commands/profile-apply.ts

@@ -267,7 +267,8 @@ export async function runProjectProfileApplyCommand(
       ];
       const validationFailure =
         applied.error.code === "PROFILE_INVALID" ||
-        applied.error.code === "RUNTIME_PATH_OVERLAP";
+        applied.error.code === "RUNTIME_PATH_OVERLAP" ||
+        applied.error.code === "WORKSPACE_ROOT_CONFLICT";
       return {
         result: failedApplyResult(
           validationFailure ? "invalid" : "failed",