@gmickel/gno 2.3.3 → 2.4.0

package/src/core/typed-metadata.ts

@@ -0,0 +1,224 @@
+/** Bounded custom metadata and the shared, type-strict retrieval predicate. */
+import { z } from "zod";
+
+export type MetadataScalar = string | number | boolean;
+export type TypedValue = MetadataScalar | MetadataScalar[];
+export type TypedMetadata = Record<string, TypedValue>;
+export type MetadataPredicate =
+  | { op: "and" | "or"; predicates: MetadataPredicate[] }
+  | { op: "not"; predicate: MetadataPredicate }
+  | { op: "eq" | "ne"; key: string; value: MetadataScalar }
+  | { op: "gt" | "gte" | "lt" | "lte"; key: string; value: number }
+  | { op: "in" | "nin" | "all"; key: string; values: MetadataScalar[] }
+  | { op: "exists"; key: string; value: boolean };
+
+export const TYPED_METADATA_INGEST_VERSION = 7;
+export const METADATA_LIMITS = {
+  keys: 64,
+  keyLength: 128,
+  stringLength: 4096,
+  members: 128,
+  bytes: 65_536,
+  nodes: 128,
+  depth: 8,
+} as const;
+const reserved = new Set(["__proto__", "prototype", "constructor"]);
+const keySchema = z
+  .string()
+  .min(1)
+  .max(METADATA_LIMITS.keyLength)
+  .refine((key) => !reserved.has(key), "Reserved metadata key");
+const scalarSchema = z.union([
+  z.string().max(METADATA_LIMITS.stringLength),
+  z.number().finite(),
+  z.boolean(),
+]);
+const membersSchema = z
+  .array(scalarSchema)
+  .max(METADATA_LIMITS.members)
+  .refine(
+    (values) => values.every((value) => typeof value === typeof values[0]),
+    "Array members must have one scalar type"
+  );
+export const typedMetadataSchema = z
+  .unknown()
+  .superRefine((value, ctx) => {
+    if (
+      value &&
+      typeof value === "object" &&
+      Object.keys(value).some((key) => reserved.has(key))
+    ) {
+      ctx.addIssue({ code: "custom", message: "Reserved metadata key" });
+    }
+  })
+  .pipe(
+    z
+      .record(keySchema, z.union([scalarSchema, membersSchema]))
+      .refine(
+        (value) => Object.keys(value).length <= METADATA_LIMITS.keys,
+        "Too many metadata keys"
+      )
+      .refine(
+        (value) =>
+          new TextEncoder().encode(JSON.stringify(value)).length <=
+          METADATA_LIMITS.bytes,
+        "Metadata exceeds 64 KiB"
+      )
+  );
+
+const leafSchemas = [
+  z
+    .object({ op: z.enum(["eq", "ne"]), key: keySchema, value: scalarSchema })
+    .strict(),
+  z
+    .object({
+      op: z.enum(["gt", "gte", "lt", "lte"]),
+      key: keySchema,
+      value: z.number().finite(),
+    })
+    .strict(),
+  z
+    .object({
+      op: z.enum(["in", "nin", "all"]),
+      key: keySchema,
+      values: membersSchema.refine(
+        (v) => v.length > 0,
+        "Membership requires values"
+      ),
+    })
+    .strict(),
+  z
+    .object({ op: z.literal("exists"), key: keySchema, value: z.boolean() })
+    .strict(),
+] as const;
+
+/** Finite schema recursion rejects deep/cyclic SDK values before descending.
+ * Each level shares its child schema; MCP can export the real input contract. */
+function predicateAtDepth(depth: number): z.ZodType<MetadataPredicate> {
+  if (depth === METADATA_LIMITS.depth)
+    return z
+      .discriminatedUnion("op", leafSchemas)
+      .meta({ id: "gnoMetadataPredicateDepth8" });
+  const child = predicateAtDepth(depth + 1);
+  return z
+    .discriminatedUnion("op", [
+      ...leafSchemas,
+      z
+        .object({
+          op: z.enum(["and", "or"]),
+          predicates: z.array(child).min(1).max(128),
+        })
+        .strict(),
+      z.object({ op: z.literal("not"), predicate: child }).strict(),
+    ])
+    .meta({ id: `gnoMetadataPredicateDepth${depth}` });
+}
+
+export const metadataPredicateSchema = predicateAtDepth(1).superRefine(
+  (input, ctx) => {
+    const queue: MetadataPredicate[] = [input];
+    let nodes = 0;
+    while (queue.length) {
+      const node = queue.pop();
+      if (!node) break;
+      if (++nodes > METADATA_LIMITS.nodes) {
+        ctx.addIssue({ code: "custom", message: "Filter exceeds 128 nodes" });
+        return;
+      }
+      if ("predicates" in node) queue.push(...node.predicates);
+      if ("predicate" in node) queue.push(node.predicate);
+    }
+    if (
+      new TextEncoder().encode(JSON.stringify(input)).length >
+      METADATA_LIMITS.bytes
+    ) {
+      ctx.addIssue({ code: "custom", message: "Filter exceeds 64 KiB" });
+    }
+  }
+);
+
+export function normalizeMetadataPredicate(input: unknown): MetadataPredicate {
+  const predicate = metadataPredicateSchema.parse(input);
+  const normalize = (node: MetadataPredicate): MetadataPredicate => {
+    if ("predicates" in node) {
+      const unique = new Map(
+        node.predicates.map((child) => {
+          const value = normalize(child);
+          return [JSON.stringify(value), value];
+        })
+      );
+      return {
+        op: node.op,
+        predicates: [...unique.entries()]
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([, value]) => value),
+      };
+    }
+    if (node.op === "not")
+      return { op: "not", predicate: normalize(node.predicate) };
+    if ("values" in node)
+      return {
+        op: node.op,
+        key: node.key,
+        values: [...new Set(node.values)].sort((a, b) =>
+          JSON.stringify(a) < JSON.stringify(b)
+            ? -1
+            : JSON.stringify(a) > JSON.stringify(b)
+              ? 1
+              : 0
+        ),
+      };
+    return node;
+  };
+  return normalize(predicate);
+}
+
+export function matchesMetadataPredicate(
+  metadata: TypedMetadata,
+  predicate: MetadataPredicate
+): boolean {
+  if (predicate.op === "and")
+    return predicate.predicates.every((p) =>
+      matchesMetadataPredicate(metadata, p)
+    );
+  if (predicate.op === "or")
+    return predicate.predicates.some((p) =>
+      matchesMetadataPredicate(metadata, p)
+    );
+  if (predicate.op === "not")
+    return !matchesMetadataPredicate(metadata, predicate.predicate);
+  if (!("key" in predicate)) return false;
+  const present = Object.hasOwn(metadata, predicate.key);
+  if (predicate.op === "exists") return present === predicate.value;
+  if (!present) return false;
+  const field = metadata[predicate.key];
+  if ("values" in predicate) {
+    const values = Array.isArray(field) ? field : [field];
+    if (predicate.op === "all")
+      return (
+        Array.isArray(field) && predicate.values.every((v) => field.includes(v))
+      );
+    const match = values.some((v) =>
+      predicate.values.some((wanted) => wanted === v)
+    );
+    return predicate.op === "in" ? match : !match;
+  }
+  if (Array.isArray(field)) return false;
+  if (predicate.op === "eq") return field === predicate.value;
+  if (predicate.op === "ne")
+    return typeof field === typeof predicate.value && field !== predicate.value;
+  if (typeof field !== "number" || typeof predicate.value !== "number")
+    return false;
+  switch (predicate.op) {
+    case "gt":
+      return field > predicate.value;
+    case "gte":
+      return field >= predicate.value;
+    case "lt":
+      return field < predicate.value;
+    case "lte":
+      return field <= predicate.value;
+    default:
+      return false;
+  }
+}

