Expose authorized full-text facets and aggregation results through Table.search and REST #3845

Outcome

Return category counts and numeric-range facets alongside full-text results through an explicit Harper response contract. Facets describe the eligible matching set, independently of the returned hit page.

Ownership and dependency

Parent: Qualify native full-text filtering and catalog-scale operation for v5.4, which retains metadata adoption and catalog-scale qualification. This child owns the facet/aggregation response contract and its integration. Coordinate with the active filtering/sorting/count work; reuse its eligibility and planner decisions rather than implementing a second metadata projection or count engine.

Native aggregation capability does not by itself establish that Harper can safely expose its results. See Epic: Integrate schema-native full-text search into Harper for the product boundary.

Acceptance

• Define an opt-in Table.search and REST response shape for hits, facet buckets and aggregation metadata while preserving existing row-iterator/default response behavior. Resolve streaming/error representation before implementation.
• Start with explicitly declared category terms and numeric ranges. Specify missing/multivalued values, per-document versus occurrence counts, bucket order, range boundaries and selected-filter behavior. Nested aggregations are a separately qualified extension.
• Authorize all facet/filter fields before execution. Derive counts from the complete eligible match set after permissions, authoritative source-version and expiry checks. Post-hit filtering of a native aggregate cannot establish this.
• Reuse proven native aggregation only when projection coverage and source eligibility make it safe; otherwise use a correct bounded fallback or an explicit unsupported/budget error. Incomplete source eligibility or coverage must produce an explicit error rather than silent partial facets. Distinguish native terms approximation from incomplete source coverage; never label partial or approximate results exact.
• Expose applicable native terms uncertainty, truncation/completeness and omitted-bucket metadata without losing meaning. Define counts independently of hit offset/limit.
• Bound request depth, buckets, response bytes, memory and time under host policy. Specify cross-worker behavior and aggregate/hit consistency during concurrent writes, rebuilds and lag.
• Test Table.search and REST against an authoritative oracle: multiple pages, restricted/stale/expired rows, arrays/missing values, filters, ranges, high cardinality, fallback/error paths and concurrent updates.
• Document examples, accuracy/consistency guarantees, supported schema types and explicit limits. Retain parent catalog-scale and rollout gates.

Planning

Proposed feature; response API and release are not committed. Parent release scope does not commit this new child to a milestone. Priority P3: scoped extension under a P3 parent, with no demonstrated customer blocker. Effort High: response/iterator design, full-set eligibility and native/fallback integration. No customer-specific or security context.

Comment generated by kAIle (GPT-6)