@gmickel/gno 2.10.0 → 2.11.0

package/src/cli/program.ts

@@ -2481,6 +2481,11 @@ function wireRetrievalCommands(program: Command): void {
         );
       }
 
+      // Terminal output is the raw content; the mark goes to stderr so
+      // piping the document stays byte-exact.
+      if (format === "terminal" && result.data.supersededBy) {
+        process.stderr.write(`Superseded by: ${result.data.supersededBy}\n`);
+      }
       process.stdout.write(
         `${formatGet(result, {
           lineNumbers: Boolean(cmdOpts.lineNumbers),
@@ -2870,23 +2875,59 @@ function wireManagementCommands(program: Command): void {
       });
     });
 
-  collectionCmd
-    .command("remove <name>")
-    .description("Remove a collection")
-    .action(async (name: string) => {
-      const { collectionRemove } = await import("./commands/collection");
-      await collectionRemove(name, { configPath: getGlobals().config });
-    });
+  addWriteLeaseFlags(
+    collectionCmd
+      .command("remove <name>")
+      .description("Remove a collection and its indexed documents")
+  ).action(async (name: string, cmdOpts: Record<string, unknown>) => {
+    const { collectionRemove } = await import("./commands/collection");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: getGlobals().index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      async () => {
+        await collectionRemove(name, {
+          configPath: getGlobals().config,
+          indexName: getGlobals().index,
+        });
+        return { success: true as const };
+      }
+    );
+    throwIfWriteLeaseBusy(result, false);
+  });
 
-  collectionCmd
-    .command("rename <old> <new>")
-    .description("Rename a collection")
-    .action(async (oldName: string, newName: string) => {
+  addWriteLeaseFlags(
+    collectionCmd
+      .command("rename <old> <new>")
+      .description("Rename a collection (run gno update afterwards)")
+  ).action(
+    async (
+      oldName: string,
+      newName: string,
+      cmdOpts: Record<string, unknown>
+    ) => {
       const { collectionRename } = await import("./commands/collection");
-      await collectionRename(oldName, newName, {
-        configPath: getGlobals().config,
-      });
-    });
+      const lease = parseWriteLeaseFlags(cmdOpts);
+      const result = await withCliWriteLease(
+        {
+          indexName: getGlobals().index,
+          lockWaitMs: lease.lockWaitMs,
+          noWait: lease.noWait,
+        },
+        async () => {
+          await collectionRename(oldName, newName, {
+            configPath: getGlobals().config,
+            indexName: getGlobals().index,
+          });
+          return { success: true as const };
+        }
+      );
+      throwIfWriteLeaseBusy(result, false);
+    }
+  );
 
   addWriteLeaseFlags(
     collectionCmd
@@ -3620,7 +3661,11 @@ function wireManagementCommands(program: Command): void {
         lockWaitMs: lease.lockWaitMs,
         noWait: lease.noWait,
       },
-      () => cleanup({ indexName: getGlobals().index })
+      () =>
+        cleanup({
+          configPath: getGlobals().config,
+          indexName: getGlobals().index,
+        })
     );
     throwIfWriteLeaseBusy(result, false);
 
@@ -4144,6 +4189,46 @@ function wireAgentsCommands(program: Command): void {
 // ─────────────────────────────────────────────────────────────────────────────
 
 function wireTagsCommands(program: Command): void {
+  program
+    .command("metadata")
+    .description(
+      "List typed metadata keys with their types, document counts and common values"
+    )
+    .option("-c, --collection <name>", "only documents in this collection")
+    .option(
+      "--values <n>",
+      "common values listed per key (1-100, default 10)",
+      (value) => Number(value)
+    )
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.metadataList, format);
+      const globals = getGlobals();
+      const { metadataList, formatMetadataList } =
+        await import("./commands/metadata");
+      const result = await metadataList({
+        configPath: globals.config,
+        indexName: globals.index,
+        collection: cmdOpts.collection as string | undefined,
+        values: cmdOpts.values as number | undefined,
+      });
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
+      }
+      await writeOutput(
+        formatMetadataList(result.data, {
+          json: format === "json",
+          md: format === "md",
+        }),
+        format
+      );
+    });
+
   const tagsCmd = program.command("tags").description("Manage document tags");
 
   // tags list

package/src/core/context-capsule-schema.ts

@@ -365,6 +365,8 @@ export const contextCapsuleEvidenceSchema = z
     ]),
     egressLineage: egressLineageSchema.optional(),
     record: recordEvidenceMetadataSchema.optional(),
+    /** Current successor when a newer memory fact superseded this one. */
+    supersededBy: contextCapsuleGnoUriSchema.optional(),
   })
   .strict()
   .superRefine((value, context) => {

package/src/core/context-capsule-verification.ts

@@ -51,6 +51,7 @@ export const contextCapsuleVerificationEvidenceSchema = z
       "chunk_corrupt",
       "source_missing",
       "mirror_missing",
+      "superseded",
     ]),
     rankingStatus: z.enum(["unchanged", "reranked", "unavailable"]),
     rankingCode: z.enum([
@@ -82,6 +83,7 @@ export const contextCapsuleVerificationEvidenceSchema = z
           "passage_stale",
           "chunk_missing",
           "chunk_corrupt",
+          "superseded",
         ].includes(value.contentCode) &&
         hashes.every((hash) => hash !== null)) ||
       (value.contentStatus === "missing" &&

package/src/core/context-compiler.ts

@@ -28,7 +28,7 @@ import type {
 import type { ContextConfiguredGuidance } from "./context-guidance";
 import type { MetadataPredicate } from "./typed-metadata";
 
-import { decorateUriForIndex } from "../app/constants";
+import { decorateResultUris, decorateUriForIndex } from "../app/constants";
 import { canonicalizeIndexName } from "../app/index-name";
 import { resolveTemporalRange } from "../pipeline/temporal";
 import { attachSearchResultPlannerMetadata } from "../pipeline/trace-metadata";
@@ -383,10 +383,7 @@ export const planContextEvidence = async <T, P>(
   const decoratedResults = responses
     .flatMap((response) => response.results)
     .map((result) => {
-      const decorated = {
-        ...result,
-        uri: decorateUriForIndex(result.uri, indexName),
-      };
+      const decorated = decorateResultUris(result, indexName);
       const metadata = result[SEARCH_RESULT_PLANNER_METADATA];
       return metadata
         ? attachSearchResultPlannerMetadata(decorated, metadata)

package/src/core/context-evidence.ts

@@ -502,6 +502,7 @@ export const materializeContextEvidenceCandidates = async (
           ...(projectRecordEvidenceMetadata(document)
             ? { record: projectRecordEvidenceMetadata(document) }
             : {}),
+          ...(result.supersededBy ? { supersededBy: result.supersededBy } : {}),
         },
       },
     };

package/src/core/context-verifier.ts

@@ -11,6 +11,7 @@ import type { ContextCapsuleVerification } from "./context-capsule-verification"
 
 import { decorateUriForIndex, deriveDocid } from "../app/constants";
 import { chunkMatchesCanonicalContent } from "../pipeline/chunk-lookup";
+import { ok } from "../store/types";
 import { type ContextCapsuleCreateOptions } from "./context-capsule";
 import { sha256Text } from "./context-capsule-validation";
 import {
@@ -35,6 +36,7 @@ type ContextVerifierStore = Pick<
   | "getCollections"
   | "getContexts"
   | "getDocumentsByDocids"
+  | "getSupersedingUris"
 > &
   Required<Pick<StorePort, "getContentBatch">>;
 
@@ -127,6 +129,8 @@ interface LoadedEvidence {
   chunksByHash: Map<string, ChunkRow[]>;
   documents: DocumentRow[];
   snapshot: ContextEvidenceSnapshot;
+  /** Current successor URI of evidence whose memory fact was superseded. */
+  successors: ReadonlyMap<string, string>;
 }
 
 const missingReceipt = (evidence: Evidence): EvidenceReceipt => ({
@@ -229,6 +233,8 @@ const verifyContent = (
     contentCode = "chunk_missing";
   } else if (!chunkValid) {
     contentCode = "chunk_corrupt";
+  } else if (loaded.successors.has(evidence.uri)) {
+    contentCode = "superseded";
   }
 
   return {
@@ -374,16 +380,23 @@ export const verifyContextCapsule = async (
       )
     ),
   ];
-  const [documentResult, contentResult, chunkResult, rankResult] =
+  const [documentResult, contentResult, chunkResult, rankResult, successors] =
     await Promise.all([
       deps.store.getDocumentsByDocids(docids, { activeOnly: true }),
       deps.store.getContentBatch(mirrorHashes),
       deps.store.getChunksBatch(mirrorHashes),
       deps.resolveCurrentRanks?.(structuredClone(capsule)).catch(() => null) ??
         Promise.resolve(null),
+      deps.store.getSupersedingUris?.([...evidenceUris]) ??
+        Promise.resolve(ok(new Map<string, string>())),
     ]);
   const loaded: LoadedEvidence = {
     snapshot: before,
+    successors: unwrapStore(
+      successors,
+      "document_load_failed",
+      "Failed to load supersession of verification evidence"
+    ),
     documents: unwrapStore(
       documentResult,
       "document_load_failed",

package/src/core/metadata-discovery.ts

@@ -0,0 +1,169 @@
+/**
+ * Typed metadata discovery: which keys the indexed documents carry, with
+ * their observed types, document counts and most common values, so a caller
+ * can write a `filter` predicate for metadata it has not seen.
+ *
+ * @module src/core/metadata-discovery
+ */
+
+export type MetadataValue = string | number | boolean;
+
+export interface MetadataKeySummary {
+  key: string;
+  /** Observed value types, e.g. `string`, `number`, `string[]`. */
+  types: string[];
+  /** Documents that carry the key. */
+  documents: number;
+  /** Most common values (array members count individually), count desc. */
+  values: { value: MetadataValue; documents: number }[];
+  /** True when more distinct values exist than `values` lists. */
+  valuesTruncated: boolean;
+}
+
+export interface MetadataSummary {
+  collection: string | null;
+  /** Active documents in scope, and how many carry typed metadata. */
+  documents: number;
+  documentsWithMetadata: number;
+  keys: MetadataKeySummary[];
+}
+
+export const DEFAULT_METADATA_VALUE_LIMIT = 10;
+export const MAX_METADATA_VALUE_LIMIT = 100;
+
+const typeOf = (value: unknown): string | null => {
+  if (Array.isArray(value)) {
+    const member = value.length > 0 ? typeOf(value[0]) : "string";
+    return member ? `${member}[]` : null;
+  }
+  return typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+    ? typeof value
+    : null;
+};
+
+/**
+ * Summarize stored typed metadata JSON. Keys sort by document count then
+ * name; values by document count then their JSON text, so output is stable.
+ */
+export function summarizeTypedMetadata(
+  input: {
+    collection: string | null;
+    documents: number;
+    metadata: string[];
+  },
+  valueLimit = DEFAULT_METADATA_VALUE_LIMIT
+): MetadataSummary {
+  const keys = new Map<
+    string,
+    { types: Set<string>; documents: number; values: Map<string, number> }
+  >();
+  let documentsWithMetadata = 0;
+  for (const json of input.metadata) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      continue;
+    const entries = Object.entries(parsed);
+    if (entries.length === 0) continue;
+    documentsWithMetadata += 1;
+    for (const [key, value] of entries) {
+      const type = typeOf(value);
+      if (!type) continue;
+      const summary = keys.get(key) ?? {
+        types: new Set<string>(),
+        documents: 0,
+        values: new Map<string, number>(),
+      };
+      summary.types.add(type);
+      summary.documents += 1;
+      const members = new Set(
+        (Array.isArray(value) ? value : [value]).map((member) =>
+          JSON.stringify(member)
+        )
+      );
+      for (const member of members)
+        summary.values.set(member, (summary.values.get(member) ?? 0) + 1);
+      keys.set(key, summary);
+    }
+  }
+  return {
+    collection: input.collection,
+    documents: input.documents,
+    documentsWithMetadata,
+    keys: [...keys.entries()]
+      .map(([key, summary]) => {
+        const values = [...summary.values.entries()].sort(
+          ([leftText, left], [rightText, right]) =>
+            right - left || (leftText < rightText ? -1 : 1)
+        );
+        return {
+          key,
+          types: [...summary.types].sort(),
+          documents: summary.documents,
+          values: values.slice(0, valueLimit).map(([text, documents]) => ({
+            value: JSON.parse(text) as MetadataValue,
+            documents,
+          })),
+          valuesTruncated: values.length > valueLimit,
+        };
+      })
+      .sort(
+        (left, right) =>
+          right.documents - left.documents || (left.key < right.key ? -1 : 1)
+      ),
+  };
+}
+
+/** Shared read for every surface; `values` caps listed values per key. */
+export async function readMetadataSummary(
+  store: {
+    getTypedMetadataDocuments(options?: {
+      collection?: string;
+    }): Promise<
+      | { ok: true; value: { documents: number; metadata: string[] } }
+      | { ok: false; error: { message: string } }
+    >;
+  },
+  options: { collection?: string; values?: number } = {}
+): Promise<MetadataSummary> {
+  const values = options.values ?? DEFAULT_METADATA_VALUE_LIMIT;
+  if (
+    !Number.isInteger(values) ||
+    values < 1 ||
+    values > MAX_METADATA_VALUE_LIMIT
+  )
+    throw new RangeError(
+      `values must be an integer from 1 to ${MAX_METADATA_VALUE_LIMIT}`
+    );
+  const result = await store.getTypedMetadataDocuments({
+    collection: options.collection,
+  });
+  if (!result.ok) throw new Error(result.error.message);
+  return summarizeTypedMetadata(
+    { collection: options.collection ?? null, ...result.value },
+    values
+  );
+}
+
+/** Plain-text rendering shared by the CLI terminal output and MCP text. */
+export function formatMetadataSummary(summary: MetadataSummary): string {
+  const scope = summary.collection ? ` in ${summary.collection}` : "";
+  const header = `${summary.documentsWithMetadata} of ${summary.documents} documents${scope} carry typed metadata`;
+  if (summary.keys.length === 0) return `${header}.`;
+  const lines = [`${header}:`, ""];
+  for (const key of summary.keys) {
+    const values = key.values
+      .map((item) => `${JSON.stringify(item.value)} (${item.documents})`)
+      .join(", ");
+    lines.push(
+      `${key.key} [${key.types.join(", ")}] ${key.documents} ${key.documents === 1 ? "doc" : "docs"}${values ? `: ${values}${key.valuesTruncated ? ", ..." : ""}` : ""}`
+    );
+  }
+  return lines.join("\n");
+}

package/src/ingestion/sync.ts

@@ -1,5 +1,6 @@
 // node:fs/promises for realpath/stat (no Bun equivalent for canonical paths or file stats)
-import { realpath, stat } from "node:fs/promises";
+// opendir proves a root can be listed; Bun has no directory-handle API.
+import { opendir, realpath, stat } from "node:fs/promises";
 /**
  * Sync service - orchestrates file ingestion.
  * Walks collections, converts files, chunks content, updates store.
@@ -389,6 +390,22 @@ class Semaphore {
   }
 }
 
+/** Null when the collection root can be listed; otherwise why it cannot. */
+async function unavailableRootMessage(root: string): Promise<string | null> {
+  try {
+    const directory = await opendir(root);
+    try {
+      // The open is lazy; the first read is what needs list permission.
+      await directory.read();
+    } finally {
+      await directory.close();
+    }
+    return null;
+  } catch (cause) {
+    return `Collection root could not be resolved (${cause instanceof Error ? cause.message : String(cause)}); indexed documents were kept`;
+  }
+}
+
 function summarizePathResults(
   collection: string,
   results: FileSyncResult[],
@@ -1174,6 +1191,7 @@ export class SyncService {
     const directoryAvailability = memoizeDirectoryAvailability(
       this.directoryAvailabilityFactory(availabilityMode)
     );
+    let rootUnavailable: string | null = null;
 
     for (const relPath of relPaths) {
       const recordDocumentsResult = await store.listRecordDocuments(
@@ -1285,6 +1303,19 @@ export class SyncService {
           });
           continue;
         }
+        // A file is only proven deleted while its collection root can be
+        // listed. Checked per absence: the root can vanish mid-batch.
+        const rootError = await unavailableRootMessage(collection.path);
+        if (rootError) {
+          rootUnavailable = rootError;
+          results.push({
+            relPath,
+            status: "error",
+            errorCode: "SOURCE_AVAILABILITY_UNKNOWN",
+            errorMessage: rootError,
+          });
+          continue;
+        }
         const inactive = await this.inactivateOneAbsentSource(
           collection,
           store,
@@ -1436,6 +1467,23 @@ export class SyncService {
       syncOptions.projectTypedEdges === false
         ? []
         : await this.projectTypedEdges(store, syncOptions, projectionSourceIds);
+    if (rootUnavailable) {
+      // Collection-level, as a full sync reports it, so status, summaries and
+      // the watcher's error path all carry the root and the original error.
+      errors.unshift({
+        relPath: "",
+        code: "SOURCE_AVAILABILITY_UNKNOWN",
+        message: rootUnavailable,
+      });
+      await store
+        .recordError({
+          collection: collection.name,
+          relPath: "",
+          code: "SOURCE_AVAILABILITY_UNKNOWN",
+          message: rootUnavailable,
+        })
+        .catch(() => undefined);
+    }
     return {
       ...summarizePathResults(
         collection.name,

package/src/ingestion/walker.ts

@@ -289,9 +289,17 @@ export class FileWalker implements WalkerPort {
     let rootReal: string;
     try {
       rootReal = await realpath(rootAbs);
-    } catch {
-      // Root doesn't exist
-      return { entries: [], skipped: [] };
+    } catch (error) {
+      // An unmounted drive or offline sync folder proves nothing about its
+      // files, so the root is an unproven prefix, never an empty listing.
+      skipped.push({
+        absPath: rootAbs,
+        relPath: "",
+        reason: "SOURCE_AVAILABILITY_UNKNOWN",
+        unprovenPrefix: true,
+        message: `Collection root could not be resolved (${error instanceof Error ? error.message : String(error)}); indexed documents were kept`,
+      });
+      return { entries, skipped };
     }
 
     const matches = new Set<string>();

package/src/mcp/http-egress.ts

@@ -48,6 +48,7 @@ export const MCP_HTTP_EGRESS_TOOLS = {
   gno_job_status: "metadata",
   gno_links: "metadata",
   gno_list_jobs: "metadata",
+  gno_list_metadata: "metadata",
   gno_list_tags: "metadata",
   gno_move_note: "metadata",
   gno_multi_get: "source",

package/src/mcp/tool-descriptions-core.ts

@@ -18,9 +18,9 @@ import { type McpToolProfile, mcpToolProfileAllowlist } from "./tool-profile";
 
 export const MCP_CORE_TOOL_DESCRIPTIONS: Readonly<Record<string, string>> = {
   gno_query:
-    "Call first for a question about the indexed documents when the answer may be worded differently from the question. Runs hybrid retrieval: BM25 plus vector search, fused, with bounded one-hop graph expansion and optional query expansion and reranking. Returns ranked results, each with uri, docid, score, snippet, and usually a line anchor to read next with gno_get fromLine/lineCount; meta reports the mode actually used (bm25_only when vectors are unavailable) and whether expansion and reranking ran. Set fast=true for a quick lookup, thorough=true when recall matters, and intent to disambiguate a short term. A context field on a result is configured guidance; cite the source lines.",
+    "Call first for a question about the indexed documents when the answer may be worded differently from the question. Runs hybrid retrieval: BM25 plus vector search, fused, with bounded one-hop graph expansion and optional query expansion and reranking. Returns ranked results, each with uri, docid, score, snippet, and usually a line anchor to read next with gno_get fromLine/lineCount; meta reports the mode actually used (bm25_only when vectors are unavailable) and whether expansion and reranking ran. Start with fast=true (no expansion or reranking, typically under a second on a warm server); when that misses, call again without fast to add expansion and reranking; set thorough=true when recall matters and intent to disambiguate a short term. A context field on a result is configured guidance; cite the source lines.",
   gno_search:
-    "Call when you know the exact words: a name, identifier, filename, error message, or quoted phrase. Runs BM25 keyword matching only, so it needs no model and answers fast. Returns ranked results with uri, docid, score, snippet, and a line anchor when available; the match sits at that line, so read it with gno_get fromLine/lineCount. Call gno_query when the wording is uncertain.",
+    "Call when you know the exact words: a name, identifier, filename, error message, or quoted phrase. Runs BM25 keyword matching only, so it needs no model and answers fast. Returns ranked results with uri, docid, score, snippet, and a line anchor when available; the match sits at that line, so read it with gno_get fromLine/lineCount. For a question asked in words, call gno_query with fast=true instead.",
   gno_get:
     "Call to read one document a result named: pass its gno:// URI, #docid, or collection/path as ref. With fromLine and lineCount it returns only that range; start from the result's line anchor with a small count before fetching the whole file. Returns the content with line numbers plus uri, docid, title, totalLines, returnedLines, and the source path and modifiedAt.",
   gno_multi_get:

package/src/mcp/tool-profile.ts

@@ -17,6 +17,8 @@ import type {
  * @module src/mcp/tool-profile
  */
 
+import { z } from "zod";
+
 import { withInferenceScope } from "../llm/inference-scope";
 
 export const MCP_TOOL_PROFILES = ["core", "full"] as const;
@@ -129,6 +131,19 @@ export function createProfileToolRegistrar(
             : (cb as ToolCallback<StandardSchemaWithJSON>)(args[0], request)
       );
     };
-    server.registerTool(name, config, wrapped as unknown as typeof cb);
+    server.registerTool(
+      name,
+      { ...config, inputSchema: rejectUnknownKeys(config.inputSchema) },
+      wrapped as unknown as typeof cb
+    );
   };
 }
+
+/**
+ * Unknown argument keys fail validation with the key named instead of being
+ * dropped: a misspelled scope or receipt key must not silently widen a read
+ * or skip a write fence.
+ */
+function rejectUnknownKeys<T>(schema: T): T {
+  return (schema instanceof z.ZodObject ? schema.strict() : schema) as T;
+}

package/src/mcp/tools/get.ts

@@ -25,6 +25,7 @@ import {
   evidenceFromExactDocument,
   RetrievalTraceSession,
 } from "../../core/retrieval-trace-session";
+import { supersedingUri } from "../../pipeline/result-context";
 import { openScopedIndexStore } from "../../store/sqlite/scoped-index";
 import { runTool, type ToolResult } from "./index";
 
@@ -59,6 +60,8 @@ interface GetResponse {
     mirrorHash?: string;
   };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
   capabilities: DocumentCapabilities;
 }
 
@@ -104,6 +107,9 @@ function formatGetResponse(data: GetResponse): string {
   if (data.title) {
     lines.push(`Title: ${data.title}`);
   }
+  if (data.supersededBy) {
+    lines.push(`Superseded by: ${data.supersededBy}`);
+  }
   lines.push(`Lines: ${data.totalLines}`);
   if (data.source.absPath) {
     lines.push(`Path: ${data.source.absPath}`);
@@ -226,7 +232,11 @@ export function handleGet(
           }
         }
 
+        const successor = await supersedingUri(scoped.store, doc.uri);
         const response: GetResponse = {
+          ...(successor
+            ? { supersededBy: decorateUriForIndex(successor, scoped.indexName) }
+            : {}),
           docid: doc.docid,
           uri: decorateUriForIndex(doc.uri, scoped.indexName),
           title: doc.title ?? undefined,