@gmickel/gno 2.10.1 → 2.11.0

package/src/cli/commands/ask-format.ts

@@ -146,6 +146,9 @@ const formatTerminal = (data: AskResult, opts: FormatOptions = {}): string => {
           ? ""
           : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
       lines.push(`  [${index + 1}] ${citation.uri}${range}`);
+      if (citation.supersededBy) {
+        lines.push(`      Superseded by: ${citation.supersededBy}`);
+      }
     }
     lines.push("");
   }
@@ -158,12 +161,18 @@ const formatTerminal = (data: AskResult, opts: FormatOptions = {}): string => {
         `  [${evidence.docid}] ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}`
       );
       if (evidence.title) lines.push(`    ${evidence.title}`);
+      if (evidence.supersededBy) {
+        lines.push(`    Superseded by: ${evidence.supersededBy}`);
+      }
     }
   } else if (showAllSources && data.results.length > 0) {
     lines.push(hasAnswer ? "All Retrieved Sources:" : "Sources:");
     for (const result of data.results) {
       lines.push(`  [${result.docid}] ${result.uri}`);
       if (result.title) lines.push(`    ${result.title}`);
+      if (result.supersededBy) {
+        lines.push(`    Superseded by: ${result.supersededBy}`);
+      }
     }
   } else if (hasAnswer && data.results.length > 0) {
     const citedCount = data.citations?.length ?? 0;
@@ -196,7 +205,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
         citation.startLine === undefined
           ? ""
           : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
-      lines.push(`**[${index + 1}]** \`${citation.uri}${range}\``);
+      lines.push(
+        `**[${index + 1}]** \`${citation.uri}${range}\`${citation.supersededBy ? ` (superseded by \`${citation.supersededBy}\`)` : ""}`
+      );
     }
     lines.push("");
   }
@@ -216,6 +227,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
           `${index + 1}. **${evidence.title || evidence.uri}**`,
           `   - URI: \`${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}\``
         );
+        if (evidence.supersededBy) {
+          lines.push(`   - Superseded by: \`${evidence.supersededBy}\``);
+        }
       }
     } else {
       for (const [index, result] of data.results.entries()) {
@@ -223,6 +237,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
           `${index + 1}. **${result.title || result.source.relPath}**`
         );
         lines.push(`   - URI: \`${result.uri}\``);
+        if (result.supersededBy) {
+          lines.push(`   - Superseded by: \`${result.supersededBy}\``);
+        }
         lines.push(`   - Score: ${result.score.toFixed(2)}`);
       }
       if (data.results.length === 0) lines.push("*No relevant sources found.*");

package/src/cli/commands/ask.ts

@@ -15,7 +15,7 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
-import { decorateUriForIndex } from "../../app/constants";
+import { decorateResultUris } from "../../app/constants";
 import { buildVerifiedAsk } from "../../app/verified-ask";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
