@gmickel/gno 1.17.0 → 1.19.0

package/src/cli/program.ts

@@ -164,6 +164,15 @@ async function writeOutput(
   }
 }
 
+/** Emit opt-in trace identity without changing command stdout payloads. */
+export function writeRetrievalTraceReceipt(
+  metadata: { traceId: string } | undefined
+): void {
+  if (metadata) {
+    process.stderr.write(`Trace: ${metadata.traceId}\n`);
+  }
+}
+
 async function resolveTerminalLinkPolicy(
   format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
 ): Promise<
@@ -292,6 +301,7 @@ export function createProgram(): Command {
   wireOnboardingCommands(program);
   wireCaptureCommand(program);
   wireManagementCommands(program);
+  wireTraceCommands(program);
   wirePublishCommand(program);
   wireVecCommands(program);
   wireRetrievalCommands(program);
@@ -315,6 +325,244 @@ Report issues: ${ISSUES_URL}`
   return program;
 }
 
+function wireTraceCommands(program: Command): void {
+  const traceCmd = program
+    .command("trace")
+    .description("Inspect and manage private local retrieval traces");
+
+  const outputFormat = (options: Record<string, unknown>): "json" | "md" =>
+    getFormat(options) === "json" ? "json" : "md";
+
+  traceCmd
+    .command("list")
+    .description("List bounded, redacted retrieval trace summaries")
+    .option("-n, --limit <num>", "maximum traces", "50")
+    .option("--cursor <cursor>", "continue from a previous list receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceList } = await import("./commands/trace");
+      const output = await traceList(
+        {
+          limit: parsePositiveInt("limit", cmdOpts.limit),
+          cursor: cmdOpts.cursor as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("show <trace-id>")
+    .description("Inspect one bounded retrieval trace receipt")
+    .option("--detail-limit <num>", "maximum records per detail section", "500")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceShow } = await import("./commands/trace");
+      const output = await traceShow(
+        traceId,
+        {
+          detailLimit: parsePositiveInt("detail-limit", cmdOpts.detailLimit),
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("label <trace-id>")
+    .description("Append an explicit retrieval relevance judgment")
+    .requiredOption(
+      "--label <label>",
+      "relevant, irrelevant, or missing-expected"
+    )
+    .requiredOption("--target <ref>", "evidence or expected-document reference")
+    .option("--target-kind <kind>", "document, chunk, or span")
+    .option("--from-line <num>", "exact evidence start line")
+    .option("--to-line <num>", "exact evidence end line")
+    .option("--source-hash <sha256>", "expected immutable source hash")
+    .option("--docid <docid>", "expected document ID")
+    .option("--idempotency-key <key>", "caller retry key")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const rawLabel = String(cmdOpts.label).replace("-", "_");
+      if (!["relevant", "irrelevant", "missing_expected"].includes(rawLabel)) {
+        throw new CliError(
+          "VALIDATION",
+          "--label must be relevant, irrelevant, or missing-expected"
+        );
+      }
+      const rawTargetKind = cmdOpts.targetKind;
+      if (
+        rawTargetKind !== undefined &&
+        (typeof rawTargetKind !== "string" ||
+          !["document", "chunk", "span"].includes(rawTargetKind))
+      ) {
+        throw new CliError(
+          "VALIDATION",
+          "--target-kind must be document, chunk, or span"
+        );
+      }
+      const { traceLabel } = await import("./commands/trace");
+      const output = await traceLabel(
+        {
+          traceId,
+          label: rawLabel as "relevant" | "irrelevant" | "missing_expected",
+          targetRef: String(cmdOpts.target),
+          targetKind: rawTargetKind as
+            | "document"
+            | "chunk"
+            | "span"
+            | undefined,
+          startLine:
+            cmdOpts.fromLine === undefined
+              ? undefined
+              : parsePositiveInt("from-line", cmdOpts.fromLine),
+          endLine:
+            cmdOpts.toLine === undefined
+              ? undefined
+              : parsePositiveInt("to-line", cmdOpts.toLine),
+          sourceHash: cmdOpts.sourceHash as string | undefined,
+          docid: cmdOpts.docid as string | undefined,
+          idempotencyKey: cmdOpts.idempotencyKey as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("export <trace-ids...>")
+    .description("Export immutable terminal traces as one local receipt")
+    .option("--format <format>", "agentic-receipt or qrels", "agentic-receipt")
+    .option("--output <path>", "write canonical artifact atomically")
+    .option("--json", "JSON output")
+    .action(async (traceIds: string[], cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const exportFormat = String(cmdOpts.format);
+      if (!["agentic-receipt", "qrels"].includes(exportFormat)) {
+        throw new CliError(
+          "VALIDATION",
+          "--format must be agentic-receipt or qrels"
+        );
+      }
+      const { traceExport } = await import("./commands/trace");
+      process.stdout.write(
+        await traceExport(traceIds, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: "json",
+          output: cmdOpts.output as string | undefined,
+          exportFormat: exportFormat as "agentic-receipt" | "qrels",
+        })
+      );
+    });
+
+  traceCmd
+    .command("replay <export-id>")
+    .description("Compare one immutable qrels baseline with a candidate")
+    .requiredOption("--candidate <type>", "bm25, vector, or hybrid")
+    .option("-n, --limit <num>", "result cutoff")
+    .option("--candidate-limit <num>", "candidate pool size")
+    .option("--no-expand", "disable query expansion")
+    .option("--no-rerank", "disable reranking")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (exportId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const candidateType = String(cmdOpts.candidate);
+      if (!["bm25", "vector", "hybrid"].includes(candidateType)) {
+        throw new CliError(
+          "VALIDATION",
+          "--candidate must be bm25, vector, or hybrid"
+        );
+      }
+      const { traceReplay } = await import("./commands/replay");
+      process.stdout.write(
+        await traceReplay(
+          exportId,
+          {
+            id: `cli-${candidateType}`,
+            type: candidateType as "bm25" | "vector" | "hybrid",
+            limit:
+              cmdOpts.limit === undefined
+                ? undefined
+                : parsePositiveInt("limit", cmdOpts.limit),
+            candidateLimit:
+              cmdOpts.candidateLimit === undefined
+                ? undefined
+                : parsePositiveInt("candidate-limit", cmdOpts.candidateLimit),
+            noExpand: cmdOpts.expand === false,
+            noRerank: cmdOpts.rerank === false,
+          },
+          {
+            configPath: globals.config,
+            indexName: globals.index,
+            format: outputFormat(cmdOpts),
+            offline: globals.offline,
+          }
+        )
+      );
+    });
+
+  traceCmd
+    .command("delete <trace-id>")
+    .description("Delete one trace and every owned local record")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceDelete } = await import("./commands/trace");
+      process.stdout.write(
+        await traceDelete(traceId, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+
+  traceCmd
+    .command("purge")
+    .description("Delete every local retrieval trace receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      if (!globals.yes) {
+        throw new CliError(
+          "VALIDATION",
+          "Trace purge requires the global --yes confirmation"
+        );
+      }
+      const { tracePurge } = await import("./commands/trace");
+      process.stdout.write(
+        await tracePurge({
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Commands (search, vsearch, query, ask)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -435,6 +683,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // vsearch - Vector similarity search
@@ -547,6 +796,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // query - Hybrid search with expansion and reranking
@@ -768,6 +1018,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // bench - Retrieval benchmark fixture runner
@@ -960,6 +1211,7 @@ function wireSearchCommands(program: Command): void {
         showSources,
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 }
 
@@ -1191,6 +1443,7 @@ function wireRetrievalCommands(program: Command): void {
       parsePositiveInt.bind(null, "limit")
     )
     .option("--line-numbers", "Prefix lines with numbers")
+    .option("--trace-id <id>", "Continue an open retrieval trace")
     .option("--source", "Include source metadata")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -1209,6 +1462,7 @@ function wireRetrievalCommands(program: Command): void {
         source: Boolean(cmdOpts.source),
         json: format === "json",
         md: format === "md",
+        traceId: cmdOpts.traceId as string | undefined,
       });
 
       if (!result.success) {
@@ -1225,6 +1479,7 @@ function wireRetrievalCommands(program: Command): void {
           md: format === "md",
         })}\n`
       );
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // multi-get - Retrieve multiple documents
@@ -2806,20 +3061,46 @@ function wireGraphCommand(program: Command): void {
 // Serve Command (web UI)
 // ─────────────────────────────────────────────────────────────────────────────
 
-function wireDaemonCommand(program: Command): void {
-  const daemonCmd = program
-    .command("daemon")
-    .description("Start headless continuous indexing")
+function addGatewayOptions(
+  command: Command,
+  hostDescription = "HTTP listen address (default: 127.0.0.1)"
+): Command {
+  return command
+    .option("--host <address>", hostDescription)
+    .option("--mcp-token-file <path>", "restrictive bearer token file")
     .option(
-      "--no-sync-on-start",
-      "skip initial sync and only watch future file changes"
+      "--mcp-allowed-host <host>",
+      "exact allowed Host header (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value]
     )
-    // Local `--json` so `gno daemon --status --json` parses cleanly in any
-    // argv position. Mirrors the serve wiring: gated to --status only.
     .option(
-      "--json",
-      "JSON output (applies to --status; see process-status schema)"
+      "--mcp-allowed-origin <origin>",
+      "exact allowed Origin (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value]
+    )
+    .option(
+      "--mcp-enable-write",
+      "authorize HTTP MCP mutation tools (independent of authentication)"
     );
+}
+
+function wireDaemonCommand(program: Command): void {
+  const daemonCmd = addGatewayOptions(
+    program
+      .command("daemon")
+      .description("Start headless continuous indexing")
+      .option("-p, --port <num>", "MCP gateway port", "3000")
+      .option(
+        "--no-sync-on-start",
+        "skip initial sync and only watch future file changes"
+      )
+      // Local `--json` so `gno daemon --status --json` parses cleanly in any
+      // argv position. Mirrors the serve wiring: gated to --status only.
+      .option(
+        "--json",
+        "JSON output (applies to --status; see process-status schema)"
+      )
+  );
 
   // --detach / --status / --stop are mutually exclusive. Use Commander's
   // Option API so the conflict error is the native "option '--status'
@@ -2873,8 +3154,8 @@ function wireDaemonCommand(program: Command): void {
  * the foreground + detached-child paths boot the runtime.
  *
  * Mirrors `handleServeAction` exactly — same helper imports, same JSON
- * gating, same detached-child verification + pid-file cleanup. Daemon has no
- * `--port`, so the foreground path skips port validation entirely.
+ * gating, same detached-child verification + pid-file cleanup. Daemon's port
+ * identifies its headless MCP gateway.
  */
 async function handleDaemonAction(
   cmdOpts: Record<string, unknown>,
@@ -2927,7 +3208,9 @@ async function handleDaemonAction(
   }
 
   if (cmdOpts.detach) {
+    const port = parsePositiveInt("port", cmdOpts.port);
     await runDaemonDetach({
+      port,
       paths,
       spawnDetached,
       argv: resolveCliArgv(cmd),
@@ -2954,6 +3237,8 @@ async function handleDaemonAction(
     installPidFileCleanup(paths.pidFile);
   }
 
+  const port = parsePositiveInt("port", cmdOpts.port);
+
   const { daemon } = await import("./commands/daemon.js");
   const result = await daemon({
     configPath: globals.config,
@@ -2962,6 +3247,12 @@ async function handleDaemonAction(
     verbose: globals.verbose,
     quiet: globals.quiet,
     noSyncOnStart: cmdOpts.syncOnStart === false,
+    port,
+    host: cmdOpts.host as string | undefined,
+    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
+    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
+    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
+    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
   });
   if (!result.success) {
     throw new CliError("RUNTIME", result.error);
@@ -2995,8 +3286,9 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     process.stdout.write("gno daemon status\n");
     process.stdout.write(`${"─".repeat(50)}\n`);
     if (status.running) {
-      // Daemon is headless — no port to print.
-      process.stdout.write(`  running  yes (pid ${status.pid})\n`);
+      process.stdout.write(
+        `  running  yes (pid ${status.pid}, port ${status.port})\n`
+      );
       if (status.version) {
         process.stdout.write(`  version  ${status.version}\n`);
       }
@@ -3091,6 +3383,7 @@ async function runDaemonStop(deps: DaemonStopDeps): Promise<void> {
 }
 
 interface DaemonDetachDeps {
+  port: number;
   paths: { pidFile: string; logFile: string };
   spawnDetached: typeof import("./detach.js").spawnDetached;
   /**
@@ -3111,24 +3404,28 @@ async function runDaemonDetach(deps: DaemonDetachDeps): Promise<void> {
     argv: childArgv,
     pidFile: deps.paths.pidFile,
     logFile: deps.paths.logFile,
+    port: deps.port,
   });
-  // Daemon is headless — print pid only (no URL).
+  // Daemon has no Web UI URL; its listener exists solely for MCP.
   process.stdout.write(`PID ${result.pid}\n`);
 }
 
 function wireServeCommand(program: Command): void {
-  const serveCmd = program
-    .command("serve")
-    .description("Start web UI server")
-    .option("-p, --port <num>", "port to listen on", "3000")
-    // Local `--json` so `gno serve --status --json` parses cleanly in any
-    // argv position. Global `--json` already exists on the root program
-    // (see line 208); resolution goes through `getFormat()` /
-    // `getGlobals()` which precedence-merges local over global.
-    .option(
-      "--json",
-      "JSON output (applies to --status; see process-status schema)"
-    );
+  const serveCmd = addGatewayOptions(
+    program
+      .command("serve")
+      .description("Start web UI server")
+      .option("-p, --port <num>", "port to listen on", "3000")
+      // Local `--json` so `gno serve --status --json` parses cleanly in any
+      // argv position. Global `--json` already exists on the root program
+      // (see line 208); resolution goes through `getFormat()` /
+      // `getGlobals()` which precedence-merges local over global.
+      .option(
+        "--json",
+        "JSON output (applies to --status; see process-status schema)"
+      ),
+    "loopback HTTP listen address (default: 127.0.0.1)"
+  );
 
   // --detach / --status / --stop are mutually exclusive. Use Commander's
   // Option API so the conflict error is the native "option '--status'
@@ -3275,6 +3572,11 @@ async function handleServeAction(
     port,
     configPath: globals.config,
     index: globals.index,
+    host: cmdOpts.host as string | undefined,
+    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
+    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
+    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
+    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
   });
 
   if (!result.success) {

package/src/config/index.ts

@@ -50,6 +50,8 @@ export {
   CollectionSchema,
   type Config,
   ConfigSchema,
+  HttpGatewayConfigSchema,
+  HttpGatewayLimitsSchema,
   CONTENT_TYPE_GRAPH_HINTS,
   type ContentTypeConfig,
   type ContentTypeGraphHint,
@@ -67,3 +69,13 @@ export {
   type ScopeType,
   ScopeTypeSchema,
 } from "./types";
+export type { HttpGatewayConfig } from "./types";
+export {
+  RETRIEVAL_TRACE_DEFAULT_RETENTION,
+  type RetrievalTraceConfig,
+  RetrievalTraceConfigSchema,
+  type RetrievalTraceRedactionMode,
+  RetrievalTraceRedactionModeSchema,
+  type RetrievalTraceRetention,
+  RetrievalTraceRetentionSchema,
+} from "./retrieval-traces";

package/src/config/retrieval-traces.ts

@@ -0,0 +1,56 @@
+/** Opt-in retrieval trace configuration and bounded-retention defaults. */
+
+import { z } from "zod";
+
+export const RETRIEVAL_TRACE_DEFAULT_RETENTION = {
+  maxAgeDays: 30,
+  maxTraces: 1_000,
+  maxRecordsPerTrace: 10_000,
+  maxBytes: 16 * 1024 * 1024,
+} as const;
+
+export const RetrievalTraceRetentionSchema = z
+  .object({
+    maxAgeDays: z.number().int().min(1).max(3_650),
+    maxTraces: z.number().int().min(1).max(1_000_000),
+    maxRecordsPerTrace: z.number().int().min(1).max(100_000),
+    maxBytes: z
+      .number()
+      .int()
+      .min(64 * 1024)
+      .max(1024 * 1024 * 1024),
+  })
+  .strict();
+
+export const RetrievalTraceRedactionModeSchema = z.enum(["metadata", "replay"]);
+
+const DisabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(false),
+  })
+  .strict();
+
+const EnabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(true),
+    /**
+     * `replay` stores replay inputs such as the raw query and filters. Choosing
+     * it is explicit consent; the safer metadata-only projection is recommended.
+     */
+    redactionMode: RetrievalTraceRedactionModeSchema,
+    retention: RetrievalTraceRetentionSchema,
+  })
+  .strict();
+
+export const RetrievalTraceConfigSchema = z.discriminatedUnion("enabled", [
+  DisabledRetrievalTraceConfigSchema,
+  EnabledRetrievalTraceConfigSchema,
+]);
+
+export type RetrievalTraceConfig = z.infer<typeof RetrievalTraceConfigSchema>;
+export type RetrievalTraceRetention = z.infer<
+  typeof RetrievalTraceRetentionSchema
+>;
+export type RetrievalTraceRedactionMode = z.infer<
+  typeof RetrievalTraceRedactionModeSchema
+>;

package/src/config/types.ts

@@ -8,6 +8,7 @@
 import { z } from "zod";
 
 import { URI_PREFIX } from "../app/constants";
+import { RetrievalTraceConfigSchema } from "./retrieval-traces";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -245,6 +246,40 @@ export const ModelConfigSchema = z.object({
 
 export type ModelConfig = z.infer<typeof ModelConfigSchema>;
 
+// ────────────────────────────────────────────────────────────────────────────
+// Resident HTTP gateway schema
+// ────────────────────────────────────────────────────────────────────────────
+
+export const HttpGatewayLimitsSchema = z.object({
+  maxBodyBytes: z
+    .number()
+    .int()
+    .min(1)
+    .max(16 * 1024 * 1024)
+    .optional(),
+  maxRequestsPerMinute: z.number().int().min(1).max(100_000).optional(),
+  maxConcurrentRequests: z.number().int().min(1).max(10_000).optional(),
+  maxQueuedRequests: z.number().int().min(0).max(10_000).optional(),
+  maxSessions: z.number().int().min(1).max(10_000).optional(),
+  sessionIdleTimeoutMs: z.number().int().min(1_000).optional(),
+});
+
+export const HttpGatewayConfigSchema = z.object({
+  /** Literal listen address. Defaults to IPv4 loopback. */
+  host: z.string().min(1).optional(),
+  /** Bearer token file. Required for wildcard/non-loopback binding. */
+  tokenFile: z.string().min(1).optional(),
+  /** Exact Host header allowlist. */
+  allowedHosts: z.array(z.string().min(1)).optional(),
+  /** Exact Origin allowlist. Origin-less non-browser clients remain supported. */
+  allowedOrigins: z.array(z.string().min(1)).optional(),
+  /** Separate mutation authorization; authentication alone never enables it. */
+  enableWrite: z.boolean().optional(),
+  limits: HttpGatewayLimitsSchema.optional(),
+});
+
+export type HttpGatewayConfig = z.infer<typeof HttpGatewayConfigSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Content Type Schema
 // ─────────────────────────────────────────────────────────────────────────────
@@ -301,6 +336,12 @@ export const ConfigSchema = z.object({
 
   /** Model configuration */
   models: ModelConfigSchema.optional(),
+
+  /** Resident Streamable HTTP MCP gateway configuration */
+  gateway: HttpGatewayConfigSchema.optional(),
+
+  /** Private local retrieval trace recording. Absent means recording off. */
+  retrievalTraces: RetrievalTraceConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {

package/src/core/context-compiler.ts

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