@gmickel/gno 2.6.0 → 2.7.1

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

@@ -12,8 +12,17 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Error code matching exit code",
-          "enum": ["VALIDATION", "RUNTIME"]
+          "description": "CLI error code; each maps to one exit code (see spec/cli.md Error Output)",
+          "enum": [
+            "VALIDATION",
+            "RUNTIME",
+            "NOT_RUNNING",
+            "BUSY",
+            "AUDIT_FINDINGS",
+            "AUDIT_PARTIAL",
+            "CONTEXT_STALE",
+            "CONTEXT_CONFLICT"
+          ]
         },
         "message": {
           "type": "string",

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

@@ -62,7 +62,7 @@
       "properties": {
         "absPath": {
           "type": "string",
-          "description": "Absolute path to source file"
+          "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "relPath": {
           "type": "string",

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

@@ -7,7 +7,6 @@
   "required": [
     "docid",
     "uri",
-    "absPath",
     "collection",
     "relPath",
     "created",
@@ -34,7 +33,7 @@
     },
     "absPath": {
       "type": "string",
-      "description": "Absolute path to the created file"
+      "description": "Absolute path to the created file. Stdio callers only; omitted for HTTP MCP callers, which identify the file by uri + relPath."
     },
     "collection": {
       "type": "string",

package/spec/output-schemas/memory-remember.schema.json

@@ -34,13 +34,13 @@
     {
       "type": "object",
       "additionalProperties": false,
-      "required": ["outcome", "record", "absPath", "sync", "matching"],
+      "required": ["outcome", "record", "sync", "matching"],
       "properties": {
         "outcome": { "enum": ["added", "superseded"] },
         "record": { "$ref": "#/$defs/fact" },
         "absPath": {
           "type": "string",
-          "description": "Absolute path of the fact file that was written."
+          "description": "Absolute path of the fact file that was written. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "sync": { "$ref": "#/$defs/sync" },
         "matching": { "$ref": "#/$defs/matching" },

package/spec/output-schemas/multi-get.schema.json

@@ -40,7 +40,10 @@
             "type": "object",
             "required": ["relPath", "mime", "ext"],
             "properties": {
-              "absPath": { "type": "string" },
+              "absPath": {
+                "type": "string",
+                "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
+              },
               "relPath": { "type": "string" },
               "mime": { "type": "string" },
               "ext": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" }

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

@@ -99,14 +99,7 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": [
-          "docid",
-          "uri",
-          "title",
-          "collection",
-          "absPath",
-          "modifiedAt"
-        ],
+        "required": ["docid", "uri", "title", "collection", "modifiedAt"],
         "properties": {
           "docid": {
             "type": "string",
@@ -129,7 +122,7 @@
           "absPath": {
             "type": "string",
             "minLength": 1,
-            "description": "Absolute source path (collection root + relative path)"
+            "description": "Absolute source path (collection root + relative path). CLI and stdio MCP only; omitted for HTTP MCP callers."
           },
           "modifiedAt": {
             "type": "string",

package/spec/output-schemas/resident-status.schema.json

@@ -128,6 +128,28 @@
         "content": { "type": "integer", "minimum": 0 },
         "index": { "type": "integer", "minimum": 0 }
       }
+    },
+    "backgroundIssues": {
+      "description": "Present only while a background job is in trouble: failing passes, retries parked, a pass overrunning, or (client-side) a resident that did not answer its status request",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/backgroundIssue" }
+    }
+  },
+  "definitions": {
+    "backgroundIssue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["job", "state", "consecutiveFailures", "runningSeconds"],
+      "properties": {
+        "job": { "type": "string", "enum": ["embed", "resident"] },
+        "state": {
+          "type": "string",
+          "enum": ["failing", "parked", "overrunning", "unresponsive"]
+        },
+        "consecutiveFailures": { "type": "integer", "minimum": 0 },
+        "runningSeconds": { "type": ["integer", "null"], "minimum": 0 }
+      }
     }
   },
   "allOf": [

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

@@ -78,7 +78,7 @@
       "properties": {
         "absPath": {
           "type": "string",
-          "description": "Absolute path (included with --source or in MCP)"
+          "description": "Absolute source path. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "relPath": {
           "type": "string",

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

@@ -237,7 +237,7 @@
           "properties": {
             "absPath": {
               "type": "string",
-              "description": "Absolute filesystem path when resolvable from collection root + relPath. Default field on gno search --json (no --source flag). Omitted when unresolvable; consumers fall back to the URI tail for display and disable file-open."
+              "description": "Absolute filesystem path when resolvable from collection root + relPath. Default field on gno search --json (no --source flag). Omitted when unresolvable, and always omitted for remote REST and HTTP MCP callers (host paths reach only CLI, stdio MCP and same-host Web UI/REST callers); consumers fall back to uri + relPath for display and disable file-open."
             },
             "relPath": {
               "type": "string",

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

@@ -90,24 +90,18 @@
     },
     "configPath": {
       "type": "string",
-      "description": "Path to config file"
+      "description": "Path to config file. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
     },
     "dbPath": {
       "type": "string",
-      "description": "Path to SQLite database"
+      "description": "Path to SQLite database. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
     },
     "collections": {
       "type": "array",
       "description": "Collection statistics",
       "items": {
         "type": "object",
-        "required": [
-          "name",
-          "path",
-          "documentCount",
-          "chunkCount",
-          "embeddedCount"
-        ],
+        "required": ["name", "documentCount", "chunkCount", "embeddedCount"],
         "properties": {
           "name": {
             "type": "string",
@@ -115,7 +109,7 @@
           },
           "path": {
             "type": "string",
-            "description": "Collection root path"
+            "description": "Collection root path. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
           },
           "documentCount": {
             "type": "integer",
@@ -150,6 +144,104 @@
       "description": "Chunks awaiting embedding",
       "minimum": 0
     },
+    "vectorPartitions": {
+      "type": "array",
+      "description": "Vector partitions of the embedding model; omitted when none exist",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "model",
+          "dimensions",
+          "state",
+          "legacy",
+          "retrieval",
+          "droppable",
+          "owners",
+          "provenance",
+          "compatibleRuntimes",
+          "incompatibleRuntimes"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Partition id (drop with `gno vec drop <id-prefix>`)"
+          },
+          "model": {
+            "type": "string",
+            "description": "Embedding model URI"
+          },
+          "dimensions": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "state": {
+            "type": "string",
+            "enum": ["active", "shadow"],
+            "description": "active = activated for retrieval; shadow = incomplete or abandoned"
+          },
+          "legacy": {
+            "type": "boolean",
+            "description": "Pre-runtime-independent key, awaiting measured re-keying"
+          },
+          "retrieval": {
+            "type": "boolean",
+            "description": "Status counts use this partition: the activated runtime-independent partition every compatible runtime reads"
+          },
+          "droppable": {
+            "type": "boolean",
+            "description": "`gno vec drop` accepts it; never the partition this runtime's retrieval uses"
+          },
+          "owners": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Current chunks bound to this partition"
+          },
+          "provenance": {
+            "type": "string",
+            "description": "Runtime that built the partition, e.g. \"CUDA, Bun 1.4.2\""
+          },
+          "compatibleRuntimes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Runtimes measured (or recorded as the builder) to read this partition"
+          },
+          "incompatibleRuntimes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Runtimes measured incompatible; they read another partition or use lexical retrieval only"
+          }
+        }
+      }
+    },
+    "vectorRuntime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "state", "partition"],
+      "description": "This process's runtime, resolved by the same selection rule its queries use",
+      "properties": {
+        "label": {
+          "type": ["string", "null"],
+          "description": "Runtime recorded by this caller's last query or embed"
+        },
+        "state": {
+          "type": "string",
+          "enum": ["vectors", "unavailable", "unresolved"],
+          "description": "vectors: queries read `partition`; unavailable: lexical retrieval only; unresolved: no query or embed has resolved this caller yet"
+        },
+        "partition": {
+          "type": ["string", "null"]
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
     "recentErrors": {
       "type": "integer",
       "description": "Recent ingest errors in the last 24 hours",
@@ -497,13 +589,14 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["label", "path", "reason"],
+            "required": ["label", "reason"],
             "properties": {
               "label": {
                 "type": "string"
               },
               "path": {
-                "type": "string"
+                "type": "string",
+                "description": "Suggested folder path. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
               },
               "reason": {
                 "type": "string"
@@ -785,10 +878,11 @@
         },
         "cache": {
           "type": "object",
-          "required": ["path", "totalSizeBytes", "totalSizeLabel"],
+          "required": ["totalSizeBytes", "totalSizeLabel"],
           "properties": {
             "path": {
-              "type": "string"
+              "type": "string",
+              "description": "Model cache directory. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
             },
             "totalSizeBytes": {
               "type": "integer",
@@ -843,7 +937,6 @@
                   "role",
                   "uri",
                   "cached",
-                  "path",
                   "sizeBytes",
                   "statusLabel"
                 ],
@@ -859,7 +952,8 @@
                     "type": "boolean"
                   },
                   "path": {
-                    "type": ["string", "null"]
+                    "type": ["string", "null"],
+                    "description": "Cached model file, or null when not cached. Same-host callers only: omitted for a remote REST or HTTP MCP caller."
                   },
                   "sizeBytes": {
                     "type": ["integer", "null"],

package/src/cli/commands/ask.ts

@@ -81,6 +81,36 @@ export type AskCommandResult =
     }
   | { success: false; error: string };
 
+/**
+ * Give every document URI `?index=` on a named index, like search and
+ * Capsule results: results, citations and the answer-context selection.
+ */
+export function decorateAskUris(
+  result: AskResult,
+  indexName: string | undefined
+): AskResult {
+  const decorate = <T extends { uri: string }>(item: T): T => ({
+    ...item,
+    uri: decorateUriForIndex(item.uri, indexName),
+  });
+  const answerContext = result.meta.answerContext;
+  return {
+    ...result,
+    results: result.results.map(decorate),
+    citations: result.citations?.map(decorate),
+    meta: answerContext
+      ? {
+          ...result.meta,
+          answerContext: {
+            ...answerContext,
+            selected: answerContext.selected.map(decorate),
+            dropped: answerContext.dropped.map(decorate),
+          },
+        }
+      : result.meta,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -435,20 +465,9 @@ export async function ask(
         return { success: false, error: finalized.error.message };
       }
     }
-    // URIs carry `?index=` like search and Capsule results on a named index.
     return {
       success: true,
-      data: {
-        ...askResult,
-        results: askResult.results.map((result) => ({
-          ...result,
-          uri: decorateUriForIndex(result.uri, globals.index),
-        })),
-        citations: askResult.citations?.map((citation) => ({
-          ...citation,
-          uri: decorateUriForIndex(citation.uri, globals.index),
-        })),
-      },
+      data: decorateAskUris(askResult, globals.index),
       metadata: traceSession?.metadata(),
     };
   } catch (cause) {

package/src/cli/commands/doctor.ts

@@ -12,6 +12,10 @@ import { arch, platform } from "node:os";
 
 import type { Config } from "../../config/types";
 import type { ActivationStatus } from "../../core/activation-status";
+import type {
+  VectorPartitionStatus,
+  VectorRuntimeStatus,
+} from "../../store/vector/status";
 
 import { getIndexDbPath, getModelsCachePath } from "../../app/constants";
 import {
@@ -26,6 +30,7 @@ import {
   readFindingsRunStatus,
   resolveFindingsSchedule,
 } from "../../core/findings-run-state";
+import { formatVectorPartitionLines } from "../../core/vector-partition-status";
 import { getCodeChunkingStatus } from "../../ingestion/chunker";
 import { ModelCache } from "../../llm/cache";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
@@ -57,6 +62,9 @@ export interface DoctorCheck {
   details?: string[];
   /** Embedding fingerprint diagnostics for machine consumers */
   embeddingFingerprint?: EmbeddingFingerprintHealth;
+  /** Vector partitions; `retrieval` marks the one status and search use */
+  vectorPartitions?: VectorPartitionStatus[];
+  vectorRuntime?: VectorRuntimeStatus;
 }
 
 export interface EmbeddingFingerprintGroup {
@@ -261,16 +269,18 @@ function describeFingerprintGroup(group: EmbeddingFingerprintGroup): string {
 async function checkEmbeddingFingerprints(
   config: Config,
   indexName?: string
-): Promise<DoctorCheck> {
+): Promise<DoctorCheck[]> {
   const dbPath = getIndexDbPath(indexName);
   try {
     await stat(dbPath);
   } catch {
-    return {
-      name: "embedding-fingerprint",
-      status: "warn",
-      message: "Database not found. Run: gno init",
-    };
+    return [
+      {
+        name: "embedding-fingerprint",
+        status: "warn",
+        message: "Database not found. Run: gno init",
+      },
+    ];
   }
 
   const store = new SqliteAdapter();
@@ -283,12 +293,14 @@ async function checkEmbeddingFingerprints(
     config.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS
   );
   if (!openResult.ok) {
-    return {
-      name: "embedding-fingerprint",
-      status: "warn",
-      message: `Fingerprint health unavailable: ${openResult.error.message}`,
-      details: ["Run: gno doctor --json", "Then run: gno embed"],
-    };
+    return [
+      {
+        name: "embedding-fingerprint",
+        status: "warn",
+        message: `Fingerprint health unavailable: ${openResult.error.message}`,
+        details: ["Run: gno doctor --json", "Then run: gno embed"],
+      },
+    ];
   }
 
   try {
@@ -297,12 +309,14 @@ async function checkEmbeddingFingerprints(
     const currentFingerprint = getStoredEmbeddingFingerprint(db, model);
     const statusResult = await store.getStatus({ embedModel: model });
     if (!statusResult.ok) {
-      return {
-        name: "embedding-fingerprint",
-        status: "warn",
-        message: `Fingerprint health unavailable: ${statusResult.error.message}`,
-        details: ["Run: gno embed"],
-      };
+      return [
+        {
+          name: "embedding-fingerprint",
+          status: "warn",
+          message: `Fingerprint health unavailable: ${statusResult.error.message}`,
+          details: ["Run: gno embed"],
+        },
+      ];
     }
 
     const legacyChunks =
@@ -389,13 +403,33 @@ async function checkEmbeddingFingerprints(
       }
     }
 
-    return {
+    const fingerprintCheck: DoctorCheck = {
       name: "embedding-fingerprint",
       status: hasWarnings ? "warn" : "ok",
       message,
       details: details.length > 0 ? details : undefined,
       embeddingFingerprint: health,
     };
+    const partitions = statusResult.value.vectorPartitions;
+    if (!partitions) return [fingerprintCheck];
+    const runtime = statusResult.value.vectorRuntime;
+    const partitionLines = formatVectorPartitionLines(partitions, runtime);
+    const retrieval = partitions.find((p) => p.retrieval);
+    return [
+      fingerprintCheck,
+      {
+        name: "vector-partitions",
+        status: partitionLines.length ? "warn" : "ok",
+        message: retrieval
+          ? `this runtime's retrieval uses ${retrieval.id.slice(0, 12)} (${retrieval.state}, ${retrieval.owners} chunks, ${retrieval.provenance}); ${partitions.length - 1} other partition(s)`
+          : runtime?.state === "unavailable"
+            ? `this runtime uses lexical retrieval only: ${runtime.reason}`
+            : `this runtime has not resolved a partition yet; ${partitions.length} partition(s)`,
+        details: partitionLines.length ? partitionLines.slice(1) : undefined,
+        vectorPartitions: partitions,
+        vectorRuntime: runtime,
+      },
+    ];
   } finally {
     await store.close();
   }
@@ -669,7 +703,7 @@ export async function doctor(
   checks.push(checkCodeChunking());
 
   // Embedding fingerprint freshness
-  checks.push(await checkEmbeddingFingerprints(config, options.indexName));
+  checks.push(...(await checkEmbeddingFingerprints(config, options.indexName)));
 
   // Scheduled findings pass (daemon-only, opt-in)
   checks.push(await checkFindingsPass(config, options.indexName));

package/src/cli/commands/embed.ts

@@ -7,6 +7,9 @@
 
 import type { Database } from "bun:sqlite";
 
+// node:readline/promises is the platform line-input API; Bun has no equivalent
+import { createInterface } from "node:readline/promises";
+
 import type { EmbeddingPort } from "../../llm/types";
 import type { StoreResult } from "../../store/types";
 
@@ -77,8 +80,10 @@ export interface EmbedOptions extends CliWriteLeaseOptions {
   force?: boolean;
   /** Show what would be done without embedding */
   dryRun?: boolean;
-  /** Skip confirmation prompts */
+  /** Skip confirmation prompts (never confirms a separate vector partition) */
   yes?: boolean;
+  /** Explicitly confirm building a separate vector partition */
+  newPartition?: boolean;
   /** Output as JSON */
   json?: boolean;
   /** Verbose error logging */
@@ -450,6 +455,24 @@ async function initEmbedContext(
   return { ok: true, config, modelUri, store };
 }
 
+async function confirmSeparatePartition(message: string): Promise<boolean> {
+  process.stderr.write(`${message}\n`);
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    const answer = await prompt.question(
+      "Build the separate partition? [y/N] "
+    );
+    return /^(?:y|yes)$/i.test(answer.trim());
+  } catch {
+    return false;
+  } finally {
+    prompt.close();
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main Command
 // ─────────────────────────────────────────────────────────────────────────────
@@ -574,7 +597,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
         }
         vectorIndex = vectorResult.value;
 
-        const prepared = await prepareEmbeddingBacklog({
+        const backlogDeps = {
           statsPort: stats,
           embedPort,
           vectorIndex,
@@ -582,7 +605,22 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
           collection: options.collection,
           batchSize,
           force,
-        });
+          allowNewPartition: options.newPartition,
+        };
+        let prepared = await prepareEmbeddingBacklog(backlogDeps);
+        if (
+          !prepared.ok &&
+          prepared.error.code === "VECTOR_PARTITION_FORK" &&
+          !dryRun &&
+          !options.json &&
+          !options.yes &&
+          process.stdin.isTTY &&
+          (await confirmSeparatePartition(prepared.error.message))
+        )
+          prepared = await prepareEmbeddingBacklog({
+            ...backlogDeps,
+            allowNewPartition: true,
+          });
         if (!prepared.ok)
           return { success: false, error: prepared.error.message };
         if (prepared.value.variantStore) {

package/src/cli/commands/ls.ts

@@ -7,6 +7,7 @@
 
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 
+import { decorateUriForIndex } from "../../app/constants";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -145,7 +146,11 @@ export async function ls(
     // Apply offset and limit
     const offset = options.offset ?? 0;
     const limit = options.limit ?? 20;
-    const paged = allActive.slice(offset, offset + limit);
+    // Sorted on canonical URIs; the output URIs carry `?index=` like search.
+    const paged = allActive.slice(offset, offset + limit).map((doc) => ({
+      ...doc,
+      uri: decorateUriForIndex(doc.uri, options.indexName),
+    }));
 
     return {
       success: true,

package/src/cli/commands/query.ts

@@ -37,6 +37,7 @@ import {
   createVectorIndexPort,
   type VectorIndexPort,
 } from "../../store/vector";
+import { VECTOR_RUNTIME_INCOMPATIBLE } from "../../store/vector/variant-search";
 import { getGlobals } from "../program";
 import {
   createProgressRenderer,
@@ -517,6 +518,10 @@ export function formatQuery(
   }
   // Output explain to stderr if present (async but best-effort)
   outputExplainToStderr(result.data);
+  if (options.format !== "json")
+    for (const warning of result.data.meta.warnings ?? [])
+      if (warning.code === VECTOR_RUNTIME_INCOMPATIBLE)
+        process.stderr.write(`Warning: ${warning.message}\n`);
 
   // Use shared formatter for consistent output
   // Dynamic import to keep module loading fast