@sixb/core 0.0.1

package/dist/chunk-2gpr6jsz.js

@@ -0,0 +1,1968 @@
+// @bun
+import {
+  ObjectQueryExecutionError,
+  ObjectQueryPlanningError,
+  ObjectQueryValidationError,
+  normalizeObjectQuery
+} from "./chunk-88ppkr54.js";
+import {
+  compareQueryScalarValues,
+  queryScalarValuesEqual
+} from "./chunk-6wetht33.js";
+import {
+  validatePropertyValue,
+  validateSchemaValue
+} from "./chunk-tsk2bxs3.js";
+import {
+  normalizeDecimalValue
+} from "./chunk-04b07a9q.js";
+import {
+  formatUnknownObjectTypeMessage
+} from "./chunk-dktq02ne.js";
+import {
+  assertAuthorized
+} from "./chunk-0fygrz37.js";
+// src/objects/query/planner.ts
+var DEFAULT_MAX_FALLBACK_ROWS = 1000;
+var fallbackNodeKinds = new Set([
+  "start",
+  "filter",
+  "sort",
+  "limit",
+  "page",
+  "project",
+  "expand"
+]);
+
+class QueryPlanner {
+  plan(query, options) {
+    return planObjectQuery(query, options);
+  }
+}
+function planObjectQuery(query, options) {
+  const operation = options.operation ?? "queryObjects";
+  const providerIssues = collectProviderIssues(query, options.capabilities, {
+    operation,
+    hasImplementation: hasProviderImplementation(operation, options)
+  });
+  if (providerIssues.length === 0) {
+    return {
+      mode: "pushdown",
+      query,
+      providerIssues,
+      fallbackIssues: [],
+      issues: []
+    };
+  }
+  const fallbackIssues = collectFallbackIssues(query, options);
+  const issues = [...providerIssues, ...fallbackIssues];
+  if (fallbackIssues.length === 0) {
+    return {
+      mode: "fallback",
+      query,
+      providerIssues,
+      fallbackIssues,
+      issues: [],
+      fallback: {
+        maxRows: options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS,
+        requiresExplicitBound: options.requiresExplicitFallbackBound !== false
+      }
+    };
+  }
+  return {
+    mode: "rejected",
+    query,
+    providerIssues,
+    fallbackIssues,
+    issues
+  };
+}
+function collectProviderIssues(query, capabilities, options) {
+  const issues = [];
+  collectOperationProviderIssues(capabilities, options, issues);
+  collectNodeProviderIssues(query, "$", capabilities, issues);
+  return issues;
+}
+function collectOperationProviderIssues(capabilities, options, issues) {
+  const enabled = options.operation === "queryObjects" ? capabilities.queryObjects === true : options.operation === "countObjects" ? capabilities.countObjects === true : options.operation === "existsObjects" ? capabilities.existsObjects === true : capabilities.facetObjects === true;
+  if (!enabled) {
+    const code2 = `${operationIssuePrefix(options.operation)}_not_enabled`;
+    addIssue(issues, "$", code2, `Object storage capabilities do not enable ${options.operation} pushdown`);
+  }
+  if (options.hasImplementation)
+    return;
+  const code = `${operationIssuePrefix(options.operation)}_not_implemented`;
+  addIssue(issues, "$", code, `Object storage does not implement ${options.operation}`);
+}
+function hasProviderImplementation(operation, options) {
+  switch (operation) {
+    case "queryObjects":
+      return options.hasQueryObjects === true;
+    case "countObjects":
+      return options.hasCountObjects === true;
+    case "existsObjects":
+      return options.hasExistsObjects === true;
+    case "facetObjects":
+      return options.hasFacetObjects === true;
+  }
+}
+function operationIssuePrefix(operation) {
+  switch (operation) {
+    case "queryObjects":
+      return "query_objects";
+    case "countObjects":
+      return "count_objects";
+    case "existsObjects":
+      return "exists_objects";
+    case "facetObjects":
+      return "facet_objects";
+  }
+}
+function collectNodeProviderIssues(query, path, capabilities, issues) {
+  if (capabilities.nodes?.[query.kind] !== true) {
+    addIssue(issues, path, "query_node_not_supported", `Provider does not support query node '${query.kind}'`);
+  }
+  switch (query.kind) {
+    case "start":
+      if (query.includeSubtypes === true && capabilities.features?.includeSubtypes !== true) {
+        addIssue(issues, path, "include_subtypes_not_supported", "Provider does not support start.includeSubtypes expansion");
+      }
+      return;
+    case "filter":
+      collectPredicateProviderIssues(query.predicate, `${path}.predicate`, capabilities, issues);
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "text":
+    case "vector":
+    case "project":
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "limit":
+      collectProviderMaxLimitIssues(query.limit, path, capabilities, issues);
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "page":
+      collectProviderMaxPageSizeIssues(query.pageSize, path, capabilities, issues);
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "traverse":
+      if (capabilities.traversalDirections?.[query.direction] !== true) {
+        addIssue(issues, path, "traversal_direction_not_supported", `Provider does not support ${query.direction} traversal`);
+      }
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "set":
+      if (capabilities.setOps?.[query.op] !== true) {
+        addIssue(issues, path, "set_operation_not_supported", `Provider does not support set operation '${query.op}'`);
+      }
+      query.inputs.forEach((input, index) => {
+        collectNodeProviderIssues(input, `${path}.inputs[${index}]`, capabilities, issues);
+      });
+      return;
+    case "sort":
+      query.fields.forEach((field, index) => {
+        collectSortProviderIssues(field, `${path}.fields[${index}]`, capabilities, issues);
+      });
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+    case "expand":
+      query.expansions.forEach((expansion, index) => {
+        collectExpansionProviderIssues(expansion, `${path}.expansions[${index}]`, capabilities, issues);
+      });
+      collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues);
+      return;
+  }
+}
+function collectExpansionProviderIssues(expansion, path, capabilities, issues) {
+  if (expansion.cardinality === undefined) {
+    addIssue(issues, path, "expand_cardinality_unresolved", `Provider cannot push down expansion '${expansion.linkId}' without a resolved cardinality`);
+  }
+  expansion.orderBy?.forEach((field, index) => {
+    collectSortProviderIssues(field, `${path}.orderBy[${index}]`, capabilities, issues);
+  });
+  expansion.expand?.forEach((nested, index) => {
+    collectExpansionProviderIssues(nested, `${path}.expand[${index}]`, capabilities, issues);
+  });
+}
+function collectPredicateProviderIssues(predicate, path, capabilities, issues) {
+  const scalarOperation = predicateScalarOperation(predicate);
+  if ("scalarKind" in predicate && predicate.scalarKind !== undefined && scalarOperation !== undefined && capabilities.scalarOperations?.[predicate.scalarKind]?.[scalarOperation] !== true) {
+    addIssue(issues, path, "scalar_operation_not_supported", `Provider does not support ${scalarOperation} for '${predicate.scalarKind}' values`);
+  }
+  if (capabilities.predicateOps?.[predicate.op] !== true) {
+    addIssue(issues, path, "predicate_operation_not_supported", `Provider does not support predicate operation '${predicate.op}'`);
+  }
+  switch (predicate.op) {
+    case "and":
+    case "or":
+      predicate.items.forEach((item, index) => {
+        collectPredicateProviderIssues(item, `${path}.items[${index}]`, capabilities, issues);
+      });
+      return;
+    case "not":
+      collectPredicateProviderIssues(predicate.item, `${path}.item`, capabilities, issues);
+      return;
+    default:
+      return;
+  }
+}
+function predicateScalarOperation(predicate) {
+  switch (predicate.op) {
+    case "eq":
+    case "neq":
+    case "in":
+      return "equality";
+    case "lt":
+    case "lte":
+    case "gt":
+    case "gte":
+      return "ordering";
+    default:
+      return;
+  }
+}
+function collectSortProviderIssues(field, path, capabilities, issues) {
+  if (field.kind === "property" && field.scalarKind !== undefined && capabilities.scalarOperations?.[field.scalarKind]?.ordering !== true) {
+    addIssue(issues, path, "scalar_operation_not_supported", `Provider does not support ordering for '${field.scalarKind}' values`);
+  }
+  if (capabilities.sortKinds?.[field.kind] === true)
+    return;
+  addIssue(issues, path, "sort_kind_not_supported", `Provider does not support sort kind '${field.kind}'`);
+}
+function collectProviderMaxLimitIssues(limit, path, capabilities, issues) {
+  const maxLimit = capabilities.limits?.maxLimit;
+  if (maxLimit === undefined)
+    return;
+  if (!Number.isInteger(maxLimit) || maxLimit < 0) {
+    addIssue(issues, path, "invalid_provider_limit_capability", "Provider limit capability maxLimit must be a non-negative integer");
+    return;
+  }
+  if (limit > maxLimit) {
+    addIssue(issues, path, "provider_limit_too_large", `Provider supports limit up to ${maxLimit}`);
+  }
+}
+function collectProviderMaxPageSizeIssues(pageSize, path, capabilities, issues) {
+  const maxPageSize = capabilities.limits?.maxPageSize;
+  if (maxPageSize === undefined)
+    return;
+  if (!Number.isInteger(maxPageSize) || maxPageSize <= 0) {
+    addIssue(issues, path, "invalid_provider_page_size_capability", "Provider limit capability maxPageSize must be a positive integer");
+    return;
+  }
+  if (pageSize > maxPageSize) {
+    addIssue(issues, path, "provider_page_size_too_large", `Provider supports pageSize up to ${maxPageSize}`);
+  }
+}
+function collectFallbackIssues(query, options) {
+  const issues = [];
+  if (options.allowFallback === false) {
+    addIssue(issues, "$", "fallback_disabled", "Object query fallback is disabled");
+    return issues;
+  }
+  const maxFallbackRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS;
+  if (!Number.isInteger(maxFallbackRows) || maxFallbackRows <= 0) {
+    addIssue(issues, "$", "invalid_fallback_bound", "maxFallbackRows must be a positive integer");
+  }
+  if (options.requiresExplicitFallbackBound !== false && !hasExplicitResultBound(query)) {
+    addIssue(issues, "$", "fallback_requires_bound", "Fallback requires an explicit limit or page node");
+  }
+  collectFallbackNodeIssues(query, "$", issues);
+  return issues;
+}
+function collectFallbackNodeIssues(query, path, issues) {
+  if (!fallbackNodeKinds.has(query.kind)) {
+    addIssue(issues, path, "fallback_node_not_supported", `Fallback does not support query node '${query.kind}'`);
+  }
+  switch (query.kind) {
+    case "start":
+      return;
+    case "filter":
+    case "limit":
+    case "page":
+    case "project":
+    case "expand":
+      collectFallbackNodeIssues(query.input, `${path}.input`, issues);
+      return;
+    case "sort":
+      query.fields.forEach((field, index) => {
+        if (field.kind === "relevance") {
+          addIssue(issues, `${path}.fields[${index}]`, "fallback_sort_kind_not_supported", "Fallback does not support relevance sorting");
+        }
+      });
+      collectFallbackNodeIssues(query.input, `${path}.input`, issues);
+      return;
+    case "text":
+    case "vector":
+    case "traverse":
+      collectFallbackNodeIssues(query.input, `${path}.input`, issues);
+      return;
+    case "set":
+      query.inputs.forEach((input, index) => {
+        collectFallbackNodeIssues(input, `${path}.inputs[${index}]`, issues);
+      });
+      return;
+  }
+}
+function hasExplicitResultBound(query) {
+  switch (query.kind) {
+    case "limit":
+    case "page":
+      return true;
+    case "start":
+      return false;
+    case "set":
+      return query.inputs.some(hasExplicitResultBound);
+    default:
+      return hasExplicitResultBound(query.input);
+  }
+}
+function addIssue(issues, path, code, message) {
+  issues.push({ path, code, message });
+}
+
+// src/objects/query/validate.ts
+var DEFAULT_MAX_LIMIT = 1000;
+var DEFAULT_MAX_PAGE_SIZE = 1000;
+function validateObjectQuery(query, options) {
+  const normalized = options.normalize === false ? query : normalizeObjectQuery(query);
+  const ctx = createValidationContext(options);
+  const validation = validateQueryNode(normalized, "$", ctx);
+  if (ctx.issues.length > 0) {
+    throw new ObjectQueryValidationError(ctx.issues);
+  }
+  return {
+    query: validation.query,
+    result: validation.result,
+    touchedObjectTypeIds: [...ctx.touchedObjectTypeIds]
+  };
+}
+function collectObjectQueryValidationIssues(query, options) {
+  const normalized = options.normalize === false ? query : normalizeObjectQuery(query);
+  const ctx = createValidationContext(options);
+  validateQueryNode(normalized, "$", ctx);
+  return ctx.issues;
+}
+function resolveObjectQueryResultShape(query, options) {
+  return validateObjectQuery(query, options).result;
+}
+function createValidationContext(options) {
+  return {
+    ontology: options.ontology,
+    valueTypesById: options.ontology.getValueTypesById(),
+    maxLimit: options.maxLimit ?? DEFAULT_MAX_LIMIT,
+    maxPageSize: options.maxPageSize ?? DEFAULT_MAX_PAGE_SIZE,
+    issues: [],
+    touchedObjectTypeIds: new Set
+  };
+}
+function validateQueryNode(query, path, ctx) {
+  const validation = dispatchQueryNode(query, path, ctx);
+  for (const objectTypeId of validation.result.objectTypeIds) {
+    ctx.touchedObjectTypeIds.add(objectTypeId);
+  }
+  return validation;
+}
+function dispatchQueryNode(query, path, ctx) {
+  switch (query.kind) {
+    case "start":
+      return validateStart(query.objectTypeId, query.includeSubtypes, path, ctx);
+    case "filter": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      const predicate = validatePredicate(query.predicate, input.result, `${path}.predicate`, ctx);
+      return { result: input.result, query: { ...query, input: input.query, predicate } };
+    }
+    case "text": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      const textFields = validateTextQuery(query.query, query.fields, input.result, path, ctx);
+      return {
+        result: input.result,
+        query: {
+          ...query,
+          input: input.query,
+          fields: query.fields,
+          fieldsByObjectType: query.fields ? undefined : textFields.fieldsByObjectType
+        }
+      };
+    }
+    case "vector": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      validateVectorQuery(query.vector, query.propertyId, query.k, input.result, path, ctx);
+      return { result: input.result, query: { ...query, input: input.query } };
+    }
+    case "traverse": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      return {
+        result: validateTraverse(query.linkId, query.direction, query.sourceObjectTypeId, input.result, path, ctx),
+        query: { ...query, input: input.query }
+      };
+    }
+    case "set":
+      return validateSet(query.inputs, query.op, path, ctx);
+    case "sort": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      const fields = validateSortFields(query.fields, input.result, path, ctx);
+      return { result: input.result, query: { ...query, input: input.query, fields } };
+    }
+    case "limit": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      validateLimit(query.limit, path, ctx);
+      return { result: input.result, query: { ...query, input: input.query } };
+    }
+    case "page": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      validatePage(query.pageSize, query.pageToken, path, ctx);
+      return { result: input.result, query: { ...query, input: input.query } };
+    }
+    case "project": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      validateProjection(query.properties, input.result, path, ctx);
+      return { result: input.result, query: { ...query, input: input.query } };
+    }
+    case "expand": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx);
+      const expansions = validateExpansions(query.expansions, input.result, `${path}.expansions`, ctx);
+      return { result: input.result, query: { ...query, input: input.query, expansions } };
+    }
+  }
+}
+function validateStart(objectTypeId, includeSubtypes, path, ctx) {
+  if (!objectTypeId) {
+    addIssue2(ctx, path, "missing_object_type", "start.objectTypeId is required");
+    return { result: { objectTypeIds: [] }, query: { kind: "start", objectTypeId } };
+  }
+  if (!ctx.ontology.getObjectTypeById(objectTypeId)) {
+    addIssue2(ctx, path, "unknown_object_type", formatUnknownObjectTypeMessage(objectTypeId));
+    return { result: { objectTypeIds: [] }, query: { kind: "start", objectTypeId } };
+  }
+  const objectTypeIds = includeSubtypes ? uniqueStrings([objectTypeId, ...ctx.ontology.listSubTypes(objectTypeId)]) : [objectTypeId];
+  return { result: { objectTypeIds }, query: { kind: "start", objectTypeId, includeSubtypes } };
+}
+function validatePredicate(predicate, shape, path, ctx) {
+  switch (predicate.op) {
+    case "and":
+    case "or":
+      if (predicate.items.length === 0) {
+        addIssue2(ctx, path, "empty_predicate_group", `Predicate '${predicate.op}' must not be empty`);
+      }
+      return {
+        ...predicate,
+        items: predicate.items.map((item, index) => validatePredicate(item, shape, `${path}.items[${index}]`, ctx))
+      };
+    case "not":
+      return {
+        ...predicate,
+        item: validatePredicate(predicate.item, shape, `${path}.item`, ctx)
+      };
+    case "eq":
+    case "neq":
+    case "lt":
+    case "lte":
+    case "gt":
+    case "gte": {
+      const { scalarKind: _authoredScalarKind, ...authoredPredicate } = predicate;
+      const scalarKind = resolveAndValidatePredicateProperty(predicate.propertyId, predicate.op, shape, path, ctx);
+      validatePredicateValue(predicate.propertyId, predicate.value, shape, path, ctx);
+      return {
+        ...authoredPredicate,
+        value: normalizeObjectQueryValue(predicate.value, scalarKind),
+        ...scalarKind ? { scalarKind } : {}
+      };
+    }
+    case "in": {
+      const { scalarKind: _authoredScalarKind, ...authoredPredicate } = predicate;
+      const scalarKind = resolveAndValidatePredicateProperty(predicate.propertyId, predicate.op, shape, path, ctx);
+      if (predicate.values.length === 0) {
+        addIssue2(ctx, path, "empty_in_values", "Predicate 'in' must include at least one value");
+      }
+      predicate.values.forEach((value, index) => {
+        validatePredicateValue(predicate.propertyId, value, shape, `${path}.values[${index}]`, ctx);
+      });
+      return {
+        ...authoredPredicate,
+        values: predicate.values.map((value) => normalizeObjectQueryValue(value, scalarKind)),
+        ...scalarKind ? { scalarKind } : {}
+      };
+    }
+    case "exists":
+      resolveAndValidatePredicateProperty(predicate.propertyId, predicate.op, shape, path, ctx);
+      if (typeof predicate.value !== "boolean") {
+        addIssue2(ctx, path, "invalid_exists_value", "Predicate 'exists' value must be boolean");
+      }
+      return predicate;
+    case "contains":
+      resolveAndValidatePredicateProperty(predicate.propertyId, predicate.op, shape, path, ctx);
+      validateContainsValue(predicate.propertyId, predicate.value, shape, path, ctx);
+      return predicate;
+  }
+}
+function resolveAndValidatePredicateProperty(propertyId, op, shape, path, ctx) {
+  const properties = getPropertiesForResult(propertyId, shape, path, ctx);
+  if (properties.length === 0)
+    return;
+  const schemas = [];
+  for (const { objectType, property } of properties) {
+    const schema = resolveSchemaForProperty(property, objectType.id, ctx, path);
+    if (schema)
+      schemas.push(schema);
+    if (isPrimaryExactPredicate(property, op)) {
+      continue;
+    }
+    if (property.query?.searchable !== true || property.query.filterable !== true) {
+      addIssue2(ctx, path, "property_not_filterable", `Property '${propertyId}' on '${objectType.id}' must set query.searchable: true and query.filterable: true before it can be used in predicates`);
+      continue;
+    }
+    if (!schema)
+      continue;
+    if ((op === "lt" || op === "lte" || op === "gt" || op === "gte") && !isSortableSchema(schema)) {
+      addIssue2(ctx, path, "operator_not_supported_for_schema", `Predicate '${op}' cannot be used with property '${propertyId}' on '${objectType.id}' because its schema is not orderable`);
+    }
+    if ((op === "eq" || op === "neq" || op === "in" || op === "exists") && !isExactSchema(schema)) {
+      addIssue2(ctx, path, "operator_not_supported_for_schema", `Predicate '${op}' cannot be used with property '${propertyId}' on '${objectType.id}' because its schema cannot be exact-matched`);
+    }
+    if (op === "contains" && !isContainsSchema(schema)) {
+      addIssue2(ctx, path, "operator_not_supported_for_schema", `Predicate 'contains' cannot be used with property '${propertyId}' on '${objectType.id}' because its schema is not string, array, or map`);
+    }
+  }
+  if (op === "exists" || op === "contains")
+    return;
+  return resolveCommonQueryScalarKind(schemas, propertyId, path, ctx);
+}
+function normalizeObjectQueryValue(value, scalarKind) {
+  if (scalarKind !== "decimal" || typeof value !== "string")
+    return value;
+  try {
+    return normalizeDecimalValue(value);
+  } catch {
+    return value;
+  }
+}
+function resolveCommonQueryScalarKind(schemas, propertyId, path, ctx) {
+  const scalarKinds = schemas.map(queryScalarKindForSchema);
+  if (scalarKinds.length === 0 || scalarKinds.some((kind) => kind === undefined)) {
+    return;
+  }
+  const resolvedKinds = new Set(scalarKinds);
+  if (resolvedKinds.size === 1)
+    return scalarKinds[0];
+  addIssue2(ctx, path, "incompatible_property_scalar_kinds", `Property '${propertyId}' resolves to incompatible scalar schemas: ${[...resolvedKinds].join(", ")}`);
+  return;
+}
+function queryScalarKindForSchema(schema) {
+  if (typeof schema === "string")
+    return schema === "fileRef" ? undefined : schema;
+  if (schema.type === "enum")
+    return schema.valueType === "integer" ? "integer" : "string";
+  return;
+}
+function validatePredicateValue(propertyId, value, shape, path, ctx) {
+  for (const { objectType, property } of getPropertiesForResult(propertyId, shape, path, ctx, {
+    reportMissing: false
+  })) {
+    try {
+      validatePropertyValue(property, value, `${objectType.id}.${property.id}`, ctx.valueTypesById);
+    } catch (error) {
+      addIssue2(ctx, path, "invalid_predicate_value", error instanceof Error ? error.message : `Invalid value for property '${property.id}' on '${objectType.id}'`);
+    }
+  }
+}
+function validateContainsValue(propertyId, value, shape, path, ctx) {
+  for (const { objectType, property } of getPropertiesForResult(propertyId, shape, path, ctx, {
+    reportMissing: false
+  })) {
+    const schema = resolveSchemaForProperty(property, objectType.id, ctx, path);
+    if (!schema)
+      continue;
+    if (typeof schema === "string") {
+      if (schema === "string" || schema === "uuid") {
+        if (typeof value !== "string") {
+          addIssue2(ctx, path, "invalid_contains_value", `Predicate 'contains' value for '${objectType.id}.${property.id}' must be a string`);
+        }
+      }
+      continue;
+    }
+    if (schema.type === "array") {
+      try {
+        validateSchemaValue(schema.items, value, `${objectType.id}.${property.id}[]`, ctx.valueTypesById);
+      } catch (error) {
+        addIssue2(ctx, path, "invalid_contains_value", error instanceof Error ? error.message : `Invalid contains value for '${objectType.id}.${property.id}'`);
+      }
+      continue;
+    }
+    if (schema.type === "map" && typeof value !== "string") {
+      addIssue2(ctx, path, "invalid_contains_value", `Predicate 'contains' value for '${objectType.id}.${property.id}' must be a map key string`);
+    }
+  }
+}
+function validateTextQuery(query, fields, shape, path, ctx) {
+  if (query.trim().length === 0) {
+    addIssue2(ctx, path, "empty_text_query", "Text query must not be empty");
+  }
+  const fieldsByObjectType = fields ? undefined : {};
+  for (const objectType of getObjectTypesForResult(shape, ctx)) {
+    const fieldIds = fields ?? objectType.search?.defaultText;
+    if (!fieldIds || fieldIds.length === 0) {
+      addIssue2(ctx, path, "missing_text_fields", `Object type '${objectType.id}' must define search.defaultText or the text query must specify fields`);
+      continue;
+    }
+    if (fieldsByObjectType)
+      fieldsByObjectType[objectType.id] = uniqueStrings(fieldIds);
+    for (const fieldId of fieldIds) {
+      const property = getProperty(objectType, fieldId);
+      if (!property) {
+        addIssue2(ctx, path, "unknown_text_field", `Text query references unknown property '${fieldId}' on '${objectType.id}'`);
+        continue;
+      }
+      assertStaticSearchProperty(objectType.id, property, "text query", path, ctx);
+      assertQueryFlag(objectType.id, property, "text", "text query", path, ctx);
+      const schema = resolveSchemaForProperty(property, objectType.id, ctx, path);
+      if (schema && !isTextSchema(schema)) {
+        addIssue2(ctx, path, "text_field_not_string_like", `Text query field '${fieldId}' on '${objectType.id}' must be string-like`);
+      }
+    }
+  }
+  return fieldsByObjectType ? { fieldsByObjectType } : {};
+}
+function validateVectorQuery(vector, propertyId, k, shape, path, ctx) {
+  if (!Number.isInteger(k) || k <= 0) {
+    addIssue2(ctx, path, "invalid_vector_k", "Vector query k must be a positive integer");
+  }
+  if (vector.length === 0) {
+    addIssue2(ctx, path, "empty_vector", "Vector query vector must not be empty");
+  }
+  if (vector.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
+    addIssue2(ctx, path, "invalid_vector_value", "Vector query vector values must be finite numbers");
+  }
+  for (const objectType of getObjectTypesForResult(shape, ctx)) {
+    const property = getProperty(objectType, propertyId);
+    if (!property) {
+      addIssue2(ctx, path, "unknown_vector_property", `Vector query references unknown property '${propertyId}' on '${objectType.id}'`);
+      continue;
+    }
+    assertStaticSearchProperty(objectType.id, property, "vector query", path, ctx);
+    assertQueryFlag(objectType.id, property, "vector", "vector query", path, ctx);
+    if (objectType.search?.vector?.property !== propertyId) {
+      addIssue2(ctx, path, "vector_profile_missing", `Object type '${objectType.id}' must declare search.vector.property '${propertyId}' before vector search can use it`);
+    }
+    const schema = resolveSchemaForProperty(property, objectType.id, ctx, path);
+    if (schema && !isVectorSchema(schema, ctx)) {
+      addIssue2(ctx, path, "vector_property_not_numeric_array", `Vector query property '${propertyId}' on '${objectType.id}' must be a numeric array`);
+    }
+  }
+}
+function validateTraverse(linkId, direction, sourceObjectTypeId, shape, path, ctx) {
+  if (!linkId) {
+    addIssue2(ctx, path, "missing_link_id", "traverse.linkId is required");
+    return { objectTypeIds: [] };
+  }
+  if (direction === "outgoing") {
+    if (sourceObjectTypeId !== undefined) {
+      addIssue2(ctx, path, "traverse_source_not_applicable", "traverse.sourceObjectTypeId only applies to incoming traversal");
+    }
+    return validateOutgoingTraverse(linkId, shape, path, ctx);
+  }
+  return validateIncomingTraverse(linkId, sourceObjectTypeId, shape, path, ctx);
+}
+function validateOutgoingTraverse(linkId, shape, path, ctx) {
+  const targetTypeIds = [];
+  for (const objectType of getObjectTypesForResult(shape, ctx)) {
+    const link = objectType.links.find((candidate) => candidate.id === linkId);
+    if (!link) {
+      addIssue2(ctx, path, "unknown_link", `Outgoing traversal references unknown link '${linkId}' on '${objectType.id}'`);
+      continue;
+    }
+    if (link.targetObjectTypeId === "*") {
+      addIssue2(ctx, path, "wildcard_traverse_target", `Outgoing traversal over wildcard link '${objectType.id}.${linkId}' cannot infer a target object type`);
+      continue;
+    }
+    const declaredTargets = Array.isArray(link.targetObjectTypeId) ? link.targetObjectTypeId : [link.targetObjectTypeId];
+    for (const targetId of declaredTargets) {
+      if (!ctx.ontology.getObjectTypeById(targetId)) {
+        addIssue2(ctx, path, "unknown_link_target", `Outgoing traversal over '${objectType.id}.${linkId}' targets unknown object type '${targetId}'`);
+      } else {
+        targetTypeIds.push(targetId);
+      }
+    }
+  }
+  return { objectTypeIds: uniqueStrings(targetTypeIds) };
+}
+function validateIncomingTraverse(linkId, sourceObjectTypeId, shape, path, ctx) {
+  let candidateTypes = ctx.ontology.listObjectTypes();
+  if (sourceObjectTypeId !== undefined) {
+    const sourceType = ctx.ontology.getObjectTypeById(sourceObjectTypeId);
+    if (!sourceType) {
+      addIssue2(ctx, path, "unknown_traverse_source", `Incoming traversal references unknown source object type '${sourceObjectTypeId}'`);
+      return { objectTypeIds: [] };
+    }
+    candidateTypes = [sourceType];
+  }
+  const sourceTypeIds = [];
+  for (const sourceType of candidateTypes) {
+    const link = sourceType.links.find((candidate) => candidate.id === linkId);
+    if (!link)
+      continue;
+    if (link.targetObjectTypeId === "*") {
+      sourceTypeIds.push(sourceType.id);
+      continue;
+    }
+    const matches = shape.objectTypeIds.some((targetTypeId) => ctx.ontology.isValidLinkTarget(link.targetObjectTypeId, targetTypeId));
+    if (matches)
+      sourceTypeIds.push(sourceType.id);
+  }
+  if (sourceTypeIds.length === 0) {
+    addIssue2(ctx, path, "incoming_link_not_found", `Incoming traversal found no source object types with link '${linkId}' targeting ${shape.objectTypeIds.join(" | ")}`);
+  }
+  return { objectTypeIds: uniqueStrings(sourceTypeIds) };
+}
+function validateExpansions(expansions, shape, path, ctx) {
+  return expansions.map((expansion, index) => validateExpansion(expansion, shape, `${path}[${index}]`, ctx));
+}
+function validateExpansion(expansion, shape, path, ctx) {
+  if (!expansion.linkId) {
+    addIssue2(ctx, path, "missing_expand_link", "expand.linkId is required");
+    return expansion;
+  }
+  const targetShape = expansion.direction === "incoming" ? resolveIncomingExpansionTargets(expansion.linkId, expansion.sourceObjectTypeId, shape, path, ctx) : resolveOutgoingExpansionTargets(expansion.linkId, expansion.sourceObjectTypeId, shape, path, ctx);
+  for (const targetTypeId of targetShape.objectTypeIds) {
+    ctx.touchedObjectTypeIds.add(targetTypeId);
+  }
+  validateExpansionLimit(expansion.limit, path, ctx);
+  const orderBy = expansion.orderBy ? validateSortFields(expansion.orderBy, targetShape, `${path}.orderBy`, ctx) : undefined;
+  const expand = expansion.expand ? validateExpansions(expansion.expand, targetShape, `${path}.expand`, ctx) : undefined;
+  return { ...expansion, orderBy, expand };
+}
+function resolveOutgoingExpansionTargets(linkId, sourceObjectTypeId, shape, path, ctx) {
+  if (sourceObjectTypeId !== undefined) {
+    addIssue2(ctx, path, "expand_source_not_applicable", "expand.sourceObjectTypeId only applies to incoming expansion");
+  }
+  const targetTypeIds = [];
+  let foundOnAnyType = false;
+  for (const objectType of getObjectTypesForResult(shape, ctx)) {
+    const link = objectType.links.find((candidate) => candidate.id === linkId);
+    if (!link)
+      continue;
+    foundOnAnyType = true;
+    if (link.targetObjectTypeId === "*") {
+      addIssue2(ctx, path, "wildcard_expand_target", `Expansion over wildcard link '${objectType.id}.${linkId}' cannot infer a target object type`);
+      continue;
+    }
+    const declaredTargets = Array.isArray(link.targetObjectTypeId) ? link.targetObjectTypeId : [link.targetObjectTypeId];
+    for (const targetId of declaredTargets) {
+      if (!ctx.ontology.getObjectTypeById(targetId)) {
+        addIssue2(ctx, path, "unknown_expand_target", `Expansion over '${objectType.id}.${linkId}' targets unknown object type '${targetId}'`);
+      } else {
+        targetTypeIds.push(targetId);
+      }
+    }
+  }
+  if (!foundOnAnyType) {
+    addIssue2(ctx, path, "unknown_expand_link", `Expansion references link '${linkId}' not present on result type ${shape.objectTypeIds.join(" | ")} (an expand abandoned by a later traverse?)`);
+  }
+  return { objectTypeIds: uniqueStrings(targetTypeIds) };
+}
+function resolveIncomingExpansionTargets(linkId, sourceObjectTypeId, shape, path, ctx) {
+  let candidateTypes = ctx.ontology.listObjectTypes();
+  if (sourceObjectTypeId !== undefined) {
+    const sourceType = ctx.ontology.getObjectTypeById(sourceObjectTypeId);
+    if (!sourceType) {
+      addIssue2(ctx, path, "unknown_expand_source", `Incoming expansion references unknown source object type '${sourceObjectTypeId}'`);
+      return { objectTypeIds: [] };
+    }
+    candidateTypes = [sourceType];
+  }
+  const sourceTypeIds = [];
+  for (const sourceType of candidateTypes) {
+    const link = sourceType.links.find((candidate) => candidate.id === linkId);
+    if (!link)
+      continue;
+    if (link.targetObjectTypeId === "*") {
+      sourceTypeIds.push(sourceType.id);
+      continue;
+    }
+    const matches = shape.objectTypeIds.some((targetTypeId) => ctx.ontology.isValidLinkTarget(link.targetObjectTypeId, targetTypeId));
+    if (matches)
+      sourceTypeIds.push(sourceType.id);
+  }
+  if (sourceTypeIds.length === 0) {
+    addIssue2(ctx, path, "incoming_expand_link_not_found", `Incoming expansion found no source object types with link '${linkId}' targeting ${shape.objectTypeIds.join(" | ")}`);
+  }
+  return { objectTypeIds: uniqueStrings(sourceTypeIds) };
+}
+function validateExpansionLimit(limit, path, ctx) {
+  if (limit === undefined)
+    return;
+  if (!Number.isInteger(limit) || limit < 0) {
+    addIssue2(ctx, `${path}.limit`, "invalid_expand_limit", "expand.limit must be a non-negative integer");
+  }
+}
+function validateSet(inputs, op, path, ctx) {
+  if (inputs.length === 0) {
+    addIssue2(ctx, path, "empty_set", `Set operation '${op}' must include at least one input`);
+    return { result: { objectTypeIds: [] }, query: { kind: "set", op, inputs } };
+  }
+  const results = inputs.map((input, index) => validateQueryNode(input, `${path}.inputs[${index}]`, ctx));
+  const first = results[0]?.result ?? { objectTypeIds: [] };
+  const expected = keyForTypeIds(first.objectTypeIds);
+  results.forEach((result, index) => {
+    if (keyForTypeIds(result.result.objectTypeIds) !== expected) {
+      addIssue2(ctx, `${path}.inputs[${index}]`, "incompatible_set_input", `Set operation '${op}' inputs must produce the same object type set`);
+    }
+  });
+  return {
+    result: first,
+    query: { kind: "set", op, inputs: results.map((result) => result.query) }
+  };
+}
+function validateSortFields(fields, shape, path, ctx) {
+  if (fields.length === 0) {
+    addIssue2(ctx, path, "empty_sort", "Sort must include at least one field");
+    return [];
+  }
+  const seen = new Set;
+  return fields.map((field, index) => {
+    if (field.direction && field.direction !== "asc" && field.direction !== "desc") {
+      addIssue2(ctx, `${path}.fields[${index}]`, "invalid_sort_direction", "Sort direction must be asc or desc");
+    }
+    const key = field.kind === "property" ? `property:${field.propertyId}` : "relevance";
+    if (seen.has(key)) {
+      addIssue2(ctx, `${path}.fields[${index}]`, "duplicate_sort_field", `Duplicate sort field '${key}'`);
+    }
+    seen.add(key);
+    if (field.kind === "relevance")
+      return field;
+    const { scalarKind: _authoredScalarKind, ...authoredField } = field;
+    const schemas = [];
+    for (const { objectType, property } of getPropertiesForResult(field.propertyId, shape, `${path}.fields[${index}]`, ctx)) {
+      if (property.query?.searchable !== true || property.query.sortable !== true) {
+        addIssue2(ctx, `${path}.fields[${index}]`, "property_not_sortable", `Property '${property.id}' on '${objectType.id}' must set query.searchable: true and query.sortable: true before it can be sorted`);
+        continue;
+      }
+      const schema = resolveSchemaForProperty(property, objectType.id, ctx, `${path}.fields[${index}]`);
+      if (schema)
+        schemas.push(schema);
+      if (schema && !isSortableSchema(schema)) {
+        addIssue2(ctx, `${path}.fields[${index}]`, "sort_field_not_orderable", `Sort field '${property.id}' on '${objectType.id}' is not orderable`);
+      }
+    }
+    const scalarKind = resolveCommonQueryScalarKind(schemas, field.propertyId, `${path}.fields[${index}]`, ctx);
+    return { ...authoredField, ...scalarKind ? { scalarKind } : {} };
+  });
+}
+function validateLimit(limit, path, ctx) {
+  if (!Number.isInteger(limit) || limit < 0) {
+    addIssue2(ctx, path, "invalid_limit", "limit must be a non-negative integer");
+  } else if (limit > ctx.maxLimit) {
+    addIssue2(ctx, path, "limit_too_large", `limit must be <= ${ctx.maxLimit}`);
+  }
+}
+function validatePage(pageSize, pageToken, path, ctx) {
+  if (!Number.isInteger(pageSize) || pageSize <= 0) {
+    addIssue2(ctx, path, "invalid_page_size", "pageSize must be a positive integer");
+  } else if (pageSize > ctx.maxPageSize) {
+    addIssue2(ctx, path, "page_size_too_large", `pageSize must be <= ${ctx.maxPageSize}`);
+  }
+  if (pageToken !== undefined && pageToken.length === 0) {
+    addIssue2(ctx, path, "empty_page_token", "pageToken must not be empty when provided");
+  }
+}
+function validateProjection(properties, shape, path, ctx) {
+  if (!properties)
+    return;
+  if (properties.length === 0) {
+    addIssue2(ctx, path, "empty_projection", "project.properties must not be empty when provided");
+  }
+  const seen = new Set;
+  properties.forEach((propertyId, index) => {
+    if (seen.has(propertyId)) {
+      addIssue2(ctx, `${path}.properties[${index}]`, "duplicate_projection_property", `Duplicate projected property '${propertyId}'`);
+    }
+    seen.add(propertyId);
+    getPropertiesForResult(propertyId, shape, `${path}.properties[${index}]`, ctx);
+  });
+}
+function getObjectTypesForResult(shape, ctx) {
+  const objectTypes = [];
+  for (const objectTypeId of shape.objectTypeIds) {
+    const objectType = ctx.ontology.getObjectTypeById(objectTypeId);
+    if (objectType)
+      objectTypes.push(objectType);
+  }
+  return objectTypes;
+}
+function getPropertiesForResult(propertyId, shape, path, ctx, options = {}) {
+  const results = [];
+  for (const objectType of getObjectTypesForResult(shape, ctx)) {
+    const property = getProperty(objectType, propertyId);
+    if (!property) {
+      if (options.reportMissing === false) {
+        continue;
+      }
+      addIssue2(ctx, path, "unknown_property", `Property '${propertyId}' does not exist on object type '${objectType.id}'`);
+      continue;
+    }
+    results.push({ objectType, property });
+  }
+  return results;
+}
+function getProperty(objectType, propertyId) {
+  return objectType.properties.find((property) => property.id === propertyId);
+}
+function assertStaticSearchProperty(objectTypeId, property, context, path, ctx) {
+  if (property.mode === "telemetry") {
+    addIssue2(ctx, path, "telemetry_search_property", `${context} references telemetry property '${property.id}' on '${objectTypeId}'. Search can only reference static properties because telemetry latest values are not object-query indexed.`);
+  }
+}
+function assertQueryFlag(objectTypeId, property, flag, context, path, ctx) {
+  if (property.query?.searchable === true && property.query[flag] === true)
+    return;
+  addIssue2(ctx, path, "query_field_not_enabled", `${context} field '${property.id}' on '${objectTypeId}' must set query.searchable: true and query.${flag}: true`);
+}
+function resolveSchemaForProperty(property, objectTypeId, ctx, path) {
+  try {
+    return resolveSchema(property.schema, ctx.valueTypesById);
+  } catch (error) {
+    addIssue2(ctx, path, "unresolved_property_schema", error instanceof Error ? error.message : `Could not resolve schema for '${objectTypeId}.${property.id}'`);
+    return null;
+  }
+}
+function resolveSchema(schema, valueTypesById, seenValueTypeIds = new Set) {
+  if (typeof schema === "string")
+    return schema;
+  if (schema.type !== "valueTypeRef")
+    return schema;
+  if (seenValueTypeIds.has(schema.valueTypeId)) {
+    throw new Error(`Circular valueTypeRef '${schema.valueTypeId}'`);
+  }
+  const resolved = schema._resolved ?? valueTypesById.get(schema.valueTypeId)?.schema;
+  if (!resolved) {
+    throw new Error(`Unknown valueTypeRef '${schema.valueTypeId}'`);
+  }
+  seenValueTypeIds.add(schema.valueTypeId);
+  return resolveSchema(resolved, valueTypesById, seenValueTypeIds);
+}
+function isPrimaryExactPredicate(property, op) {
+  return property.primary === true && (op === "eq" || op === "in");
+}
+function isTextSchema(schema) {
+  if (schema === "string")
+    return true;
+  return typeof schema !== "string" && schema.type === "enum" && schema.valueType === "string";
+}
+function isExactSchema(schema) {
+  if (typeof schema === "string")
+    return schema !== "fileRef";
+  return schema.type === "enum";
+}
+function isSortableSchema(schema) {
+  if (typeof schema === "string") {
+    return schema === "string" || schema === "uuid" || schema === "integer" || schema === "double" || schema === "decimal" || schema === "date" || schema === "timestamp";
+  }
+  return schema.type === "enum";
+}
+function isContainsSchema(schema) {
+  return schema === "string" || schema === "uuid" || typeof schema !== "string" && (schema.type === "array" || schema.type === "map");
+}
+function isVectorSchema(schema, ctx) {
+  if (typeof schema === "string")
+    return false;
+  if (schema.type !== "array")
+    return false;
+  const itemSchema = resolveSchema(schema.items, ctx.valueTypesById);
+  return itemSchema === "integer" || itemSchema === "double" || itemSchema === "decimal";
+}
+function keyForTypeIds(typeIds) {
+  return uniqueStrings(typeIds).sort().join("\x00");
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+function addIssue2(ctx, path, code, message) {
+  ctx.issues.push({ path, code, message });
+}
+
+// src/objects/query/executor.ts
+var DEFAULT_MAX_FALLBACK_ROWS2 = 1000;
+var DEFAULT_MAX_FACET_LIMIT = 1000;
+var DEFAULT_MAX_EXPANSION_FANOUT = 1000;
+var PAGE_TOKEN_PREFIX = "offset:";
+
+class QueryExecutor {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async execute(input) {
+    return executeObjectQuery(input, this.options);
+  }
+  async count(input) {
+    return countObjects(input, this.options);
+  }
+  async exists(input) {
+    return existsObjects(input, this.options);
+  }
+  async facets(input) {
+    return facetObjects(input, this.options);
+  }
+}
+async function executeObjectQuery(input, options) {
+  const normalized = normalizeObjectQuery(input.query);
+  const validated = validateObjectQuery(normalized, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  });
+  assertQueryViewable(validated, options.authorization);
+  const capabilities = options.storage.queryCapabilities();
+  const hasQueryObjects = typeof options.storage.queryObjects === "function";
+  const hasCountObjects = typeof options.storage.countObjects === "function";
+  const hasExistsObjects = typeof options.storage.existsObjects === "function";
+  const hasFacetObjects = typeof options.storage.facetObjects === "function";
+  const plannedQuery = expandPushdownQuery(validated.query, options.ontology, capabilities, {
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  }, options.maxExpansionFanout);
+  const plan = planObjectQuery(plannedQuery, {
+    capabilities,
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  if (plan.mode === "rejected") {
+    throw new ObjectQueryPlanningError(plan.issues);
+  }
+  if (plan.mode === "pushdown") {
+    if (!options.storage.queryObjects) {
+      throw new ObjectQueryPlanningError(plan.providerIssues);
+    }
+    const result = await options.storage.queryObjects({
+      projectId: input.projectId,
+      query: plan.query,
+      includeTotal: input.includeTotal
+    });
+    return { ...result, plan };
+  }
+  const fallback = await executeFallbackQuery(input.projectId, validated.query, options, {
+    includeTotal: input.includeTotal
+  });
+  return { ...fallback, plan };
+}
+async function countObjects(input, options) {
+  const normalized = normalizeObjectQuery(input.query);
+  const validated = validateObjectQuery(normalized, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  });
+  assertQueryViewable(validated, options.authorization);
+  const capabilities = options.storage.queryCapabilities();
+  const hasQueryObjects = typeof options.storage.queryObjects === "function";
+  const hasCountObjects = typeof options.storage.countObjects === "function";
+  const hasExistsObjects = typeof options.storage.existsObjects === "function";
+  const hasFacetObjects = typeof options.storage.facetObjects === "function";
+  const aggregateQuery = stripOuterRowShape(validated.query);
+  const plannedQuery = expandPushdownQuery(aggregateQuery, options.ontology, capabilities, {
+    operation: "countObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  const plan = planObjectQuery(plannedQuery, {
+    capabilities,
+    operation: "countObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  if (plan.mode === "rejected") {
+    throw new ObjectQueryPlanningError(plan.issues);
+  }
+  if (plan.mode === "pushdown") {
+    if (!options.storage.countObjects) {
+      throw new ObjectQueryPlanningError(plan.providerIssues);
+    }
+    const result = await options.storage.countObjects({
+      projectId: input.projectId,
+      query: plan.query
+    });
+    return { ...result, plan };
+  }
+  const maxRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS2;
+  const evaluation = await evaluateFallbackQuery(input.projectId, aggregateQuery, options, maxRows);
+  return { count: evaluation.total, plan };
+}
+async function existsObjects(input, options) {
+  const normalized = normalizeObjectQuery(input.query);
+  const validated = validateObjectQuery(normalized, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  });
+  assertQueryViewable(validated, options.authorization);
+  const capabilities = options.storage.queryCapabilities();
+  const hasQueryObjects = typeof options.storage.queryObjects === "function";
+  const hasCountObjects = typeof options.storage.countObjects === "function";
+  const hasExistsObjects = typeof options.storage.existsObjects === "function";
+  const hasFacetObjects = typeof options.storage.facetObjects === "function";
+  const aggregateQuery = stripOuterRowShape(validated.query);
+  const plannedQuery = expandPushdownQuery(aggregateQuery, options.ontology, capabilities, {
+    operation: "existsObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  const plan = planObjectQuery(plannedQuery, {
+    capabilities,
+    operation: "existsObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  if (plan.mode === "rejected") {
+    throw new ObjectQueryPlanningError(plan.issues);
+  }
+  if (plan.mode === "pushdown") {
+    if (!options.storage.existsObjects) {
+      throw new ObjectQueryPlanningError(plan.providerIssues);
+    }
+    const result = await options.storage.existsObjects({
+      projectId: input.projectId,
+      query: plan.query
+    });
+    return { ...result, plan };
+  }
+  const maxRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS2;
+  const evaluation = await evaluateFallbackQuery(input.projectId, aggregateQuery, options, maxRows);
+  return { exists: evaluation.total > 0, plan };
+}
+async function facetObjects(input, options) {
+  const normalized = normalizeObjectQuery(input.query);
+  const validated = validateObjectQuery(normalized, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  });
+  assertQueryViewable(validated, options.authorization);
+  const facets = validateFacetRequests(input.facets, validated.result.objectTypeIds, options);
+  const aggregateQuery = stripOuterRowShape(validated.query);
+  const capabilities = options.storage.queryCapabilities();
+  const hasQueryObjects = typeof options.storage.queryObjects === "function";
+  const hasCountObjects = typeof options.storage.countObjects === "function";
+  const hasExistsObjects = typeof options.storage.existsObjects === "function";
+  const hasFacetObjects = typeof options.storage.facetObjects === "function";
+  const plannedQuery = expandPushdownQuery(aggregateQuery, options.ontology, capabilities, {
+    operation: "facetObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  const plan = planObjectQuery(plannedQuery, {
+    capabilities,
+    operation: "facetObjects",
+    hasQueryObjects,
+    hasCountObjects,
+    hasExistsObjects,
+    hasFacetObjects,
+    allowFallback: options.allowFallback,
+    maxFallbackRows: options.maxFallbackRows,
+    requiresExplicitFallbackBound: options.requiresExplicitFallbackBound
+  });
+  if (plan.mode === "rejected") {
+    throw new ObjectQueryPlanningError(plan.issues);
+  }
+  if (plan.mode === "pushdown") {
+    if (!options.storage.facetObjects) {
+      throw new ObjectQueryPlanningError(plan.providerIssues);
+    }
+    const result = await options.storage.facetObjects({
+      projectId: input.projectId,
+      query: plan.query,
+      facets
+    });
+    return { ...result, plan };
+  }
+  const maxRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS2;
+  const evaluation = await evaluateFallbackQuery(input.projectId, aggregateQuery, options, maxRows);
+  return {
+    facets: buildFacetResults(evaluation.entries.map((entry) => entry.row), facets),
+    plan
+  };
+}
+function assertQueryViewable(validated, authorization) {
+  assertAuthorized({ authorization }, { kind: "object.query", touchedObjectTypeIds: validated.touchedObjectTypeIds });
+}
+function expandPushdownQuery(query, ontology, capabilities, planning, maxExpansionFanout) {
+  const ctx = { ontology, maxExpansionFanout };
+  const annotated = resolveExpansions(query, ctx);
+  const expanded = expandIncludeSubtypes(annotated, ontology);
+  if (expanded === annotated)
+    return annotated;
+  const plan = planObjectQuery(expanded, { ...planning, capabilities, allowFallback: false });
+  return plan.mode === "pushdown" ? expanded : annotated;
+}
+function resolveExpansions(query, ctx) {
+  switch (query.kind) {
+    case "expand": {
+      const parentShape = safeResultShape(query.input, ctx.ontology);
+      return {
+        ...query,
+        input: resolveExpansions(query.input, ctx),
+        expansions: query.expansions.map((expansion) => annotateExpansion(expansion, parentShape, ctx))
+      };
+    }
+    case "start":
+      return query;
+    case "set":
+      return {
+        ...query,
+        inputs: query.inputs.map((input) => resolveExpansions(input, ctx))
+      };
+    case "filter":
+    case "text":
+    case "vector":
+    case "traverse":
+    case "sort":
+    case "limit":
+    case "page":
+    case "project":
+      return { ...query, input: resolveExpansions(query.input, ctx) };
+  }
+}
+function annotateExpansion(expansion, parentShape, ctx) {
+  const cardinality = resolveUniformCardinality(expansion, parentShape, ctx.ontology);
+  const limit = effectiveExpansionFanout(expansion.limit, ctx.maxExpansionFanout);
+  const base = cardinality ? { ...expansion, cardinality, limit } : { ...expansion, limit };
+  if (!expansion.expand || expansion.expand.length === 0)
+    return base;
+  const targetShape = resolveExpansionTargetShape(expansion, parentShape, ctx.ontology);
+  return {
+    ...base,
+    expand: expansion.expand.map((nested) => annotateExpansion(nested, targetShape, ctx))
+  };
+}
+function resolveUniformCardinality(expansion, parentShape, ontology) {
+  if (expansion.direction === "incoming")
+    return "many";
+  if (parentShape.objectTypeIds.length === 0)
+    return;
+  const cardinalities = new Set;
+  for (const objectTypeId of parentShape.objectTypeIds) {
+    const objectType = ontology.getObjectTypeById(objectTypeId);
+    const link = objectType?.links.find((candidate) => candidate.id === expansion.linkId);
+    cardinalities.add(link?.cardinality ?? "many");
+  }
+  return cardinalities.size === 1 ? [...cardinalities][0] : undefined;
+}
+function resolveExpansionTargetShape(expansion, parentShape, ontology) {
+  if (parentShape.objectTypeIds.length === 0)
+    return { objectTypeIds: [] };
+  const input = parentShape.objectTypeIds.length === 1 ? { kind: "start", objectTypeId: parentShape.objectTypeIds[0] } : {
+    kind: "set",
+    op: "union",
+    inputs: parentShape.objectTypeIds.map((objectTypeId) => ({
+      kind: "start",
+      objectTypeId
+    }))
+  };
+  const traverse = {
+    kind: "traverse",
+    input,
+    linkId: expansion.linkId,
+    direction: expansion.direction,
+    ...expansion.sourceObjectTypeId === undefined ? {} : { sourceObjectTypeId: expansion.sourceObjectTypeId }
+  };
+  return safeResultShape(traverse, ontology);
+}
+function safeResultShape(query, ontology) {
+  try {
+    return resolveObjectQueryResultShape(query, { ontology });
+  } catch {
+    return { objectTypeIds: [] };
+  }
+}
+function expandIncludeSubtypes(query, ontology) {
+  switch (query.kind) {
+    case "start": {
+      if (query.includeSubtypes !== true)
+        return query;
+      const objectTypeIds = [query.objectTypeId, ...ontology.listSubTypes(query.objectTypeId)];
+      if (objectTypeIds.length === 1)
+        return { kind: "start", objectTypeId: query.objectTypeId };
+      return {
+        kind: "set",
+        op: "union",
+        inputs: objectTypeIds.map((objectTypeId) => ({ kind: "start", objectTypeId }))
+      };
+    }
+    case "filter":
+    case "text":
+    case "vector":
+    case "traverse":
+    case "sort":
+    case "limit":
+    case "page":
+    case "project":
+    case "expand":
+      return { ...query, input: expandIncludeSubtypes(query.input, ontology) };
+    case "set":
+      return {
+        ...query,
+        inputs: query.inputs.map((input) => expandIncludeSubtypes(input, ontology))
+      };
+  }
+}
+async function executeFallbackQuery(projectId, query, options, resultOptions) {
+  const maxRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS2;
+  const evaluation = await evaluateFallbackQuery(projectId, query, options, maxRows);
+  return {
+    objects: evaluation.entries.map((entry) => entry.row),
+    hasMore: evaluation.hasMore,
+    nextPageToken: evaluation.nextPageToken,
+    ...resultOptions.includeTotal === false ? {} : { total: evaluation.total }
+  };
+}
+async function evaluateFallbackQuery(projectId, query, options, maxRows) {
+  switch (query.kind) {
+    case "start":
+      return evaluateFallbackStart(projectId, query, options, maxRows);
+    case "filter": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      return completeFallbackEvaluation(input.entries.filter((entry) => matchesPredicate(entry.row, query.predicate)));
+    }
+    case "sort": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      return {
+        ...input,
+        entries: sortEntries(input.entries, query.fields)
+      };
+    }
+    case "limit": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      const limit = Math.max(0, query.limit);
+      return {
+        entries: input.entries.slice(0, limit),
+        total: input.entries.length,
+        hasMore: limit < input.entries.length
+      };
+    }
+    case "page": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      const offset = decodePageOffset(query.pageToken);
+      const pageSize = Math.max(0, query.pageSize);
+      const nextOffset = offset + pageSize;
+      const hasMore = pageSize > 0 && nextOffset < input.entries.length;
+      return {
+        entries: input.entries.slice(offset, nextOffset),
+        total: input.entries.length,
+        hasMore,
+        nextPageToken: hasMore ? encodePageOffset(nextOffset) : undefined
+      };
+    }
+    case "project": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      if (!query.properties)
+        return input;
+      const properties = query.properties;
+      return {
+        ...input,
+        entries: input.entries.map((entry) => ({
+          ...entry,
+          row: projectRow(entry.row, properties)
+        }))
+      };
+    }
+    case "expand": {
+      const input = await evaluateFallbackQuery(projectId, query.input, options, maxRows);
+      const enriched = await hydrateExpansions(projectId, input.entries.map((entry) => entry.row), query.expansions, options);
+      return {
+        ...input,
+        entries: input.entries.map((entry, index) => ({ ...entry, row: enriched[index] }))
+      };
+    }
+    case "text":
+    case "vector":
+    case "traverse":
+    case "set":
+      throw new ObjectQueryExecutionError("fallback_node_not_supported", `Fallback execution does not support query node '${query.kind}'`);
+  }
+}
+async function hydrateExpansions(projectId, parents, expansions, options) {
+  if (expansions.length === 0) {
+    return parents.map((parent) => ({ ...parent }));
+  }
+  const linksByParent = parents.map(() => ({}));
+  for (const expansion of expansions) {
+    const values = await hydrateExpansion(projectId, parents, expansion, options);
+    values.forEach((value, index) => {
+      linksByParent[index][expansion.linkId] = value;
+    });
+  }
+  return parents.map((parent, index) => ({ ...parent, links: linksByParent[index] }));
+}
+async function hydrateExpansion(projectId, parents, expansion, options) {
+  const edgesByParent = expansion.direction === "incoming" ? await collectIncomingEdges(projectId, parents, expansion, options) : await collectOutgoingEdges(projectId, parents, expansion, options);
+  const baseTargets = await fetchExpansionTargets(projectId, edgesByParent, options);
+  const trimmedByParent = edgesByParent.map((edges) => trimExpansionEdges(edges, expansion, baseTargets, options));
+  const enrichedByKey = await enrichExpansionTargets(projectId, trimmedByParent, baseTargets, expansion, options);
+  return parents.map((parent, index) => {
+    const expanded = [];
+    for (const edge of trimmedByParent[index]) {
+      const target = enrichedByKey.get(targetKey(edge.neighborTypeId, edge.neighborId));
+      if (!target)
+        continue;
+      expanded.push(edge.edgeProperties && Object.keys(edge.edgeProperties).length > 0 ? { ...target, linkProperties: edge.edgeProperties } : { ...target });
+    }
+    return toLinkValue(expanded, expansionCardinality(parent, expansion, options));
+  });
+}
+async function collectOutgoingEdges(projectId, parents, expansion, options) {
+  const linksByKey = await options.storage.listLinksBatch({
+    projectId,
+    items: parents.map((parent) => ({
+      objectTypeId: parent.objectTypeId,
+      objectId: parent.primaryId,
+      linkId: expansion.linkId
+    }))
+  });
+  return parents.map((parent) => {
+    const links = linksByKey.get(`${parent.objectTypeId}:${parent.primaryId}:${expansion.linkId}`);
+    if (!links)
+      return [];
+    return links.map((link) => ({
+      neighborTypeId: link.targetTypeId,
+      neighborId: link.targetId,
+      edgeProperties: link.properties
+    }));
+  });
+}
+async function collectIncomingEdges(projectId, parents, expansion, options) {
+  const incident = await options.storage.listIncidentLinksBatch({
+    projectId,
+    items: parents.map((parent) => ({
+      objectTypeId: parent.objectTypeId,
+      objectId: parent.primaryId
+    }))
+  });
+  const byTarget = new Map;
+  for (const link of incident) {
+    if (link.linkId !== expansion.linkId)
+      continue;
+    if (expansion.sourceObjectTypeId && link.sourceTypeId !== expansion.sourceObjectTypeId)
+      continue;
+    const key = targetKey(link.targetTypeId, link.targetId);
+    const bucket = byTarget.get(key);
+    if (bucket)
+      bucket.push(link);
+    else
+      byTarget.set(key, [link]);
+  }
+  return parents.map((parent) => {
+    const links = byTarget.get(targetKey(parent.objectTypeId, parent.primaryId));
+    if (!links)
+      return [];
+    return links.map((link) => ({
+      neighborTypeId: link.sourceTypeId,
+      neighborId: link.sourceId,
+      edgeProperties: link.properties
+    }));
+  });
+}
+async function fetchExpansionTargets(projectId, edgesByParent, options) {
+  const seen = new Set;
+  const items = [];
+  for (const edges of edgesByParent) {
+    for (const edge of edges) {
+      const key = targetKey(edge.neighborTypeId, edge.neighborId);
+      if (seen.has(key))
+        continue;
+      seen.add(key);
+      items.push({ objectTypeId: edge.neighborTypeId, primaryId: edge.neighborId });
+    }
+  }
+  if (items.length === 0)
+    return new Map;
+  return options.storage.getByPrimaryIdBatch({ projectId, items });
+}
+async function enrichExpansionTargets(projectId, trimmedByParent, baseTargets, expansion, options) {
+  if (!expansion.expand || expansion.expand.length === 0) {
+    return baseTargets;
+  }
+  const uniqueTargets = [];
+  const seen = new Set;
+  for (const edges of trimmedByParent) {
+    for (const edge of edges) {
+      const key = targetKey(edge.neighborTypeId, edge.neighborId);
+      if (seen.has(key))
+        continue;
+      seen.add(key);
+      const base = baseTargets.get(key);
+      if (base)
+        uniqueTargets.push(base);
+    }
+  }
+  const enriched = await hydrateExpansions(projectId, uniqueTargets, expansion.expand, options);
+  const enrichedByKey = new Map;
+  for (const row of enriched) {
+    enrichedByKey.set(targetKey(row.objectTypeId, row.primaryId), row);
+  }
+  return enrichedByKey;
+}
+function trimExpansionEdges(edges, expansion, baseTargets, options) {
+  let ordered = edges;
+  if (expansion.orderBy && expansion.orderBy.length > 0) {
+    const fields = expansion.orderBy;
+    ordered = [...edges].sort((left, right) => compareExpansionEdges(left, right, fields, baseTargets));
+  }
+  const limit = effectiveExpansionFanout(expansion.limit, options.maxExpansionFanout);
+  return ordered.length > limit ? ordered.slice(0, limit) : [...ordered];
+}
+function effectiveExpansionFanout(limit, maxExpansionFanout) {
+  const cap = maxExpansionFanout !== undefined ? maxExpansionFanout : DEFAULT_MAX_EXPANSION_FANOUT;
+  return limit !== undefined ? Math.min(limit, cap) : cap;
+}
+function compareExpansionEdges(left, right, fields, baseTargets) {
+  const leftRow = baseTargets.get(targetKey(left.neighborTypeId, left.neighborId));
+  const rightRow = baseTargets.get(targetKey(right.neighborTypeId, right.neighborId));
+  for (const field of fields) {
+    const comparison = compareRowsBySortField(leftRow, rightRow, field);
+    if (comparison !== 0)
+      return comparison;
+  }
+  return targetKey(left.neighborTypeId, left.neighborId).localeCompare(targetKey(right.neighborTypeId, right.neighborId));
+}
+function compareRowsBySortField(left, right, field) {
+  if (field.kind === "relevance")
+    return 0;
+  const leftValue = left?.properties[field.propertyId];
+  const rightValue = right?.properties[field.propertyId];
+  const leftMissing = leftValue === undefined || leftValue === null;
+  const rightMissing = rightValue === undefined || rightValue === null;
+  if (leftMissing && rightMissing)
+    return 0;
+  if (leftMissing)
+    return 1;
+  if (rightMissing)
+    return -1;
+  const comparison = compareQueryScalarValues(leftValue, rightValue, field.scalarKind);
+  if (Number.isNaN(comparison))
+    return 0;
+  return field.direction === "desc" ? -comparison : comparison;
+}
+function expansionCardinality(parent, expansion, options) {
+  if (expansion.direction === "incoming")
+    return "many";
+  const objectType = options.ontology.getObjectTypeById(parent.objectTypeId);
+  const link = objectType?.links.find((candidate) => candidate.id === expansion.linkId);
+  return link?.cardinality ?? "many";
+}
+function toLinkValue(rows, cardinality) {
+  if (cardinality === "one")
+    return rows[0] ?? null;
+  return rows;
+}
+function targetKey(objectTypeId, id) {
+  return `${objectTypeId}:${id}`;
+}
+async function evaluateFallbackStart(projectId, query, options, maxRows) {
+  const objectTypeIds = query.includeSubtypes ? [query.objectTypeId, ...options.ontology.listSubTypes(query.objectTypeId)] : [query.objectTypeId];
+  const result = await options.storage.list({
+    projectId,
+    objectTypeId: objectTypeIds,
+    limit: maxRows + 1,
+    orderBy: "primaryId",
+    order: "asc"
+  });
+  if (result.objects.length > maxRows || result.hasMore || result.total > maxRows) {
+    throw new ObjectQueryExecutionError("fallback_row_limit_exceeded", `Fallback start '${query.objectTypeId}' exceeded maxFallbackRows=${maxRows}`, "$.start");
+  }
+  return completeFallbackEvaluation(result.objects.map((row, index) => ({
+    row,
+    order: index
+  })));
+}
+function completeFallbackEvaluation(entries) {
+  return {
+    entries,
+    total: entries.length,
+    hasMore: false
+  };
+}
+function matchesPredicate(row, predicate) {
+  switch (predicate.op) {
+    case "and":
+      return predicate.items.every((item) => matchesPredicate(row, item));
+    case "or":
+      return predicate.items.some((item) => matchesPredicate(row, item));
+    case "not":
+      return !matchesPredicate(row, predicate.item);
+    case "eq":
+      return queryScalarValuesEqual(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind);
+    case "neq":
+      return !queryScalarValuesEqual(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind);
+    case "lt":
+      return compareQueryScalarValues(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind) < 0;
+    case "lte":
+      return compareQueryScalarValues(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind) <= 0;
+    case "gt":
+      return compareQueryScalarValues(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind) > 0;
+    case "gte":
+      return compareQueryScalarValues(row.properties[predicate.propertyId], predicate.value, predicate.scalarKind) >= 0;
+    case "in":
+      return predicate.values.some((value) => queryScalarValuesEqual(row.properties[predicate.propertyId], value, predicate.scalarKind));
+    case "exists": {
+      const exists = Object.hasOwn(row.properties, predicate.propertyId) && row.properties[predicate.propertyId] !== undefined;
+      return predicate.value ? exists : !exists;
+    }
+    case "contains":
+      return containsValue(row.properties[predicate.propertyId], predicate.value);
+  }
+}
+function containsValue(actual, expected) {
+  if (typeof actual === "string" && typeof expected === "string") {
+    return actual.includes(expected);
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => queryScalarValuesEqual(item, expected));
+  }
+  if (isPlainObject(actual) && typeof expected === "string") {
+    return Object.hasOwn(actual, expected);
+  }
+  return false;
+}
+function sortEntries(entries, fields) {
+  return [...entries].sort((left, right) => {
+    for (const field of fields) {
+      const comparison = compareSortField(left, right, field);
+      if (comparison !== 0)
+        return comparison;
+    }
+    return left.order - right.order || rowIdentityKey(left.row).localeCompare(rowIdentityKey(right.row));
+  });
+}
+function compareSortField(left, right, field) {
+  if (field.kind === "relevance")
+    return 0;
+  const leftValue = left.row.properties[field.propertyId];
+  const rightValue = right.row.properties[field.propertyId];
+  const leftMissing = leftValue === undefined || leftValue === null;
+  const rightMissing = rightValue === undefined || rightValue === null;
+  if (leftMissing && rightMissing)
+    return 0;
+  if (leftMissing)
+    return 1;
+  if (rightMissing)
+    return -1;
+  const comparison = compareQueryScalarValues(leftValue, rightValue, field.scalarKind);
+  if (Number.isNaN(comparison))
+    return 0;
+  return field.direction === "desc" ? -comparison : comparison;
+}
+function projectRow(row, properties) {
+  const projected = {};
+  for (const propertyId of properties) {
+    if (Object.hasOwn(row.properties, propertyId)) {
+      projected[propertyId] = row.properties[propertyId];
+    }
+  }
+  return { ...row, properties: projected };
+}
+function stripOuterRowShape(query) {
+  switch (query.kind) {
+    case "limit":
+    case "page":
+    case "project":
+    case "sort":
+    case "expand":
+      return stripOuterRowShape(query.input);
+    default:
+      return query;
+  }
+}
+function validateFacetRequests(facets, objectTypeIds, options) {
+  const issues = [];
+  const maxLimit = options.maxFacetLimit ?? DEFAULT_MAX_FACET_LIMIT;
+  if (facets.length === 0) {
+    addFacetIssue(issues, "$.facets", "empty_facets", "At least one facet is required");
+  }
+  if (!Number.isInteger(maxLimit) || maxLimit <= 0) {
+    addFacetIssue(issues, "$.maxFacetLimit", "invalid_facet_bound", "maxFacetLimit must be positive");
+  }
+  const seenPropertyIds = new Set;
+  const normalizedFacets = [];
+  facets.forEach((facet, index) => {
+    const path = `$.facets[${index}]`;
+    const propertyId = typeof facet.propertyId === "string" ? facet.propertyId.trim() : "";
+    if (!propertyId) {
+      addFacetIssue(issues, `${path}.propertyId`, "missing_facet_property", "Facet propertyId is required");
+    } else if (seenPropertyIds.has(propertyId)) {
+      addFacetIssue(issues, `${path}.propertyId`, "duplicate_facet", `Facet property '${propertyId}' is requested more than once`);
+    } else {
+      seenPropertyIds.add(propertyId);
+    }
+    if (!Number.isInteger(facet.limit) || facet.limit <= 0) {
+      addFacetIssue(issues, `${path}.limit`, "invalid_facet_limit", "Facet limit must be a positive integer");
+    } else if (facet.limit > maxLimit) {
+      addFacetIssue(issues, `${path}.limit`, "facet_limit_too_large", `Facet limit must be less than or equal to ${maxLimit}`);
+    }
+    if (!propertyId)
+      return;
+    for (const objectTypeId of objectTypeIds) {
+      const objectType = options.ontology.getObjectTypeById(objectTypeId);
+      const property = objectType?.properties.find((candidate) => candidate.id === propertyId);
+      if (!objectType || !property) {
+        addFacetIssue(issues, `${path}.propertyId`, "unknown_facet_property", `Property '${propertyId}' is not defined on '${objectTypeId}'`);
+        continue;
+      }
+      if (property.query?.searchable !== true || property.query.facet !== true) {
+        addFacetIssue(issues, `${path}.propertyId`, "property_not_facetable", `Property '${propertyId}' on '${objectTypeId}' must set query.searchable: true and query.facet: true before it can be used as a facet`);
+      }
+    }
+    normalizedFacets.push({ propertyId, limit: facet.limit });
+  });
+  if (issues.length > 0) {
+    throw new ObjectQueryValidationError(issues);
+  }
+  return normalizedFacets;
+}
+function addFacetIssue(issues, path, code, message) {
+  issues.push({ path, code, message });
+}
+function buildFacetResults(rows, facets) {
+  return facets.map((facet) => ({
+    propertyId: facet.propertyId,
+    buckets: buildFacetBuckets(rows, facet)
+  }));
+}
+function buildFacetBuckets(rows, facet) {
+  const buckets = new Map;
+  for (const row of rows) {
+    if (!Object.hasOwn(row.properties, facet.propertyId))
+      continue;
+    const value = row.properties[facet.propertyId];
+    if (value === undefined)
+      continue;
+    const key = facetValueKey(value);
+    const existing = buckets.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else {
+      buckets.set(key, { value, count: 1 });
+    }
+  }
+  return [...buckets.values()].sort((left, right) => right.count - left.count || facetValueSortKey(left.value).localeCompare(facetValueSortKey(right.value))).slice(0, facet.limit);
+}
+function facetValueKey(value) {
+  return JSON.stringify(value) ?? String(value);
+}
+function facetValueSortKey(value) {
+  return JSON.stringify(value) ?? String(value);
+}
+function rowIdentityKey(row) {
+  return `${row.objectTypeId}:${row.primaryId}`;
+}
+function encodePageOffset(offset) {
+  return `${PAGE_TOKEN_PREFIX}${offset}`;
+}
+function decodePageOffset(token) {
+  if (!token)
+    return 0;
+  if (!token.startsWith(PAGE_TOKEN_PREFIX)) {
+    throw new ObjectQueryExecutionError("invalid_page_token", "Fallback page token must use the offset token format");
+  }
+  const offset = Number(token.slice(PAGE_TOKEN_PREFIX.length));
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new ObjectQueryExecutionError("invalid_page_token", "Fallback page token contains an invalid offset");
+  }
+  return offset;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// src/objects/query/explain.ts
+function explainObjectQuery(query, options = {}) {
+  const normalizedQuery = options.normalize === false ? query : normalizeObjectQuery(query);
+  const issues = options.ontology ? collectObjectQueryValidationIssues(normalizedQuery, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  }) : [];
+  const result = options.ontology && issues.length === 0 ? validateObjectQuery(normalizedQuery, {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    normalize: false
+  }).result : undefined;
+  return {
+    query,
+    normalizedQuery,
+    valid: options.ontology ? issues.length === 0 : undefined,
+    result,
+    issues,
+    tree: buildExplainNode(normalizedQuery, "$")
+  };
+}
+function buildExplainNode(query, path) {
+  switch (query.kind) {
+    case "start":
+      return {
+        path,
+        kind: query.kind,
+        summary: `start ${query.objectTypeId}`,
+        details: {
+          objectTypeId: query.objectTypeId,
+          includeSubtypes: query.includeSubtypes === true
+        },
+        children: []
+      };
+    case "filter":
+      return {
+        path,
+        kind: query.kind,
+        summary: `filter ${summarizePredicate(query.predicate)}`,
+        details: { predicate: query.predicate },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "text":
+      return {
+        path,
+        kind: query.kind,
+        summary: `text "${query.query}"`,
+        details: {
+          query: query.query,
+          fields: query.fields,
+          fieldsByObjectType: query.fieldsByObjectType
+        },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "vector":
+      return {
+        path,
+        kind: query.kind,
+        summary: `vector ${query.propertyId} k=${query.k}`,
+        details: { propertyId: query.propertyId, dimensions: query.vector.length, k: query.k },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "traverse":
+      return {
+        path,
+        kind: query.kind,
+        summary: query.sourceObjectTypeId === undefined ? `traverse ${query.direction} ${query.linkId}` : `traverse ${query.direction} ${query.sourceObjectTypeId}.${query.linkId}`,
+        details: {
+          linkId: query.linkId,
+          direction: query.direction,
+          ...query.sourceObjectTypeId === undefined ? {} : { sourceObjectTypeId: query.sourceObjectTypeId }
+        },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "set":
+      return {
+        path,
+        kind: query.kind,
+        summary: `set ${query.op}`,
+        details: { op: query.op, inputCount: query.inputs.length },
+        children: query.inputs.map((input, index) => buildExplainNode(input, `${path}.inputs[${index}]`))
+      };
+    case "sort":
+      return {
+        path,
+        kind: query.kind,
+        summary: `sort ${query.fields.map(summarizeSortField).join(", ")}`,
+        details: { fields: query.fields },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "limit":
+      return {
+        path,
+        kind: query.kind,
+        summary: `limit ${query.limit}`,
+        details: { limit: query.limit },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "page":
+      return {
+        path,
+        kind: query.kind,
+        summary: `page ${query.pageSize}`,
+        details: { pageSize: query.pageSize, hasPageToken: query.pageToken !== undefined },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "project":
+      return {
+        path,
+        kind: query.kind,
+        summary: `project ${query.properties?.join(", ") ?? "*"}`,
+        details: { properties: query.properties },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+    case "expand":
+      return {
+        path,
+        kind: query.kind,
+        summary: `expand ${query.expansions.map(summarizeExpansion).join(", ")}`,
+        details: { expansions: query.expansions },
+        children: [buildExplainNode(query.input, `${path}.input`)]
+      };
+  }
+}
+function summarizeExpansion(expansion) {
+  const head = expansion.direction === "incoming" ? `<-${expansion.linkId}` : expansion.linkId;
+  const nested = expansion.expand && expansion.expand.length > 0 ? `(${expansion.expand.map(summarizeExpansion).join(", ")})` : "";
+  return `${head}${nested}`;
+}
+function summarizePredicate(predicate) {
+  switch (predicate.op) {
+    case "and":
+    case "or":
+      return `${predicate.op}(${predicate.items.map(summarizePredicate).join(", ")})`;
+    case "not":
+      return `not(${summarizePredicate(predicate.item)})`;
+    case "in":
+      return `${predicate.propertyId} in [${predicate.values.length}]`;
+    case "exists":
+      return `${predicate.propertyId} exists=${predicate.value}`;
+    case "contains":
+      return `${predicate.propertyId} contains`;
+    default:
+      return `${predicate.propertyId} ${predicate.op}`;
+  }
+}
+function summarizeSortField(field) {
+  if (field.kind === "relevance")
+    return `relevance ${field.direction ?? "desc"}`;
+  return `${field.propertyId} ${field.direction ?? "asc"}`;
+}
+export { QueryPlanner, planObjectQuery, validateObjectQuery, collectObjectQueryValidationIssues, resolveObjectQueryResultShape, QueryExecutor, executeObjectQuery, countObjects, existsObjects, facetObjects, explainObjectQuery };
+
+//# debugId=1EDFA79E601FFF1364756E2164756E21