@gmickel/gno 2.3.2 → 2.4.0

package/src/pipeline/filters.ts

@@ -7,6 +7,11 @@
 import type { ChunkRow, DocumentRow, StorePort } from "../store/types";
 import type { HybridSearchOptions } from "./types";
 
+import {
+  matchesMetadataPredicate,
+  TYPED_METADATA_INGEST_VERSION,
+  type MetadataPredicate,
+} from "../core/typed-metadata";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { isWithinTemporalRange, resolveTemporalRange } from "./temporal";
 
@@ -85,6 +90,8 @@ export function evaluateDocumentChunkFilters(
   options: HybridSearchOptions
 ): QueryFilterEvaluation {
   const reasons: string[] = [];
+  const metadataReason = typedMetadataFilterReason(doc, options.filter);
+  if (metadataReason) reasons.push(metadataReason);
   const temporalRange = resolveTemporalRange(
     query,
     options.since,
@@ -180,3 +187,61 @@ export async function evaluateQueryTargetFilters(
     reasons,
   };
 }
+
+/** Invalid or unextracted documents are ineligible even for negated predicates. */
+export function typedMetadataFilterReason(
+  doc: DocumentRow,
+  filter?: MetadataPredicate
+): string | undefined {
+  if (!filter) return undefined;
+  if ((doc.ingestVersion ?? 0) < TYPED_METADATA_INGEST_VERSION)
+    return "metadata_backfill";
+  if (doc.metadataError || !doc.typedMetadata) return "metadata_invalid";
+  return matchesMetadataPredicate(doc.typedMetadata, filter)
+    ? undefined
+    : "metadata_filter";
+}
+
+export async function typedMetadataWarnings(
+  store: StorePort,
+  query: string,
+  options: HybridSearchOptions
+): Promise<{ code: string; message: string }[] | undefined> {
+  if (!options.filter) return undefined;
+  const unknown = [
+    {
+      code: "METADATA_COVERAGE_UNKNOWN",
+      message:
+        "Typed metadata coverage could not be checked; filtered results may be incomplete.",
+    },
+  ];
+  if (!store.getTypedMetadataCoverage) return unknown;
+  const range = resolveTemporalRange(query, options.since, options.until);
+  const result = await store.getTypedMetadataCoverage({
+    collection: options.collection,
+    relPathPrefix: options.retrievalScope?.relPathPrefix,
+    allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
+    chunkLanguage: options.lang,
+    tagsAll: options.tagsAll,
+    tagsAny: options.tagsAny,
+    since: range.since,
+    until: range.until,
+    categories: options.categories,
+    author: options.author,
+    exclude: options.exclude,
+    excludeMetadata: true,
+    semanticMetadata: true,
+    memoryScopesAny: options.memoryFilter?.scopes,
+    excludeSuperseded: options.memoryFilter?.excludeSuperseded,
+  });
+  if (!result.ok) return unknown;
+  const { pending, invalid } = result.value;
+  return pending || invalid
+    ? [
+        {
+          code: "METADATA_COVERAGE_INCOMPLETE",
+          message: `Typed metadata coverage is incomplete: ${pending} documents need re-ingestion and ${invalid} have invalid metadata within the query scope.`,
+        },
+      ]
+    : undefined;
+}

package/src/pipeline/graph-retrieval.ts

@@ -4,15 +4,18 @@
  * @module src/pipeline/graph-retrieval
  */
 
+import type { MetadataPredicate } from "../core/typed-metadata";
 import type {
   ChunkRow,
   DocumentRow,
+  DocumentEligibilityOptions,
   GraphEdgeConfidence,
   GraphLink,
   StorePort,
 } from "../store/types";
 import type { FusionCandidate } from "./types";
 
+import { typedMetadataFilterReason } from "./filters";
 import { isWithinTemporalRange } from "./temporal";
 
 export interface GraphRetrievalMeta {
@@ -65,9 +68,11 @@ const matchesDocumentFilters = (
     until?: string;
     categories?: string[];
     author?: string;
+    filter?: MetadataPredicate;
     relPathPrefix?: string;
   }
 ): boolean => {
+  if (typedMetadataFilterReason(doc, options.filter)) return false;
   if (
     !isWithinTemporalRange(doc.sourceMtime, {
       since: options.since,
@@ -235,6 +240,7 @@ export async function expandGraphCandidates(
   options: {
     collection?: string;
     includeSimilar?: boolean;
+    eligibility?: DocumentEligibilityOptions;
     limit?: number;
     candidateLimit?: number;
     disabled?: boolean;
@@ -245,6 +251,7 @@ export async function expandGraphCandidates(
     until?: string;
     categories?: string[];
     author?: string;
+    filter?: MetadataPredicate;
     relPathPrefix?: string;
   } = {},
   hydration: Pick<
@@ -300,7 +307,7 @@ export async function expandGraphCandidates(
 
   const rankedSeedDocs: Array<{ doc: DocumentRow; rank: number }> = [];
   for (const doc of seedDocsResult.value) {
-    if (!doc.mirrorHash) {
+    if (!doc.mirrorHash || typedMetadataFilterReason(doc, options.filter)) {
       continue;
     }
     if (
@@ -394,6 +401,7 @@ export async function expandGraphCandidates(
   }
 
   const docsResult = await store.getDocumentsByDocids(rankedNeighborDocids, {
+    eligibility: options.eligibility,
     collection: options.collection,
     activeOnly: true,
   });

package/src/pipeline/hybrid.ts

@@ -1,10 +1,11 @@
-import type { Config } from "../config/types";
 /**
  * Hybrid search orchestrator.
  * Combines BM25, vector search, expansion, fusion, and reranking.
  *
  * @module src/pipeline/hybrid
  */
+
+import type { Config } from "../config/types";
 import type { EmbeddingPort, GenerationPort, RerankPort } from "../llm/types";
 import type { DocumentRow, StorePort } from "../store/types";
 import type {
@@ -24,6 +25,7 @@ import type {
 
 import { normalizeContentTypes } from "../config/content-types";
 import { projectRecordEvidenceMetadata } from "../core/record-metadata";
+import { normalizeMetadataPredicate } from "../core/typed-metadata";
 import { embedTextsWithRecovery } from "../embed/batch";
 import {
   assertInferenceActive,
@@ -54,7 +56,7 @@ import {
   explainTimings,
   explainVector,
 } from "./explain";
-import { evaluateDocumentChunkFilters } from "./filters";
+import { evaluateDocumentChunkFilters, typedMetadataWarnings } from "./filters";
 import { type RankedInput, rrfFuse, toRankedInput } from "./fusion";
 import { expandGraphCandidates } from "./graph-retrieval";
 import { RequestHydration } from "./hydration";
@@ -148,6 +150,7 @@ async function checkBm25Strength(
     until?: string;
     categories?: string[];
     author?: string;
+    filter?: HybridSearchOptions["filter"];
     relPathPrefix?: string;
     allowedMirrorHashes?: string[];
     exclude?: string[];
@@ -173,6 +176,7 @@ async function checkBm25Strength(
     until: options?.until,
     categories: options?.categories,
     author: options?.author,
+    filter: options?.filter,
   });
 
   if (!result.ok || result.value.length === 0) {
@@ -221,6 +225,7 @@ async function searchFtsChunks(
     until?: string;
     categories?: string[];
     author?: string;
+    filter?: HybridSearchOptions["filter"];
     relPathPrefix?: string;
     allowedMirrorHashes?: string[];
     exclude?: string[];
@@ -246,6 +251,7 @@ async function searchFtsChunks(
     until: options.until,
     categories: options.categories,
     author: options.author,
+    filter: options.filter,
   });
   if (!result.ok) {
     // Propagate INVALID_INPUT for FTS syntax errors
@@ -356,6 +362,11 @@ export async function searchHybrid(
   query: string,
   options: HybridSearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  if (options.filter !== undefined)
+    options = {
+      ...options,
+      filter: normalizeMetadataPredicate(options.filter),
+    };
   const hydration = deps.hydration ?? new RequestHydration(deps.store);
   try {
     return await withInferenceScope(options, () =>
@@ -483,6 +494,7 @@ async function searchHybridWithHydration(
           until: temporalRange.until,
           categories: options.categories,
           author: options.author,
+          filter: options.filter,
           relPathPrefix: options.retrievalScope?.relPathPrefix,
         });
 
@@ -531,6 +543,7 @@ async function searchHybridWithHydration(
     until: temporalRange.until,
     categories: options.categories,
     author: options.author,
+    filter: options.filter,
     exclude: options.exclude,
     excludeMetadata: true,
     semanticMetadata: true,
@@ -553,6 +566,7 @@ async function searchHybridWithHydration(
     until: temporalRange.until,
     categories: options.categories,
     author: options.author,
+    filter: options.filter,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
   });
 
@@ -592,6 +606,7 @@ async function searchHybridWithHydration(
           until: temporalRange.until,
           categories: options.categories,
           author: options.author,
+          filter: options.filter,
           relPathPrefix: options.retrievalScope?.relPathPrefix,
         })
       )
@@ -767,6 +782,7 @@ async function searchHybridWithHydration(
     {
       collection: options.collection,
       includeSimilar: vectorAvailable,
+      eligibility: vectorEligibility,
       limit,
       candidateLimit,
       disabled: options.graph === false || options.noGraph === true,
@@ -778,6 +794,7 @@ async function searchHybridWithHydration(
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      filter: options.filter,
     },
     hydration
   );
@@ -1355,6 +1372,9 @@ async function searchHybridWithHydration(
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      ...(options.filter
+        ? { warnings: await typedMetadataWarnings(store, query, options) }
+        : {}),
       candidateLimit,
       graphExpansion: {
         enabled: graphExpansion.meta.enabled,

package/src/pipeline/search.ts

@@ -16,6 +16,7 @@ import type {
 } from "./types";
 
 import { projectRecordEvidenceMetadata } from "../core/record-metadata";
+import { normalizeMetadataPredicate } from "../core/typed-metadata";
 import { getContentBatch } from "../store/content-batch";
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
@@ -26,6 +27,7 @@ import {
 } from "./content-type-boost";
 import { attachSearchResultEgressLineage } from "./egress-lineage";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
+import { typedMetadataWarnings } from "./filters";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
@@ -176,6 +178,11 @@ export async function searchBm25(
   query: string,
   options: SearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  if (options.filter !== undefined)
+    options = {
+      ...options,
+      filter: normalizeMetadataPredicate(options.filter),
+    };
   const traceStartedAt = options.traceSession ? performance.now() : 0;
   const limit = options.limit ?? 20;
   const minScore = options.minScore ?? 0;
@@ -213,6 +220,7 @@ export async function searchBm25(
     until: temporalRange.until,
     categories: options.categories,
     author: options.author,
+    filter: options.filter,
     memoryScopesAny: options.memoryFilter?.scopes,
     excludeSuperseded: options.memoryFilter?.excludeSuperseded,
   });
@@ -482,6 +490,9 @@ export async function searchBm25(
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      ...(options.filter
+        ? { warnings: await typedMetadataWarnings(store, query, options) }
+        : {}),
       queryLanguage,
     },
   };

package/src/pipeline/types.ts

@@ -1,10 +1,11 @@
-import type { NormalizedContentTypeRule } from "../config/content-types";
 /**
  * Search pipeline types.
  * Defines SearchPipelinePort and related types for search operations.
  *
  * @module src/pipeline/types
  */
+
+import type { NormalizedContentTypeRule } from "../config/content-types";
 import type {
   ContextCapsuleV1,
   ContextCapsuleVerification,
@@ -12,6 +13,7 @@ import type {
 import type { EgressLineage } from "../core/egress-provenance";
 import type { RecordEvidenceMetadata } from "../core/record-metadata";
 import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
+import type { MetadataPredicate } from "../core/typed-metadata";
 import type { InferenceOptions } from "../llm/types";
 import type { StoreResult } from "../store/types";
 import type { ClaimVerificationResult } from "./claim-verification";
@@ -100,6 +102,8 @@ export type SearchMode = "bm25" | "vector" | "hybrid" | "bm25_only";
 
 /** Search metadata */
 export interface SearchMeta {
+  /** Typed-filter coverage limitations; absence does not certify model quality. */
+  warnings?: { code: string; message: string }[];
   query: string;
   mode: SearchMode;
   expanded?: boolean;
@@ -173,6 +177,8 @@ export interface SearchResults {
 
 /** Common options for all search commands */
 export interface SearchOptions extends InferenceOptions {
+  /** Type-strict custom metadata predicate, applied before candidate limits. */
+  filter?: MetadataPredicate;
   /** Internal receipt seam; never serialized or included in public schemas. */
   traceSession?: RetrievalTraceSession;
   /** Trusted, already-resolved project affinity; never accepts raw roots. */

package/src/pipeline/vsearch.ts

@@ -1,10 +1,11 @@
-import type { Config } from "../config/types";
 /**
  * Vector search pipeline.
  * Wraps VectorIndexPort.searchNearest() to produce SearchResults.
  *
  * @module src/pipeline/vsearch
  */
+
+import type { Config } from "../config/types";
 import type { EmbeddingPort } from "../llm/types";
 import type { DocumentRow, StorePort } from "../store/types";
 import type { VectorIndexPort } from "../store/vector/types";
@@ -12,6 +13,7 @@ import type { SearchOptions, SearchResult, SearchResults } from "./types";
 
 import { normalizeContentTypes } from "../config/content-types";
 import { projectRecordEvidenceMetadata } from "../core/record-metadata";
+import { normalizeMetadataPredicate } from "../core/typed-metadata";
 import {
   assertInferenceActive,
   assertInferenceResult,
@@ -29,6 +31,7 @@ import {
 import { formatQueryForEmbedding } from "./contextual";
 import { attachSearchResultEgressLineage } from "./egress-lineage";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
+import { typedMetadataWarnings, typedMetadataFilterReason } from "./filters";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
@@ -93,6 +96,11 @@ export async function searchVectorWithEmbedding(
   queryEmbedding: Float32Array,
   options: SearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  if (options.filter !== undefined)
+    options = {
+      ...options,
+      filter: normalizeMetadataPredicate(options.filter),
+    };
   return withInferenceScope(options, () =>
     searchVectorWithEmbeddingOwned(deps, query, queryEmbedding, options)
   );
@@ -162,6 +170,7 @@ async function searchVectorWithEmbeddingOwned(
         until: temporalRange.until,
         categories: options.categories,
         author: options.author,
+        filter: options.filter,
         exclude: options.exclude,
         language: options.lang,
       },
@@ -198,6 +207,7 @@ async function searchVectorWithEmbeddingOwned(
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      filter: options.filter,
       mirrorHashes: uniqueHashes,
     });
 
@@ -526,6 +536,9 @@ async function searchVectorWithEmbeddingOwned(
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      ...(options.filter
+        ? { warnings: await typedMetadataWarnings(store, query, options) }
+        : {}),
       queryLanguage,
     },
   };
@@ -552,6 +565,11 @@ export async function searchVector(
   query: string,
   options: SearchOptions = {}
 ): Promise<ReturnType<typeof ok<SearchResults>>> {
+  if (options.filter !== undefined)
+    options = {
+      ...options,
+      filter: normalizeMetadataPredicate(options.filter),
+    };
   return withInferenceScope(options, () =>
     searchVectorOwned(deps, query, options)
   );
@@ -639,6 +657,7 @@ interface DocumentMapOptions {
   until?: string;
   categories?: string[];
   author?: string;
+  filter?: SearchOptions["filter"];
   mirrorHashes?: string[];
 }
 
@@ -731,6 +750,7 @@ async function buildDocumentMap(
 
   for (const doc of activeDocs) {
     assertInferenceActive();
+    if (typedMetadataFilterReason(doc, options.filter)) continue;
     const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
     if (
       options.relPathPrefix !== undefined &&

package/src/sdk/client.ts

@@ -1,9 +1,10 @@
-import { mkdir } from "node:fs/promises";
 /**
  * GNO SDK client.
  *
  * @module src/sdk/client
  */
+
+import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import type { Config } from "../config/types";
@@ -152,6 +153,10 @@ import {
 } from "../core/sections";
 import { normalizeStructuredQueryInput } from "../core/structured-query";
 import { parseAndValidateTagFilter } from "../core/tags";
+import {
+  normalizeMetadataPredicate,
+  type MetadataPredicate,
+} from "../core/typed-metadata";
 import { writeLeasePath } from "../core/write-lease";
 import {
   defaultSyncService,
@@ -206,6 +211,17 @@ interface RuntimePorts {
   vectorIndex: VectorIndexPort | null;
 }
 
+const normalizeSdkMetadataFilter = (value: unknown): MetadataPredicate => {
+  try {
+    return normalizeMetadataPredicate(value);
+  } catch (error) {
+    throw sdkError(
+      "VALIDATION",
+      `filter: ${error instanceof Error ? error.message : "Invalid predicate"}`
+    );
+  }
+};
+
 const resolveSdkProjectAffinity = async (
   config: Config,
   projectHints: readonly string[] | undefined
@@ -640,6 +656,8 @@ class GnoClientImpl implements GnoClient {
     let traceSession: RetrievalTraceSession | null = null;
     try {
       const { projectHints, ...searchOptions } = options;
+      if (searchOptions.filter !== undefined)
+        searchOptions.filter = normalizeSdkMetadataFilter(searchOptions.filter);
       const projectAffinity = await resolveSdkProjectAffinity(
         this.config,
         projectHints
@@ -695,6 +713,8 @@ class GnoClientImpl implements GnoClient {
 
     try {
       const { projectHints, ...searchOptions } = options;
+      if (searchOptions.filter !== undefined)
+        searchOptions.filter = normalizeSdkMetadataFilter(searchOptions.filter);
       const projectAffinity = await resolveSdkProjectAffinity(
         this.config,
         projectHints
@@ -826,6 +846,8 @@ class GnoClientImpl implements GnoClient {
 
     try {
       const { projectHints, ...queryOptions } = options;
+      if (queryOptions.filter !== undefined)
+        queryOptions.filter = normalizeSdkMetadataFilter(queryOptions.filter);
       const projectAffinity = await resolveSdkProjectAffinity(
         this.config,
         projectHints
@@ -954,6 +976,8 @@ class GnoClientImpl implements GnoClient {
     const hydration = new RequestHydration(this.store);
     try {
       const { projectHints, ...askOptions } = options;
+      if (askOptions.filter !== undefined)
+        askOptions.filter = normalizeSdkMetadataFilter(askOptions.filter);
       const projectAffinity = await resolveSdkProjectAffinity(
         this.config,
         projectHints
@@ -1046,6 +1070,7 @@ class GnoClientImpl implements GnoClient {
             until: options.until,
             categories: options.categories,
             author: options.author,
+            filter: askOptions.filter,
             tagsAll: options.tagsAll,
             tagsAny: options.tagsAny,
             exclude: options.exclude,
@@ -1151,6 +1176,8 @@ class GnoClientImpl implements GnoClient {
   async context(input: GnoContextInput): Promise<GnoContextResult> {
     this.assertOpen();
     const { projectHints, ...contextInput } = input;
+    if (contextInput.filter !== undefined)
+      contextInput.filter = normalizeSdkMetadataFilter(contextInput.filter);
     validateContextCapsuleBuildInput(
       { ...contextInput, indexName: this.indexName },
       this.indexName,
@@ -1189,6 +1216,7 @@ class GnoClientImpl implements GnoClient {
             until: input.until,
             categories: input.categories,
             author: input.author,
+            filter: contextInput.filter,
             graph: input.graph,
             candidateLimit: input.candidateLimit,
             queryModes: input.queryModes,

package/src/sdk/index.ts

@@ -80,6 +80,10 @@ export type {
   SectionTargetCreateSelector,
   SectionTargetResolveResult,
   SectionTargetV1,
+  MetadataPredicate,
+  MetadataScalar,
+  TypedMetadata,
+  TypedValue,
   MemoryCandidate,
   MemoryFact,
   MemoryRecallReceipt,

package/src/sdk/types.ts

@@ -435,3 +435,10 @@ export interface GnoClient {
   ): Promise<SectionTargetResolveResult>;
   close(): Promise<void>;
 }
+
+export type {
+  MetadataPredicate,
+  MetadataScalar,
+  TypedMetadata,
+  TypedValue,
+} from "../core/typed-metadata";

package/src/serve/context-capsule.ts

@@ -126,6 +126,7 @@ export const handleContextBuild = async (
         since: input.since,
         until: input.until,
         categories: input.categories,
+        filter: input.filter,
         author: input.author,
         graph: input.graph,
         candidateLimit: input.candidateLimit,

package/src/serve/public/app.tsx

@@ -179,7 +179,7 @@ function AppContent({
           <div className="ornament mx-auto mb-4 max-w-[8rem] text-muted-foreground/20">
             <span className="text-[10px]">◆</span>
           </div>
-          <div className="flex items-center justify-center gap-5 text-muted-foreground/60">
+          <div className="flex flex-wrap items-center justify-center gap-x-3 gap-y-2 px-4 text-muted-foreground/60 sm:gap-x-5">
             <button
               className="transition-colors duration-300 hover:text-primary"
               onClick={() => navigate("/collections")}