@stigmer/server 3.14.0-dev.20260910084630

package/src/query/search/controller.ts

@@ -0,0 +1,93 @@
+/**
+ * Search controller — ports
+ * pkg/query/search/controller/search_controller.go: the thin adapter
+ * between ConnectRPC and the SearchHandler, owning the error-to-status
+ * mapping.
+ *
+ * The mapping is Go's string-contains heuristic ported byte-for-byte
+ * (toGRPCError): handler texts containing "validation failed", "invalid",
+ * or "exceeds maximum" answer InvalidArgument CARRYING the wrapped text;
+ * everything else is sanitized to Internal "search failed"
+ * (stigmer/stigmer#478 — the raw error is server internals, logged here
+ * at the boundary, never on the wire). The conformance suite pins the
+ * codes only (ratified guard P2); the texts ride the parity register's
+ * protovalidate-es watch item.
+ *
+ * SearchService carries no api_resource_kind option and
+ * is_skip_authorization (cross-aggregate CQRS read) — the apiresource
+ * interceptor injects nothing and the auth slot is a pass-through, both
+ * verified; no interceptor changes ride this port.
+ *
+ * Proven by search.conformance.test.ts (CONFORMANCE_TARGET=local) and
+ * __tests__/handler.test.ts's mapping arms.
+ */
+import type { ConnectRouter } from "@connectrpc/connect";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import type {
+  SearchRequest,
+  SearchResponse,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import type { ConnectError } from "@connectrpc/connect";
+import type { SearchHandler } from "./handler.js";
+
+export interface SearchControllerDeps {
+  readonly handler: SearchHandler;
+  readonly logger: Logger;
+}
+
+/** Registers the SearchService on the router (routes stage). */
+export function registerSearchServices(
+  router: ConnectRouter,
+  deps: SearchControllerDeps,
+): void {
+  router.service(SearchService, {
+    search: (request, ctx) => search(deps, request, callerIdentityOf(ctx)),
+  });
+}
+
+async function search(
+  deps: SearchControllerDeps,
+  request: SearchRequest,
+  identity: CallerIdentity,
+): Promise<SearchResponse> {
+  deps.logger.debug("SearchService.Search called", {
+    kinds: request.kinds.map((kind) => ApiResourceKind[kind] ?? String(kind)),
+    query: request.query,
+    org: request.org,
+    exclude_public: request.excludePublic,
+  });
+
+  try {
+    return await deps.handler.handle(request, identity);
+  } catch (error) {
+    deps.logger.error("Search failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw toGrpcError(error);
+  }
+}
+
+/**
+ * Go toGRPCError: substring-match validation texts to InvalidArgument
+ * (carrying the wrapped text), default everything else to the sanitized
+ * Internal (#478) — the call site above has already logged the full
+ * error.
+ */
+function toGrpcError(error: unknown): ConnectError {
+  const text = error instanceof Error ? error.message : String(error);
+  if (
+    text.includes("validation failed") ||
+    text.includes("invalid") ||
+    text.includes("exceeds maximum")
+  ) {
+    return invalidArgumentError(text);
+  }
+  return internalError(error, "search failed");
+}

package/src/query/search/criteria.ts

@@ -0,0 +1,204 @@
+/**
+ * Search criteria value object — ports
+ * pkg/query/search/valueobject/search_criteria.go: validated, normalized,
+ * immutable search parameters and the three-mode contract (list / search /
+ * discover).
+ *
+ * The searchable-kind set is DERIVED from the proto kind_meta extension
+ * (not_search_indexed: false, tier != cloud_only) — Go's
+ * SearchIndexedKinds() posture since stigmer/stigmer#439, where hand-copied
+ * kind lists drifted from the proto and from each other. Go still carries a
+ * hand map (SearchableKinds) pinned to the derivation by an invariant test;
+ * here the derivation IS the set — parity by construction, one source. The
+ * registry unit test pins the registered extractors against this same
+ * derivation (the #439 invariant's TS home).
+ *
+ * kinds are kept VERBATIM from the request; filtering to the searchable set
+ * happens in effectiveKinds(). Keeping the raw request is what
+ * distinguishes "no kinds requested" (discover mode) from "kinds requested
+ * but none searchable" (empty result) — collapsing the two at construction
+ * made kind-targeted requests for non-searchable kinds silently degrade to
+ * discover mode and return every other kind's resources
+ * (stigmer/stigmer#440).
+ *
+ * Proven by __tests__/criteria.test.ts (Go's tables case-for-case) and
+ * search.conformance.test.ts on local.
+ */
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  ResourceTier,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { goTrimSpace } from "../../gocompat/trim.js";
+import { getKindMeta } from "../../pipeline/apiresource-meta.js";
+
+/** Go DefaultPageSize. */
+export const DEFAULT_PAGE_SIZE = 20;
+/** Go MaxPageSize. */
+export const MAX_PAGE_SIZE = 100;
+/** Go MaxQueryLength (the proto's max_len twin; see newSearchCriteria). */
+export const MAX_QUERY_LENGTH = 500;
+
+let searchIndexedKindsCache: readonly ApiResourceKind[] | undefined;
+let searchableKindSetCache: ReadonlySet<ApiResourceKind> | undefined;
+
+/**
+ * Go SearchIndexedKinds(): every kind this edition's search read side
+ * serves — kind_meta declares it search-indexed and servable outside the
+ * cloud. Sorted ascending by enum value, exactly Go's sort. Kinds whose
+ * kind_meta cannot be read are skipped (Go's contract; the registry unit
+ * test separately fails on such a defect).
+ */
+export function searchIndexedKinds(): readonly ApiResourceKind[] {
+  if (searchIndexedKindsCache === undefined) {
+    const kinds: ApiResourceKind[] = [];
+    for (const value of ApiResourceKindSchema.values) {
+      const kind = value.number as ApiResourceKind;
+      if (kind === ApiResourceKind.api_resource_kind_unknown) {
+        continue;
+      }
+      let meta;
+      try {
+        meta = getKindMeta(kind);
+      } catch {
+        continue;
+      }
+      if (meta.notSearchIndexed || meta.tier === ResourceTier.cloud_only) {
+        continue;
+      }
+      kinds.push(kind);
+    }
+    kinds.sort((a, b) => a - b);
+    searchIndexedKindsCache = kinds;
+  }
+  return searchIndexedKindsCache;
+}
+
+/** The derivation as a Set — effectiveKinds' filter (Go SearchableKinds). */
+function searchableKindSet(): ReadonlySet<ApiResourceKind> {
+  if (searchableKindSetCache === undefined) {
+    searchableKindSetCache = new Set(searchIndexedKinds());
+  }
+  return searchableKindSetCache;
+}
+
+/**
+ * Immutable, validated search parameters. Construct via newSearchCriteria.
+ */
+export class SearchCriteria {
+  private constructor(
+    private readonly requestedKinds: readonly ApiResourceKind[],
+    private readonly queryText: string,
+    private readonly orgFilterValue: string,
+    private readonly excludePublicFlag: boolean,
+    private readonly crossOrgPublicFlag: boolean,
+    private readonly pageNumberValue: number,
+    private readonly pageSizeValue: number,
+  ) {}
+
+  /**
+   * Go NewSearchCriteria: trims query and org, clamps pagination
+   * (num < 1 → 1; size < 1 → default 20; size > 100 → 100), keeps kinds
+   * verbatim. Throws on an over-length query — defensive twin of the
+   * proto's max_len 500, which the protovalidate interceptor answers
+   * first on the wire (Go carries the same unreachable guard).
+   *
+   * Trimming is goTrimSpace, NOT String.trim: hasQuery() decides
+   * list-vs-search mode from the trimmed query, and the two trim sets
+   * disagree on U+FEFF/U+0085 — a BOM-only query would read as list mode
+   * (return everything) where Go runs an empty-match search (the #8 BOM
+   * divergence class, caught again by this sub-project's parity panel).
+   */
+  static create(
+    kinds: readonly ApiResourceKind[],
+    query: string,
+    orgFilter: string,
+    excludePublic: boolean,
+    crossOrgPublic: boolean,
+    pageNumber: number,
+    pageSize: number,
+  ): SearchCriteria {
+    const normalizedQuery = goTrimSpace(query);
+    if (normalizedQuery.length > MAX_QUERY_LENGTH) {
+      throw new Error(
+        `search query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`,
+      );
+    }
+    return new SearchCriteria(
+      [...kinds],
+      normalizedQuery,
+      goTrimSpace(orgFilter),
+      excludePublic,
+      crossOrgPublic,
+      pageNumber < 1 ? 1 : pageNumber,
+      pageSize < 1 ? DEFAULT_PAGE_SIZE : Math.min(pageSize, MAX_PAGE_SIZE),
+    );
+  }
+
+  /** The requested kinds VERBATIM — including non-searchable ones. */
+  kinds(): readonly ApiResourceKind[] {
+    return [...this.requestedKinds];
+  }
+
+  query(): string {
+    return this.queryText;
+  }
+
+  orgFilter(): string {
+    return this.orgFilterValue;
+  }
+
+  excludePublic(): boolean {
+    return this.excludePublicFlag;
+  }
+
+  crossOrgPublic(): boolean {
+    return this.crossOrgPublicFlag;
+  }
+
+  pageNumber(): number {
+    return this.pageNumberValue;
+  }
+
+  pageSize(): number {
+    return this.pageSizeValue;
+  }
+
+  /**
+   * Discover mode = NO kinds requested. A request naming only
+   * non-searchable kinds is NOT discover mode — it searches nothing.
+   */
+  isDiscoverMode(): boolean {
+    return this.requestedKinds.length === 0;
+  }
+
+  /** False = list mode (created_at ordering, score pinned 1.0). */
+  hasQuery(): boolean {
+    return this.queryText !== "";
+  }
+
+  hasOrgFilter(): boolean {
+    return this.orgFilterValue !== "";
+  }
+
+  /**
+   * Go EffectiveKinds: discover mode → all searchable kinds; otherwise
+   * the requested kinds filtered to the searchable set — silently
+   * dropping non-searchable ones (the forward-compatibility contract on
+   * SearchRequest.kinds). The result may be EMPTY: the caller answers
+   * emptiness, never a discover fallback (stigmer/stigmer#440).
+   */
+  effectiveKinds(): readonly ApiResourceKind[] {
+    if (this.requestedKinds.length === 0) {
+      return searchIndexedKinds();
+    }
+    const searchable = searchableKindSet();
+    return this.requestedKinds.filter((kind) => searchable.has(kind));
+  }
+
+  /** Zero-indexed row offset for the page (Go Offset). */
+  offset(): number {
+    return (this.pageNumberValue - 1) * this.pageSizeValue;
+  }
+}

package/src/query/search/extractor.ts

@@ -0,0 +1,93 @@
+/**
+ * Searchable-extractor contract — ports the query side of
+ * pkg/query/search/extractor/extractor.go (the index side,
+ * SearchIndexExtractor, shipped with #4 in pipeline/steps/index-search.ts;
+ * this module extends it, mirroring Go's single interface).
+ *
+ * Go duplicates the ToSearchResult body 13× (protobuf structs cannot share
+ * methods); the OUTPUT is formulaic — metadata identity, spec-audit
+ * timestamps with zero-Timestamp defaults, per-kind summary — so it ports
+ * ONCE as buildSearchResult, parameterized by what actually varies (kind,
+ * summary, icon). Byte-visible output is identical; the per-kind summary
+ * sources are pinned in each domain's search-extractor.ts and in the
+ * conformance suite (D4 #14 DD-C, owner-ratified).
+ *
+ * Proven by search.conformance.test.ts (CONFORMANCE_TARGET=local) and
+ * the registry/extractor unit tests.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage, Message } from "@bufbuild/protobuf";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { SearchResultSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import type { SearchIndexExtractor } from "../../pipeline/steps/index-search.js";
+
+/**
+ * The full extractor contract (Go SearchableExtractor): the #4 index side
+ * plus the query side this sub-project adds. One extractor per searchable
+ * kind, registered in registry.ts.
+ */
+export interface SearchableExtractor extends SearchIndexExtractor {
+  /** Go Kind(): the kind this extractor serves. */
+  readonly kind: ApiResourceKind;
+  /** Go NewEmptyProto(): the schema RebuildIndex unmarshals rows with. */
+  readonly schema: DescMessage;
+  /**
+   * Go GetSearchSummary(): the display description for search results.
+   * The source field varies by kind (see each domain's extractor header);
+   * truncation is a presentation concern — return the full text.
+   */
+  getSearchSummary(resource: Message): string;
+  /**
+   * Go ToSearchResult(): the wire projection for one hit. Returns
+   * undefined when the resource carries no metadata (Go returns nil) —
+   * the caller skips the row.
+   */
+  toSearchResult(resource: Message, score: number): SearchResult | undefined;
+}
+
+/**
+ * The formulaic SearchResult assembly every Go extractor repeats:
+ * metadata identity + qualified slug, spec-audit timestamps defaulting to
+ * the ZERO Timestamp when unstamped (Go sets &timestamppb.Timestamp{}),
+ * and the caller's summary/icon/score.
+ */
+export function buildSearchResult(params: {
+  readonly kind: ApiResourceKind;
+  readonly metadata: ApiResourceMetadata | undefined;
+  readonly summary: string;
+  readonly score: number;
+  readonly createdAt: Timestamp | undefined;
+  readonly updatedAt: Timestamp | undefined;
+  readonly iconUrl?: string;
+}): SearchResult | undefined {
+  const metadata = params.metadata;
+  if (metadata === undefined) {
+    return undefined;
+  }
+  return create(SearchResultSchema, {
+    kind: params.kind,
+    id: metadata.id,
+    name: metadata.name,
+    slug: metadata.slug,
+    org: metadata.org,
+    qualifiedSlug: buildQualifiedSlug(metadata.org, metadata.slug),
+    description: params.summary,
+    visibility: metadata.visibility,
+    tags: metadata.tags,
+    score: params.score,
+    iconUrl: params.iconUrl ?? "",
+    createdAt: params.createdAt ?? create(TimestampSchema),
+    updatedAt: params.updatedAt ?? create(TimestampSchema),
+  });
+}
+
+/** Go buildQualifiedSlug: "org/slug", or the bare slug when org is empty. */
+function buildQualifiedSlug(org: string, slug: string): string {
+  return org === "" ? slug : `${org}/${slug}`;
+}

package/src/query/search/handler.ts

@@ -0,0 +1,125 @@
+/**
+ * Search handler — ports pkg/query/search/handler/search_handler.go: the
+ * plain 4-step CQRS pipeline (validate → criteria → store → response).
+ * Deliberately NOT the domain pipeline library — Go's query side doesn't
+ * use its pipeline either; queries have no persist/audit lifecycle.
+ *
+ * Step 1's protovalidate run is Go's defensive twin: the interceptor
+ * chain has already validated the request on every wire and in-process
+ * path (chain position 3; Go server.go:246 "protovalidate runs first"),
+ * so this arm is unreachable from the wire — ported because Go carries
+ * it, and because the handler contract ("Handle validates") must not
+ * silently depend on the caller's chain.
+ *
+ * Proven by __tests__/handler.test.ts and search.conformance.test.ts on
+ * local.
+ */
+import { create } from "@bufbuild/protobuf";
+import { createValidator } from "@bufbuild/protovalidate";
+import type { Validator } from "@bufbuild/protovalidate";
+
+import {
+  SearchRequestSchema,
+  SearchResponseSchema,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type {
+  SearchRequest,
+  SearchResponse,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import { apiResourceKindName } from "../../store/proto-fields.js";
+import { SearchCriteria } from "./criteria.js";
+import type { SearchPagedResult } from "./paged-result.js";
+import type { SearchQueryStore } from "./query-store.js";
+
+export class SearchHandler {
+  private readonly validator: Validator;
+
+  constructor(
+    private readonly store: SearchQueryStore,
+    private readonly logger: Logger,
+    private readonly listReadScope: ListReadScope | undefined,
+  ) {
+    this.validator = createValidator();
+  }
+
+  /**
+   * Go Handle: validate → build criteria → execute → build response.
+   * Errors carry Go's exact wrap prefixes — the controller's error
+   * mapping string-matches them (#478 sanitization contract).
+   *
+   * With a composed ListReadScope (20260830.01, census lane 21) the
+   * store read carries a per-effective-kind authorized-id map — the Java
+   * SearchHandler's QueryAuthorizedIds step, with its crossOrgPublic
+   * bypass preserved verbatim (public-widened discovery is
+   * visibility-filtered by the engine, FGA never consulted). A scope
+   * failure propagates — the controller's default arm answers the
+   * sanitized Internal, never a silently unscoped result.
+   */
+  async handle(
+    request: SearchRequest,
+    identity: CallerIdentity,
+  ): Promise<SearchResponse> {
+    const validation = this.validator.validate(SearchRequestSchema, request);
+    if (validation.kind !== "valid") {
+      throw new Error(`validation failed: ${validation.error.message}`);
+    }
+
+    let criteria: SearchCriteria;
+    try {
+      criteria = SearchCriteria.create(
+        request.kinds,
+        request.query,
+        request.org,
+        request.excludePublic,
+        request.crossOrgPublic,
+        request.page?.num ?? 0,
+        request.page?.size ?? 0,
+      );
+    } catch (error) {
+      throw new Error(
+        `build criteria failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+
+    let authorizedIdsByKind: Map<string, ReadonlySet<string>> | undefined;
+    if (this.listReadScope !== undefined && !criteria.crossOrgPublic()) {
+      authorizedIdsByKind = new Map<string, ReadonlySet<string>>();
+      for (const kind of criteria.effectiveKinds()) {
+        authorizedIdsByKind.set(
+          apiResourceKindName(kind),
+          await this.listReadScope.authorizedResourceIds(identity, kind),
+        );
+      }
+    }
+
+    let result: SearchPagedResult;
+    try {
+      result = await this.store.search(criteria, authorizedIdsByKind);
+    } catch (error) {
+      throw new Error(
+        `search failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+
+    const response = create(SearchResponseSchema, {
+      entries: [...result.results],
+      countsByKind: { ...result.countsByKind },
+      totalCount: result.totalCount,
+      totalPages: result.totalPages,
+    });
+
+    this.logger.debug("Search completed", {
+      results: response.entries.length,
+      total: response.totalCount,
+      has_query: criteria.hasQuery(),
+    });
+
+    return response;
+  }
+}

package/src/query/search/paged-result.ts

@@ -0,0 +1,54 @@
+/**
+ * Paged search result — ports
+ * pkg/query/search/valueobject/search_paged_result.go: the page of
+ * SearchResult projections plus the counts the response carries.
+ * totalPages = ceil(totalCount / pageSize), 0 when pageSize is 0 (the
+ * EmptyResult shape). Negative totals/page sizes are internal-contract
+ * violations and throw, as Go's constructor errors.
+ *
+ * Go defensively copies on construction AND on every accessor; here the
+ * readonly types carry the same do-not-mutate contract without the
+ * per-call copies (TS's compile-time twin of Go's runtime discipline).
+ */
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+export interface SearchPagedResult {
+  readonly results: readonly SearchResult[];
+  /** Total matches per kind NAME string — totals, not page counts. */
+  readonly countsByKind: Readonly<Record<string, number>>;
+  readonly totalCount: number;
+  readonly totalPages: number;
+}
+
+const EMPTY_RESULT: SearchPagedResult = {
+  results: [],
+  countsByKind: {},
+  totalCount: 0,
+  totalPages: 0,
+};
+
+/** Go EmptyResult(): the shared empty page. */
+export function emptyResult(): SearchPagedResult {
+  return EMPTY_RESULT;
+}
+
+/** Go NewSearchPagedResult. */
+export function newSearchPagedResult(
+  results: readonly SearchResult[],
+  countsByKind: Readonly<Record<string, number>>,
+  totalCount: number,
+  pageSize: number,
+): SearchPagedResult {
+  if (totalCount < 0) {
+    throw new Error(`totalCount cannot be negative: ${totalCount}`);
+  }
+  if (pageSize < 0) {
+    throw new Error(`pageSize cannot be negative: ${pageSize}`);
+  }
+  return {
+    results,
+    countsByKind,
+    totalCount,
+    totalPages: pageSize > 0 ? Math.ceil(totalCount / pageSize) : 0,
+  };
+}