@sixb/core 0.1.2 → 0.1.4

package/src/objects/query/executor.ts

@@ -7,6 +7,7 @@ import type {
   ExpandedLinkValue,
   ExpandedObjectRow,
   FacetObjectsResult,
+  ObjectBatchKey,
   ObjectFacetRequest,
   ObjectFacetResult,
   ObjectLinkRow,
@@ -16,6 +17,7 @@ import type {
   ObjectStorage,
   QueryObjectsResult,
 } from "../../storage"
+import { linkBatchKey, objectBatchKey } from "../../storage"
 import {
   ObjectQueryExecutionError,
   ObjectQueryPlanningError,
@@ -52,6 +54,7 @@ export interface QueryExecutorOptions
   storage: ObjectStorage
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
   maxFacetLimit?: number
   /**
    * Per-parent cap on how many links a single `expand` hydrates, applied as a
@@ -132,6 +135,7 @@ export async function executeObjectQuery(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -199,6 +203,7 @@ export async function countObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -259,6 +264,7 @@ export async function existsObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -319,6 +325,7 @@ export async function facetObjects(
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
     normalize: false,
   })
   assertQueryViewable(validated, options)
@@ -435,6 +442,7 @@ function resolveExpansions(query: ObjectQuery, ctx: ExpansionResolutionContext):
       }
     }
     case "start":
+    case "refs":
       return query
     case "set":
       return {
@@ -555,6 +563,8 @@ function expandIncludeSubtypes(query: ObjectQuery, ontology: OntologyRegistry):
         inputs: objectTypeIds.map((objectTypeId) => ({ kind: "start", objectTypeId })),
       }
     }
+    case "refs":
+      return query
     case "filter":
     case "text":
     case "vector":
@@ -598,6 +608,8 @@ async function evaluateFallbackQuery(
   switch (query.kind) {
     case "start":
       return evaluateFallbackStart(projectId, query, options, maxRows)
+    case "refs":
+      return evaluateFallbackRefs(projectId, query, options)
     case "filter": {
       const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows)
       return completeFallbackEvaluation(
@@ -672,6 +684,23 @@ async function evaluateFallbackQuery(
   }
 }
 
+async function evaluateFallbackRefs(
+  projectId: string,
+  query: Extract<ObjectQuery, { kind: "refs" }>,
+  options: QueryExecutorOptions
+): Promise<FallbackEvaluation> {
+  const rows = await options.storage.getByPrimaryIdBatch({
+    projectId,
+    items: query.refs,
+  })
+  return completeFallbackEvaluation(
+    query.refs.flatMap((ref, order) => {
+      const row = rows.get(objectBatchKey(ref.objectTypeId, ref.primaryId))
+      return row ? [{ row, order }] : []
+    })
+  )
+}
+
 /**
  * A candidate neighbour for one parent under a single expansion: the object to
  * hydrate plus the metadata carried on the link edge. For outgoing expansions
@@ -769,7 +798,9 @@ async function collectOutgoingEdges(
   })
 
   return parents.map((parent) => {
-    const links = linksByKey.get(`${parent.objectTypeId}:${parent.primaryId}:${expansion.linkId}`)
+    const links = linksByKey.get(
+      linkBatchKey(parent.objectTypeId, parent.primaryId, expansion.linkId)
+    )
     if (!links) return []
     return links.map((link) => ({
       neighborTypeId: link.targetTypeId,
@@ -821,8 +852,8 @@ async function fetchExpansionTargets(
   projectId: string,
   edgesByParent: readonly ExpansionEdge[][],
   options: QueryExecutorOptions
-): Promise<Map<string, ObjectRow>> {
-  const seen = new Set<string>()
+): Promise<ReadonlyMap<ObjectBatchKey, ObjectRow>> {
+  const seen = new Set<ObjectBatchKey>()
   const items: { objectTypeId: string; primaryId: string }[] = []
   for (const edges of edgesByParent) {
     for (const edge of edges) {
@@ -841,10 +872,10 @@ async function fetchExpansionTargets(
 async function enrichExpansionTargets(
   projectId: string,
   trimmedByParent: readonly ExpansionEdge[][],
-  baseTargets: Map<string, ObjectRow>,
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>,
   expansion: ObjectExpansion,
   options: QueryExecutorOptions
-): Promise<Map<string, ObjectRow>> {
+): Promise<ReadonlyMap<ObjectBatchKey, ObjectRow>> {
   if (!expansion.expand || expansion.expand.length === 0) {
     return baseTargets
   }
@@ -862,7 +893,7 @@ async function enrichExpansionTargets(
   }
 
   const enriched = await hydrateExpansions(projectId, uniqueTargets, expansion.expand, options)
-  const enrichedByKey = new Map<string, ObjectRow>()
+  const enrichedByKey = new Map<ObjectBatchKey, ObjectRow>()
   for (const row of enriched) {
     enrichedByKey.set(targetKey(row.objectTypeId, row.primaryId), row)
   }
@@ -872,7 +903,7 @@ async function enrichExpansionTargets(
 function trimExpansionEdges(
   edges: readonly ExpansionEdge[],
   expansion: ObjectExpansion,
-  baseTargets: Map<string, ObjectRow>,
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>,
   options: QueryExecutorOptions
 ): ExpansionEdge[] {
   let ordered = edges
@@ -899,7 +930,7 @@ function compareExpansionEdges(
   left: ExpansionEdge,
   right: ExpansionEdge,
   fields: readonly ObjectQuerySortField[],
-  baseTargets: Map<string, ObjectRow>
+  baseTargets: ReadonlyMap<ObjectBatchKey, ObjectRow>
 ): number {
   const leftRow = baseTargets.get(targetKey(left.neighborTypeId, left.neighborId))
   const rightRow = baseTargets.get(targetKey(right.neighborTypeId, right.neighborId))
@@ -954,8 +985,8 @@ function toLinkValue(
   return rows
 }
 
-function targetKey(objectTypeId: string, id: string): string {
-  return `${objectTypeId}:${id}`
+function targetKey(objectTypeId: string, id: string): ObjectBatchKey {
+  return objectBatchKey(objectTypeId, id)
 }
 
 async function evaluateFallbackStart(
@@ -1300,7 +1331,7 @@ function facetValueSortKey(value: unknown): string {
 }
 
 function rowIdentityKey(row: ObjectRow): string {
-  return `${row.objectTypeId}:${row.primaryId}`
+  return objectBatchKey(row.objectTypeId, row.primaryId)
 }
 
 function encodePageOffset(offset: number): string {

package/src/objects/query/explain.ts

@@ -18,6 +18,7 @@ export interface ObjectQueryExplainOptions {
   normalize?: boolean
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
 }
 
 export interface ObjectQueryExplanation {
@@ -47,6 +48,7 @@ export function explainObjectQuery(
         ontology: options.ontology,
         maxLimit: options.maxLimit,
         maxPageSize: options.maxPageSize,
+        maxRefs: options.maxRefs,
         normalize: false,
       })
     : []
@@ -57,6 +59,7 @@ export function explainObjectQuery(
           ontology: options.ontology,
           maxLimit: options.maxLimit,
           maxPageSize: options.maxPageSize,
+          maxRefs: options.maxRefs,
           normalize: false,
         }).result
       : undefined
@@ -84,6 +87,14 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
         },
         children: [],
       }
+    case "refs":
+      return {
+        path,
+        kind: query.kind,
+        summary: `refs ${query.refs.length}`,
+        details: { refs: query.refs },
+        children: [],
+      }
     case "filter":
       return {
         path,

package/src/objects/query/index.ts

@@ -44,6 +44,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -56,6 +57,11 @@ export type {
   ObjectQueryVector,
   QueryScalarKind,
 } from "./ir"
+export type {
+  ExecuteObjectQueryLinksInput,
+  ExecuteObjectQueryLinksResult,
+} from "./links"
+export { executeObjectQueryLinks } from "./links"
 export { normalizeObjectQuery, normalizeObjectQueryPredicate } from "./normalize"
 export type {
   ObjectQueryPlan,

package/src/objects/query/ir.ts

@@ -5,6 +5,8 @@
  * storage backend. Providers can push down the subset they support, while the
  * core planner decides whether a bounded fallback is acceptable.
  */
+import type { ObjectRef } from "../../ontology/refs"
+
 export type ObjectQueryDirection = "outgoing" | "incoming"
 export type ObjectQuerySetOperation = "union" | "intersect" | "subtract"
 export type ObjectQuerySortDirection = "asc" | "desc"
@@ -21,6 +23,7 @@ export type QueryScalarKind =
 
 export type ObjectQuery =
   | ObjectQueryStart
+  | ObjectQueryRefs
   | ObjectQueryFilter
   | ObjectQueryText
   | ObjectQueryVector
@@ -38,6 +41,19 @@ export interface ObjectQueryStart {
   includeSubtypes?: boolean
 }
 
+/**
+ * Starts a query from an explicit, heterogeneous set of object identities.
+ *
+ * Unlike `start`, this source is intrinsically bounded. Providers can compile
+ * it natively for composition with the rest of the IR; core resolves it through
+ * `getByPrimaryIdBatch` when pushdown is unavailable. Normalization removes
+ * duplicate identities and orders the set canonically by type and primary id.
+ */
+export interface ObjectQueryRefs {
+  kind: "refs"
+  refs: readonly ObjectRef[]
+}
+
 export interface ObjectQueryFilter {
   kind: "filter"
   input: ObjectQuery

package/src/objects/query/links.ts

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto"
+import { isAllowed } from "../../authorization"
+import { stableJsonStringify } from "../../json"
+import {
+  type LinkDirection,
+  type ObjectBatchKey,
+  type ObjectLinkCursor,
+  type ObjectLinkRow,
+  type ObjectRow,
+  type ObjectStorage,
+  objectBatchKey,
+  objectLinkCursor,
+} from "../../storage"
+import { ObjectQueryExecutionError } from "./errors"
+import { executeObjectQuery, type QueryExecutorOptions } from "./executor"
+import type { ObjectQuery } from "./ir"
+import { normalizeObjectQuery } from "./normalize"
+import { validateObjectQuery } from "./validate"
+
+export interface ExecuteObjectQueryLinksInput {
+  projectId: string
+  query: ObjectQuery
+  direction?: LinkDirection
+  linkId?: string
+  includeObjects?: boolean
+  pageSize?: number
+  pageToken?: string
+}
+
+export interface ExecuteObjectQueryLinksResult {
+  objects: readonly ObjectRow[]
+  links: readonly ObjectLinkRow[]
+  hasMore: boolean
+  nextPageToken?: string
+}
+
+const MAX_LINK_QUERY_OBJECTS = 1_000
+const MAX_LINK_PAGE_SIZE = 1_000
+const DEFAULT_LINK_PAGE_SIZE = 100
+const LINK_PAGE_TOKEN_PREFIX = "link:v1:"
+
+/**
+ * Select a bounded object set with the query IR, then return physical links
+ * incident to that set. This is a separate terminal because edge rows and edge
+ * pagination are a different response contract from object-set queries.
+ */
+export async function executeObjectQueryLinks(
+  input: ExecuteObjectQueryLinksInput,
+  options: QueryExecutorOptions
+): Promise<ExecuteObjectQueryLinksResult> {
+  const direction = input.direction ?? "both"
+  if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_direction",
+      "direction must be 'outgoing', 'incoming', or 'both'",
+      "$.direction"
+    )
+  }
+  if (input.linkId !== undefined && input.linkId.length === 0) {
+    throw new ObjectQueryExecutionError("invalid_link_id", "linkId must not be empty", "$.linkId")
+  }
+
+  const pageSize = input.pageSize ?? DEFAULT_LINK_PAGE_SIZE
+  if (!Number.isInteger(pageSize) || pageSize <= 0 || pageSize > MAX_LINK_PAGE_SIZE) {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_page_size",
+      `pageSize must be an integer between 1 and ${MAX_LINK_PAGE_SIZE}`,
+      "$.pageSize"
+    )
+  }
+  const validated = validateObjectQuery(normalizeObjectQuery(input.query), {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
+    normalize: false,
+  })
+  assertLinkSelectorShape(validated.query)
+  const selectorQuery = validated.query
+  const pageScope = linkPageScope(input.projectId, selectorQuery, direction, input.linkId)
+  const cursor = decodeLinkPageToken(input.pageToken, pageScope)
+
+  // A root page already has an explicit result bound and must execute directly: nesting it under a
+  // probe limit would expose the provider's internal pageSize+1 row. All other selector shapes are
+  // capped here before the provider receives the selected identities.
+  const boundedSelector =
+    selectorQuery.kind === "page"
+      ? selectorQuery
+      : { kind: "limit" as const, limit: MAX_LINK_QUERY_OBJECTS + 1, input: selectorQuery }
+  const selection = await executeObjectQuery(
+    {
+      projectId: input.projectId,
+      query: boundedSelector,
+      includeTotal: false,
+    },
+    {
+      ...options,
+      maxLimit: Math.max(options.maxLimit ?? 1_000, MAX_LINK_QUERY_OBJECTS + 1),
+    }
+  )
+  if (selection.objects.length > MAX_LINK_QUERY_OBJECTS) {
+    throw new ObjectQueryExecutionError(
+      "link_query_object_limit_exceeded",
+      `Link query selected more than ${MAX_LINK_QUERY_OBJECTS} objects; add a limit or page node`,
+      "$.query"
+    )
+  }
+
+  const selected = selection.objects
+  if (selected.length === 0) {
+    return { objects: [], links: [], hasMore: false }
+  }
+
+  const endpointObjectTypeIds = visibleEndpointTypeIds(options)
+  const page = await options.storage.queryLinks({
+    projectId: input.projectId,
+    objectRefs: selected.map((row) => ({
+      objectTypeId: row.objectTypeId,
+      primaryId: row.primaryId,
+    })),
+    direction,
+    ...(input.linkId === undefined ? {} : { linkId: input.linkId }),
+    ...(endpointObjectTypeIds === undefined ? {} : { endpointObjectTypeIds }),
+    ...(cursor === undefined ? {} : { after: cursor }),
+    limit: pageSize,
+  })
+  const lastLink = page.links.at(-1)
+  let nextPageToken: string | undefined
+  if (page.hasMore) {
+    if (!lastLink) {
+      throw new Error("[Sixb] Object storage returned hasMore for an empty link page.")
+    }
+    nextPageToken = encodeLinkPageToken(objectLinkCursor(lastLink), pageScope)
+  }
+  const objects = input.includeObjects
+    ? await hydrateLinkQueryObjects(input.projectId, selected, page.links, options.storage)
+    : []
+
+  return {
+    objects,
+    links: page.links,
+    hasMore: page.hasMore,
+    ...(nextPageToken ? { nextPageToken } : {}),
+  }
+}
+
+interface EncodedLinkPageToken {
+  version: 1
+  scope: string
+  cursor: ObjectLinkCursor
+}
+
+function assertLinkSelectorShape(query: ObjectQuery, path = "$.query", root = true): void {
+  switch (query.kind) {
+    case "project":
+    case "expand":
+      throw new ObjectQueryExecutionError(
+        "link_selector_output_shape_not_supported",
+        `Link selectors do not support '${query.kind}' nodes; remove output shaping from the selector`,
+        path
+      )
+    case "page":
+      if (!root) {
+        throw new ObjectQueryExecutionError(
+          "link_selector_page_must_be_root",
+          "A page node in a link selector must be the outermost node",
+          path
+        )
+      }
+      assertLinkSelectorShape(query.input, `${path}.input`, false)
+      return
+    case "start":
+    case "refs":
+      return
+    case "set": {
+      for (const [index, input] of query.inputs.entries()) {
+        assertLinkSelectorShape(input, `${path}.inputs[${index}]`, false)
+      }
+      return
+    }
+    case "filter":
+    case "text":
+    case "vector":
+    case "traverse":
+    case "sort":
+    case "limit":
+      assertLinkSelectorShape(query.input, `${path}.input`, false)
+      return
+  }
+}
+
+function visibleEndpointTypeIds(options: QueryExecutorOptions): readonly string[] | undefined {
+  if (!options.authorization) return undefined
+  return options.ontology
+    .listObjectTypes()
+    .filter((objectType) =>
+      isAllowed(options.authorization, { kind: "object.view", objectTypeId: objectType.id })
+    )
+    .map((objectType) => objectType.id)
+}
+
+function objectIdentity(objectTypeId: string, primaryId: string): ObjectBatchKey {
+  return objectBatchKey(objectTypeId, primaryId)
+}
+
+function linkPageScope(
+  projectId: string,
+  query: ObjectQuery,
+  direction: LinkDirection,
+  linkId: string | undefined
+): string {
+  return createHash("sha256")
+    .update(
+      stableJsonStringify({
+        projectId,
+        query,
+        direction,
+        linkId: linkId ?? null,
+      })
+    )
+    .digest("base64url")
+}
+
+function encodeLinkPageToken(cursor: ObjectLinkCursor, scope: string): string {
+  const payload: EncodedLinkPageToken = { version: 1, scope, cursor }
+  return `${LINK_PAGE_TOKEN_PREFIX}${Buffer.from(JSON.stringify(payload)).toString("base64url")}`
+}
+
+function decodeLinkPageToken(
+  token: string | undefined,
+  expectedScope: string
+): ObjectLinkCursor | undefined {
+  if (token === undefined) return undefined
+  try {
+    if (!token.startsWith(LINK_PAGE_TOKEN_PREFIX)) throw new Error("invalid prefix")
+    const value = JSON.parse(
+      Buffer.from(token.slice(LINK_PAGE_TOKEN_PREFIX.length), "base64url").toString("utf8")
+    ) as unknown
+    if (
+      !isPlainObject(value) ||
+      value.version !== 1 ||
+      typeof value.scope !== "string" ||
+      !isObjectLinkCursor(value.cursor)
+    ) {
+      throw new Error("invalid cursor")
+    }
+    if (value.scope !== expectedScope) {
+      throw new Error("cursor scope mismatch")
+    }
+    return value.cursor
+  } catch {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_page_token",
+      "pageToken is not a valid object-links cursor",
+      "$.pageToken"
+    )
+  }
+}
+
+function isObjectLinkCursor(value: unknown): value is ObjectLinkCursor {
+  return (
+    Array.isArray(value) && value.length === 5 && value.every((part) => typeof part === "string")
+  )
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+async function hydrateLinkQueryObjects(
+  projectId: string,
+  selected: readonly ObjectRow[],
+  links: readonly ObjectLinkRow[],
+  storage: ObjectStorage
+): Promise<ObjectRow[]> {
+  const byIdentity = new Map(
+    selected.map((row) => [objectIdentity(row.objectTypeId, row.primaryId), row])
+  )
+  const orderedIdentities = selected.map((row) => objectIdentity(row.objectTypeId, row.primaryId))
+  const seenIdentities = new Set(orderedIdentities)
+  const missingRefs: { objectTypeId: string; primaryId: string }[] = []
+
+  for (const link of links) {
+    for (const ref of [
+      { objectTypeId: link.sourceTypeId, primaryId: link.sourceId },
+      { objectTypeId: link.targetTypeId, primaryId: link.targetId },
+    ]) {
+      const identity = objectIdentity(ref.objectTypeId, ref.primaryId)
+      if (seenIdentities.has(identity)) continue
+      seenIdentities.add(identity)
+      orderedIdentities.push(identity)
+      missingRefs.push(ref)
+    }
+  }
+
+  if (missingRefs.length > 0) {
+    const hydrated = await storage.getByPrimaryIdBatch({ projectId, items: missingRefs })
+    for (const ref of missingRefs) {
+      const row = hydrated.get(objectBatchKey(ref.objectTypeId, ref.primaryId))
+      if (row) byIdentity.set(objectIdentity(ref.objectTypeId, ref.primaryId), row)
+    }
+  }
+
+  return orderedIdentities.flatMap((identity) => {
+    const row = byIdentity.get(identity)
+    return row ? [row] : []
+  })
+}

package/src/objects/query/normalize.ts

@@ -22,6 +22,11 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
   switch (query.kind) {
     case "start":
       return { ...query }
+    case "refs":
+      return {
+        kind: "refs",
+        refs: uniqueRefs(query.refs),
+      }
     case "filter":
       return normalizeFilter(query.input, query.predicate)
     case "text":
@@ -63,7 +68,14 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
  * lands above another `expand` is merged into one.
  */
 function hoistExpand(query: ObjectQuery): ObjectQuery {
-  if (query.kind === "start" || query.kind === "set" || query.kind === "expand") return query
+  if (
+    query.kind === "start" ||
+    query.kind === "refs" ||
+    query.kind === "set" ||
+    query.kind === "expand"
+  ) {
+    return query
+  }
   if (query.input.kind !== "expand") return query
 
   const inner = query.input
@@ -236,6 +248,33 @@ function uniqueStrings(values: readonly string[]): string[] {
   return [...new Set(values)]
 }
 
+function uniqueRefs(
+  refs: readonly { objectTypeId: string; primaryId: string }[]
+): { objectTypeId: string; primaryId: string }[] {
+  const seen = new Set<string>()
+  const unique = refs.flatMap((ref) => {
+    const key = JSON.stringify([ref.objectTypeId, ref.primaryId])
+    if (seen.has(key)) return []
+    seen.add(key)
+    return [{ ...ref }]
+  })
+
+  // `refs` is an object-set source, not a positional batch response. Canonical
+  // identity order makes equivalent sets normalize identically and matches the
+  // default ordering used by provider query sources.
+  return unique.sort(
+    (left, right) =>
+      compareStrings(left.objectTypeId, right.objectTypeId) ||
+      compareStrings(left.primaryId, right.primaryId)
+  )
+}
+
+function compareStrings(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}
+
 function uniqueStringRecord(
   record: Readonly<Record<string, readonly string[]>>
 ): Record<string, string[]> {

package/src/objects/query/planner.ts

@@ -40,6 +40,7 @@ const DEFAULT_MAX_FALLBACK_ROWS = 1_000
 // accidental full scans.
 const fallbackNodeKinds = new Set<ObjectQuery["kind"]>([
   "start",
+  "refs",
   "filter",
   "sort",
   "limit",
@@ -195,6 +196,8 @@ function collectNodeProviderIssues(
         )
       }
       return
+    case "refs":
+      return
     case "filter":
       collectPredicateProviderIssues(query.predicate, `${path}.predicate`, capabilities, issues)
       collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues)
@@ -474,6 +477,7 @@ function collectFallbackNodeIssues(
 
   switch (query.kind) {
     case "start":
+    case "refs":
       return
     case "filter":
     case "limit":
@@ -512,6 +516,7 @@ function hasExplicitResultBound(query: ObjectQuery): boolean {
   switch (query.kind) {
     case "limit":
     case "page":
+    case "refs":
       return true
     case "start":
       return false