@@ -89,10 +89,9 @@ 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 decorate = <T extends { uri: string; supersededBy?: string }>(
+    item: T
+  ): T => decorateResultUris(item, indexName);
   const answerContext = result.meta.answerContext;
   return {
     ...result,

package/src/cli/commands/daemon.ts

@@ -99,7 +99,11 @@ export function logSessionAutomationResult(
 }
 
 function formatCollectionSyncSummary(result: CollectionSyncResult): string {
-  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
+  const collectionErrors = result.errors
+    .filter((error) => error.relPath === "")
+    .map((error) => `; [${error.code}] ${error.message}`)
+    .join("");
+  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors${collectionErrors}`;
 }
 
 export const authorizeDaemonStatus = async (

package/src/cli/commands/get.ts

@@ -29,6 +29,7 @@ import {
   evidenceFromExactDocument,
   RetrievalTraceSession as TraceSession,
 } from "../../core/retrieval-trace-session";
+import { supersedingUri } from "../../pipeline/result-context";
 import { parseRef } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -90,6 +91,8 @@ export interface GetResponse {
     mirrorHash?: string;
   };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
   capabilities: DocumentCapabilities;
 }
 
@@ -269,7 +272,7 @@ async function fetchDocument(
     return { success: false, error: "Mirror content unavailable" };
   }
 
-  return buildResponse({
+  const response = buildResponse({
     doc,
     fullContent: contentResult.value,
     parsed,
@@ -277,6 +280,10 @@ async function fetchDocument(
     config,
     indexName,
   });
+  const successor = await supersedingUri(store, doc.uri);
+  if (response.success && successor)
+    response.data.supersededBy = decorateUriForIndex(successor, indexName);
+  return response;
 }
 
 interface BuildResponseContext {
@@ -467,6 +474,9 @@ function formatMarkdown(data: GetResponse, options: GetCommandOptions): string {
   lines.push("");
   lines.push(`- **URI**: \`${data.uri}\``);
   lines.push(`- **DocID**: \`${data.docid}\``);
+  if (data.supersededBy) {
+    lines.push(`- **Superseded by**: \`${data.supersededBy}\``);
+  }
   if (data.returnedLines) {
     lines.push(
       `- **Lines**: ${data.returnedLines.start}-${data.returnedLines.end} of ${data.totalLines}`

package/src/cli/commands/metadata.ts

@@ -0,0 +1,79 @@
+/**
+ * gno metadata - list the typed metadata keys indexed documents carry.
+ *
+ * @module src/cli/commands/metadata
+ */
+
+import {
+  formatMetadataSummary,
+  type MetadataSummary,
+  readMetadataSummary,
+} from "../../core/metadata-discovery";
+import { initStore } from "./shared";
+
+export interface MetadataListOptions {
+  configPath?: string;
+  indexName?: string;
+  collection?: string;
+  values?: number;
+}
+
+export type MetadataListResult =
+  | { success: true; data: MetadataSummary }
+  | { success: false; error: string; isValidation?: boolean };
+
+export async function metadataList(
+  options: MetadataListOptions = {}
+): Promise<MetadataListResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+  });
+  if (!initResult.ok) return { success: false, error: initResult.error };
+  const { store } = initResult;
+  try {
+    return {
+      success: true,
+      data: await readMetadataSummary(store, {
+        collection: options.collection,
+        values: options.values,
+      }),
+    };
+  } catch (cause) {
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : String(cause),
+      isValidation: cause instanceof RangeError,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatMetadataList(
+  data: MetadataSummary,
+  options: { json?: boolean; md?: boolean }
+): string {
+  if (options.json) return JSON.stringify(data, null, 2);
+  if (!options.md) return formatMetadataSummary(data);
+  const lines = [
+    "# Typed metadata",
+    "",
+    `*${data.documentsWithMetadata} of ${data.documents} documents${data.collection ? ` in \`${data.collection}\`` : ""}*`,
+  ];
+  if (data.keys.length === 0) return lines.join("\n");
+  lines.push(
+    "",
+    "| Key | Types | Documents | Common values |",
+    "|---|---|---|---|"
+  );
+  for (const key of data.keys) {
+    const values = key.values
+      .map((item) => `\`${JSON.stringify(item.value)}\` (${item.documents})`)
+      .join(", ");
+    lines.push(
+      `| \`${key.key}\` | ${key.types.join(", ")} | ${key.documents} | ${values}${key.valuesTruncated ? ", ..." : ""} |`
+    );
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/multi-get.ts

@@ -21,6 +21,7 @@ import {
   projectRecordEvidenceMetadata,
   type RecordEvidenceMetadata,
 } from "../../core/record-metadata";
+import { supersedingUri } from "../../pipeline/result-context";
 import { isGlobPattern, parseRef, splitRefs } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -58,6 +59,8 @@ export interface MultiGetDocument {
   totalLines?: number;
   source: { absPath?: string; relPath: string; mime: string; ext: string };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
 }
 
 export interface SkippedDoc {
@@ -236,7 +239,11 @@ async function fetchSingleDocument(
   const coll = ctx.config.collections.find((c) => c.name === doc.collection);
 
   const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+  const successor = await supersedingUri(ctx.store, doc.uri);
   ctx.documents.push({
+    ...(successor
+      ? { supersededBy: decorateUriForIndex(successor, ctx.indexName) }
+      : {}),
     docid: doc.docid,
     uri: decorateUriForIndex(doc.uri, ctx.indexName),
     title: doc.title ?? undefined,
@@ -422,6 +429,9 @@ function formatMarkdown(
   for (const doc of data.documents) {
     lines.push(`## ${doc.title || doc.source.relPath}`);
     lines.push(`- **URI**: \`${doc.uri}\``);
+    if (doc.supersededBy) {
+      lines.push(`- **Superseded by**: \`${doc.supersededBy}\``);
+    }
     if (doc.truncated) {
       lines.push(`- **Truncated**: yes (max ${data.meta.maxBytes} bytes)`);
     }
@@ -450,6 +460,9 @@ function formatTerminal(
 
   for (const doc of data.documents) {
     lines.push(`=== ${doc.uri} ===`);
+    if (doc.supersededBy) {
+      lines.push(`Superseded by: ${doc.supersededBy}`);
+    }
     lines.push(formatContent(doc.content, Boolean(options.lineNumbers)));
     lines.push("");
   }

package/src/cli/commands/shared.ts

@@ -11,7 +11,7 @@ import type { SearchResults } from "../../pipeline/types";
 
 import {
   DEFAULT_INDEX_NAME,
-  decorateUriForIndex,
+  decorateResultUris,
   getIndexDbPath,
 } from "../../app/constants";
 import {
@@ -164,10 +164,9 @@ export function decorateSearchResultsForIndex(
   }
   return {
     ...data,
-    results: data.results.map((result) => ({
-      ...result,
-      uri: decorateUriForIndex(result.uri, indexName),
-    })),
+    results: data.results.map((result) =>
+      decorateResultUris(result, indexName)
+    ),
   };
 }
 
@@ -217,10 +216,13 @@ export function formatSyncResultLines(
       lines.push(`  ${c.filesErrored} errors`);
     }
     // A file stopped at its conversion budget is always named, not only in
-    // verbose output: it stays unindexed until a later run finishes it.
+    // verbose output: it stays unindexed until a later run finishes it. So is
+    // a collection-level error such as an unavailable root.
     if (!options.verbose) {
       for (const err of c.errors) {
-        if (BUDGET_ERROR_CODES.has(err.code)) {
+        if (err.relPath === "") {
+          lines.push(`    [${err.code}] ${err.message}`);
+        } else if (BUDGET_ERROR_CODES.has(err.code)) {
           lines.push(`    [${err.code}] ${err.relPath}: ${err.message}`);
         }
       }

package/src/cli/format/search-results.ts

@@ -88,6 +88,9 @@ function formatTerminal(data: SearchResults, options: FormatOptions): string {
     if (r.title) {
       lines.push(`  ${r.title}`);
     }
+    if (r.supersededBy) {
+      lines.push(`  Superseded by: ${r.supersededBy}`);
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet
@@ -175,6 +178,9 @@ function formatMarkdown(data: SearchResults, options: FormatOptions): string {
     lines.push(`- **URI**: \`${r.uri}\``);
     lines.push(`- **Score**: ${r.score.toFixed(2)}`);
     lines.push(`- **DocID**: \`${r.docid}\``);
+    if (r.supersededBy) {
+      lines.push(`- **Superseded by**: \`${r.supersededBy}\``);
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet
@@ -223,6 +229,11 @@ function formatXml(data: SearchResults, options: FormatOptions): string {
       lines.push(`    <title>${escapeXml(r.title)}</title>`);
     }
     lines.push(`    <relPath>${escapeXml(r.source.relPath)}</relPath>`);
+    if (r.supersededBy) {
+      lines.push(
+        `    <supersededBy>${escapeXml(r.supersededBy)}</supersededBy>`
+      );
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet

package/src/cli/options.ts

@@ -82,6 +82,7 @@ export const CMD = {
   contextSaved: "context.saved",
   modelsList: "models.list",
   tagsList: "tags.list",
+  metadataList: "metadata",
   linksList: "links.list",
   backlinks: "backlinks",
   similar: "similar",
@@ -118,6 +119,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.contextSaved]: ["terminal", "json"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
+  [CMD.metadataList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],
   [CMD.backlinks]: ["terminal", "json", "md"],
   [CMD.similar]: ["terminal", "json", "md"],

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),
@@ -4184,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",