package/src/ingestion/record-adapter-canonical.ts

@@ -7,9 +7,11 @@ import type {
   RecordAnchor,
   RecordMetadata,
 } from "../converters/types";
+import type { TypedMetadata } from "../core/typed-metadata";
 
 import { canonicalize, mirrorHash } from "../converters/canonicalize";
 import { RECORD_METADATA_LIMITS } from "../converters/types";
+import { validateRecordMetadata } from "./typed-metadata";
 
 const HASH_PATTERN = /^[a-f\d]{64}$/;
 const CONTROL_PATTERN = new RegExp(
@@ -33,6 +35,8 @@ const RECORD_ATTACHMENT_DISPOSITIONS = new Set<
 >(["inline", "attachment"]);
 
 export interface CanonicalRecord {
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
   recordKey: string;
   stableId: string;
   sourceLocator: string;
@@ -44,7 +48,7 @@ export interface CanonicalRecord {
   adapterFingerprint: string;
   title?: string;
   languageHint?: string;
-  metadata?: RecordMetadata;
+  metadata?: Omit<RecordMetadata, "custom">;
   anchors?: RecordAnchor[];
 }
 
@@ -187,7 +191,7 @@ const normalizeFailureReference = (
 
 const normalizeMetadata = (
   metadata: RecordMetadata | undefined
-): RecordMetadata | undefined => {
+): Omit<RecordMetadata, "custom"> | undefined => {
   if (!metadata) return undefined;
   const normalizeList = (
     values: string[] | undefined,
@@ -348,6 +352,10 @@ export const canonicalRecord = (
   const sourceLocator = normalizeLocator(record.sourceLocator);
   const markdown = canonicalize(record.markdown);
   const metadata = normalizeMetadata(record.metadata);
+  const custom =
+    record.metadata && Object.hasOwn(record.metadata, "custom")
+      ? validateRecordMetadata(record.metadata.custom, "metadata.custom")
+      : undefined;
   const anchors = normalizeAnchors(record.anchors);
   const title = boundedText(record.title, RECORD_METADATA_LIMITS.maxTitleChars);
   const languageHint = boundedText(
@@ -360,6 +368,7 @@ export const canonicalRecord = (
       languageHint,
       markdown,
       metadata,
+      ...custom,
       sourceLocator,
       stableId,
       title,
@@ -370,6 +379,7 @@ export const canonicalRecord = (
       anchors,
       languageHint,
       metadata,
+      ...custom,
       sourceLocator,
       stableId,
       title,
@@ -395,6 +405,7 @@ export const canonicalRecord = (
     title,
     languageHint,
     metadata,
+    ...custom,
     anchors,
     accountingChars: derivedSource.length,
     metadataChars,

package/src/ingestion/record-container.ts

@@ -1,6 +1,7 @@
 import type { NormalizedContentTypeRule } from "../config";
 import type { Collection } from "../config/types";
 import type { RecordAdapter, RecordMetadata } from "../converters/types";
+import type { TypedMetadata } from "../core/typed-metadata";
 import type {
   ChunkInput,
   DocumentRow,
@@ -36,6 +37,8 @@ interface RecordDocumentMetadata {
   author?: string;
   frontmatterDate?: string;
   dateFields?: Record<string, string>;
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
 }
 
 interface RecordContainerInput {
@@ -376,6 +379,12 @@ const persistRecord = async (
         author: record.metadata?.author ?? inferred.author,
         frontmatterDate: primaryDate(dateFields) ?? inferred.frontmatterDate,
         dateFields,
+        typedMetadata: record.metadataError
+          ? undefined
+          : (record.typedMetadata ?? inferred.typedMetadata),
+        metadataError:
+          record.metadataError ??
+          (record.typedMetadata ? undefined : inferred.metadataError),
         recordKey: record.recordKey,
         recordSourcePath: input.entry.relPath,
         recordSourceLocator: record.sourceLocator,

package/src/ingestion/sync.ts

@@ -12,6 +12,7 @@ import { isAbsolute, join, relative, sep } from "node:path";
 
 import type { NormalizedContentTypeRule } from "../config";
 import type { Collection } from "../config/types";
+import type { TypedMetadata } from "../core/typed-metadata";
 import type {
   ChunkInput,
   DocLinkInput,
@@ -57,6 +58,7 @@ import {
 } from "../core/links";
 import { extractMemoryScopes } from "../core/memory-record";
 import { normalizeTag, validateTag } from "../core/tags";
+import { TYPED_METADATA_INGEST_VERSION } from "../core/typed-metadata";
 import { defaultChunker } from "./chunker";
 import { persistChunkLayout, prepareChunking } from "./chunking";
 import {
@@ -81,6 +83,7 @@ import {
   type SourceReadFailure,
 } from "./source-availability";
 import { getExcludedRanges } from "./strip";
+import { extractTypedMetadata } from "./typed-metadata";
 import { collectionToWalkConfig, DEFAULT_CHUNK_PARAMS } from "./types";
 import { defaultWalker } from "./walker";
 
@@ -98,7 +101,7 @@ const MAX_CONCURRENCY = 16;
  * Increment when ingestion adds new derived data (tags, metadata, etc.)
  * Documents with ingestVersion < INGEST_VERSION will be re-processed.
  */
-export const INGEST_VERSION = 6;
+export const INGEST_VERSION = TYPED_METADATA_INGEST_VERSION;
 const EMPTY_CONTENT_TYPE_RULES_FINGERPRINT =
   fingerprintContentTypeMetadataRules([]);
 const NON_RETRYABLE_CONVERSION_ERROR_CODES = new Set([
@@ -211,6 +214,8 @@ function extractTags(markdown: string): string[] {
 }
 
 interface DocumentMetadata {
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
   contentType?: string;
   contentTypeSource: ContentTypeSource;
   categories?: string[];
@@ -404,6 +409,7 @@ export function extractDocumentMetadata(
   }
 
   return {
+    ...extractTypedMetadata(markdown),
     contentType,
     contentTypeSource,
     categories: [...categories],
@@ -493,6 +499,8 @@ const preserveDocumentWithError = (
   author: existing.author ?? undefined,
   frontmatterDate: existing.frontmatterDate ?? undefined,
   dateFields: existing.dateFields ?? undefined,
+  typedMetadata: existing.typedMetadata ?? undefined,
+  metadataError: existing.metadataError ?? undefined,
   recordKey: existing.recordKey ?? undefined,
   recordSourcePath: existing.recordSourcePath ?? undefined,
   recordSourceLocator: existing.recordSourceLocator ?? undefined,
@@ -913,6 +921,8 @@ export class SyncService {
           author: extractedMetadata.author,
           frontmatterDate: extractedMetadata.frontmatterDate,
           dateFields: extractedMetadata.dateFields,
+          typedMetadata: extractedMetadata.typedMetadata,
+          metadataError: extractedMetadata.metadataError,
           contentTypeRulesFingerprint,
           // Clear error fields on success (requires store to handle undefined → null)
           lastErrorCode: undefined,

package/src/ingestion/typed-metadata.ts

@@ -0,0 +1,55 @@
+import type { TypedMetadata } from "../core/typed-metadata";
+
+import { METADATA_LIMITS, typedMetadataSchema } from "../core/typed-metadata";
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)(?:\r?\n)?---(?:\r?\n|$)/;
+const GNO_KEY = /(?:^|[{,]\s*)(?:gno|"gno"|'gno')\s*:/m;
+export interface TypedMetadataExtraction {
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
+}
+
+export function extractTypedMetadata(
+  markdown: string
+): TypedMetadataExtraction {
+  const yaml = FRONTMATTER.exec(markdown)?.[1];
+  if (yaml === undefined || !GNO_KEY.test(yaml)) return { typedMetadata: {} };
+  if (new TextEncoder().encode(yaml).length > METADATA_LIMITS.bytes) {
+    return {
+      metadataError: "frontmatter: exceeds 64 KiB typed metadata parsing limit",
+    };
+  }
+  // Bun.YAML aliases share object references rather than expanding copies.
+  // The flat typed validator below rejects nested/cyclic values.
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(yaml);
+  } catch {
+    return { metadataError: "gno.metadata: invalid YAML" };
+  }
+  if (!parsed || typeof parsed !== "object" || !Object.hasOwn(parsed, "gno"))
+    return { typedMetadata: {} };
+  const gno = (parsed as Record<string, unknown>).gno;
+  if (!gno || typeof gno !== "object" || Array.isArray(gno)) {
+    return { metadataError: "gno: expected a mapping" };
+  }
+  if (!Object.hasOwn(gno, "metadata")) return { typedMetadata: {} };
+  return validateRecordMetadata((gno as Record<string, unknown>).metadata);
+}
+
+export function validateRecordMetadata(
+  value: unknown,
+  namespace = "gno.metadata"
+): TypedMetadataExtraction {
+  const parsed = typedMetadataSchema.safeParse(value);
+  if (parsed.success) return { typedMetadata: parsed.data };
+  const issue = parsed.error.issues[0];
+  // Values may be private. Persist only the bounded field path, never input.
+  return {
+    metadataError:
+      `${namespace}.${issue?.path.map(String).join(".") ?? ""}: invalid typed metadata`.slice(
+        0,
+        256
+      ),
+  };
+}

package/src/mcp/tools/ask.ts

@@ -1,6 +1,5 @@
-/** MCP verified Ask tool over the shared closed-evidence application boundary. */
-
 import { z } from "zod";
+/** MCP verified Ask tool over the shared closed-evidence application boundary. */
 
 import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { QueryModeInput } from "../../pipeline/types";
@@ -16,6 +15,10 @@ import {
 } from "../../core/retrieval-trace-request";
 import { attachRetrievalTraceMetadata } from "../../core/retrieval-trace-session";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
+import {
+  metadataPredicateSchema,
+  normalizeMetadataPredicate,
+} from "../../core/typed-metadata";
 import { resolveModelUri } from "../../llm/registry";
 import { answerTraceTerminalStatus } from "../../pipeline/answer";
 import { createMcpModelPorts, type McpModelPortFactory } from "./context";
@@ -41,6 +44,7 @@ export const askInputSchema = z
     candidateLimit: z.number().int().min(1).max(100).optional(),
     exclude: z.array(z.string()).optional(),
     queryModes: z.array(queryModeSchema).optional(),
+    filter: metadataPredicateSchema.optional(),
     tagsAll: z.array(z.string()).optional(),
     tagsAny: z.array(z.string()).optional(),
     since: z.string().optional(),
@@ -163,6 +167,10 @@ export const handleAsk = (
       );
       const options = {
         ...askInput,
+        filter:
+          args.filter === undefined
+            ? undefined
+            : normalizeMetadataPredicate(args.filter),
         projectAffinity,
         queryModes:
           normalized.value.queryModes.length > 0

package/src/mcp/tools/context.ts

@@ -261,6 +261,7 @@ export const handleContext = (
           until: parsed.input.until,
           categories: parsed.input.categories,
           author: parsed.input.author,
+          filter: parsed.input.filter,
           graph: parsed.input.graph,
           candidateLimit: parsed.input.candidateLimit,
           queryModes: parsed.input.queryModes,

package/src/mcp/tools/index.ts

@@ -1,10 +1,11 @@
-import type { McpServer } from "@modelcontextprotocol/server";
 /**
  * MCP tool registration and shared utilities.
  *
  * @module src/mcp/tools
  */
 
+import type { McpServer } from "@modelcontextprotocol/server";
+
 import { z } from "zod";
 
 import type { ToolContext } from "../server";
@@ -17,6 +18,7 @@ import { CAPTURE_MAX_TEXT_BYTES } from "../../core/capture";
 import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
 import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
+import { metadataPredicateSchema } from "../../core/typed-metadata";
 import {
   assertInferenceActive,
   acquireInferencePermit,
@@ -258,6 +260,9 @@ export const searchInputSchema = z.object({
     .string()
     .optional()
     .describe("Filter by author (case-insensitive substring match)"),
+  filter: metadataPredicateSchema
+    .optional()
+    .describe("Typed custom metadata predicate; intersects existing scope"),
   tagsAll: z
     .array(z.string())
     .optional()
@@ -488,6 +493,9 @@ export const vsearchInputSchema = z.object({
     .string()
     .optional()
     .describe("Filter by author (case-insensitive substring)"),
+  filter: metadataPredicateSchema
+    .optional()
+    .describe("Typed custom metadata predicate; intersects existing scope"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });
@@ -614,6 +622,9 @@ export const queryInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Include deterministic stage and per-result scoring metadata"),
+  filter: metadataPredicateSchema
+    .optional()
+    .describe("Typed custom metadata predicate; intersects existing scope"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });

package/src/mcp/tools/query.ts

@@ -38,6 +38,10 @@ import {
   type RetrievalTraceSession,
 } from "../../core/retrieval-trace-session";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
+import {
+  normalizeMetadataPredicate,
+  type MetadataPredicate,
+} from "../../core/typed-metadata";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
@@ -60,6 +64,7 @@ interface QueryInput {
   until?: string;
   categories?: string[];
   author?: string;
+  filter?: MetadataPredicate;
   queryModes?: QueryModeInput[];
   fast?: boolean;
   thorough?: boolean;
@@ -251,6 +256,10 @@ export function handleQuery(
         until: args.until,
         categories: args.categories,
         author: args.author,
+        filter:
+          args.filter === undefined
+            ? undefined
+            : normalizeMetadataPredicate(args.filter),
         noExpand,
         noRerank,
         graph: args.graph,
@@ -524,6 +533,10 @@ export function handleQueryDiagnose(
           until: args.until,
           categories: args.categories,
           author: args.author,
+          filter:
+            args.filter === undefined
+              ? undefined
+              : normalizeMetadataPredicate(args.filter),
           noExpand,
           noRerank,
           graph: args.graph,

package/src/mcp/tools/search.ts

@@ -19,6 +19,10 @@ import {
   startRetrievalTraceRequest,
 } from "../../core/retrieval-trace-request";
 import { attachRetrievalTraceMetadata } from "../../core/retrieval-trace-session";
+import {
+  normalizeMetadataPredicate,
+  type MetadataPredicate,
+} from "../../core/typed-metadata";
 import { searchBm25 } from "../../pipeline/search";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
@@ -35,6 +39,7 @@ interface SearchInput {
   until?: string;
   categories?: string[];
   author?: string;
+  filter?: MetadataPredicate;
   tagsAll?: string[];
   tagsAny?: string[];
 }
@@ -131,6 +136,10 @@ export function handleSearch(
         until: args.until,
         categories: args.categories,
         author: args.author,
+        filter:
+          args.filter === undefined
+            ? undefined
+            : normalizeMetadataPredicate(args.filter),
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,

package/src/mcp/tools/status.ts

@@ -52,6 +52,10 @@ function formatStatus(status: IndexStatus): string {
     `Total: ${status.activeDocuments} documents, ${status.totalChunks} chunks`
   );
 
+  if (status.typedMetadata)
+    lines.push(
+      `Typed metadata: ${status.typedMetadata.pending} pending sync, ${status.typedMetadata.invalid} invalid`
+    );
   if (status.embeddingBacklog > 0) {
     lines.push(`Embedding backlog: ${status.embeddingBacklog} chunks`);
   }

package/src/mcp/tools/vsearch.ts

@@ -22,6 +22,10 @@ import {
   attachRetrievalTraceMetadata,
   type RetrievalTraceSession,
 } from "../../core/retrieval-trace-session";
+import {
+  normalizeMetadataPredicate,
+  type MetadataPredicate,
+} from "../../core/typed-metadata";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -46,6 +50,7 @@ interface VsearchInput {
   until?: string;
   categories?: string[];
   author?: string;
+  filter?: MetadataPredicate;
   tagsAll?: string[];
   tagsAny?: string[];
 }
@@ -151,6 +156,10 @@ export function handleVsearch(
         until: args.until,
         categories: args.categories,
         author: args.author,
+        filter:
+          args.filter === undefined
+            ? undefined
+            : normalizeMetadataPredicate(args.filter),
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,

package/src/pipeline/diagnose.ts

@@ -19,6 +19,7 @@ import {
   normalizeContentTypes,
 } from "../config";
 import { resolveDocRef } from "../core/ref-parser";
+import { normalizeMetadataPredicate } from "../core/typed-metadata";
 import { err, ok } from "../store/types";
 import {
   getContentTypeBoostMetadata,
@@ -184,6 +185,11 @@ export async function diagnoseQueryTarget(
   query: string,
   options: QueryDiagnoseOptions
 ): Promise<StoreResult<QueryDiagnoseResult>> {
+  if (options.filter !== undefined)
+    options = {
+      ...options,
+      filter: normalizeMetadataPredicate(options.filter),
+    };
   const resolved = await resolveDocRef(deps.store, options.target);
   if ("error" in resolved) {
     return ok(buildBaseResult(query, options.target, "not_found", null));