@sixb/core 0.0.1

package/src/objects/sdk/query-builder.ts

@@ -0,0 +1,386 @@
+/**
+ * Fluent ObjectSet query builder.
+ *
+ * This is the TypeScript authoring layer for object queries. It builds the
+ * provider-neutral object query IR and delegates execution to an
+ * `ObjectQueryExecutor` — the server runtime executor or the HTTP client
+ * executor — so the same builder serves both sides.
+ */
+import type { ValueType } from "../../ontology"
+import { OntologyValidationError } from "../../ontology/errors"
+import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
+import type {
+  ListResult,
+  ListResultWithoutTotal,
+  ObjectExpandBuilder,
+  ObjectExpandOptions,
+  ObjectQueryBuilder,
+  ObjectQueryFacetInput,
+  ObjectQueryFacetResult,
+  ObjectQueryListOptions,
+  ObjectWhereBuilder,
+  ObjectWhereClause,
+  TwinObject,
+} from "../../runtime/types"
+import { formatObjectQueryExplanation } from "../query/explain-format"
+import type {
+  ObjectExpansion,
+  ObjectQuery,
+  ObjectQueryDirection,
+  ObjectQuerySortDirection,
+  ObjectQuerySortField,
+} from "../query/ir"
+import { normalizeObjectQuery } from "../query/normalize"
+import type { ObjectQueryExecutor } from "./query-executor"
+import { resolveWhere } from "./where"
+
+type QueryBuilderParams = {
+  query: ObjectQuery
+  executor: ObjectQueryExecutor
+}
+
+export function createObjectQueryBuilder<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TRegisteredObjectTypes extends ObjectTypeWithPropertyTokens,
+  TValueTypes extends readonly ValueType[],
+>(
+  params: QueryBuilderParams
+): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+  return new ObjectQueryBuilderImpl<TObjectType, TRegisteredObjectTypes, TValueTypes>(
+    params
+  ) as unknown as ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes>
+}
+
+class ObjectQueryBuilderImpl<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TRegisteredObjectTypes extends ObjectTypeWithPropertyTokens,
+  TValueTypes extends readonly ValueType[],
+> {
+  constructor(private readonly params: QueryBuilderParams) {}
+
+  get ir(): ObjectQuery {
+    return normalizeObjectQuery(this.params.query)
+  }
+
+  where(
+    whereFn: (
+      builder: ObjectWhereBuilder<TObjectType, TValueTypes>
+    ) =>
+      | ObjectWhereClause<TObjectType, TValueTypes>
+      | readonly ObjectWhereClause<TObjectType, TValueTypes>[]
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    const predicate = resolveWhere<TObjectType, TValueTypes>(whereFn)
+    if (!predicate)
+      return this as unknown as ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes>
+
+    return this.withQuery({
+      kind: "filter",
+      input: this.ir,
+      predicate,
+    })
+  }
+
+  search(
+    query: string,
+    options?: { fields?: readonly PropertyToken<TObjectType["id"], string>[] }
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery({
+      kind: "text",
+      input: this.ir,
+      query,
+      fields: options?.fields?.map(propertyTokenToId),
+    })
+  }
+
+  vector(
+    property: PropertyToken<TObjectType["id"], string>,
+    vector: readonly number[],
+    options: { k: number }
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery({
+      kind: "vector",
+      input: this.ir,
+      propertyId: property.id,
+      vector,
+      k: options.k,
+    })
+  }
+
+  traverse(
+    link: LinkToken<TObjectType["id"], string, string>,
+    options?: { direction?: "outgoing" }
+  ): ObjectQueryBuilder<ObjectTypeWithPropertyTokens, TRegisteredObjectTypes, TValueTypes>
+  traverse(
+    link: LinkToken<string, string, TObjectType["id"] | readonly TObjectType["id"][]>,
+    options: { direction: "incoming" }
+  ): ObjectQueryBuilder<ObjectTypeWithPropertyTokens, TRegisteredObjectTypes, TValueTypes>
+  traverse(
+    link: LinkToken,
+    options: { direction?: ObjectQueryDirection } = {}
+  ): ObjectQueryBuilder<ObjectTypeWithPropertyTokens, TRegisteredObjectTypes, TValueTypes> {
+    const direction = options.direction ?? "outgoing"
+    if (direction === "outgoing") {
+      requireSingleTargetObjectTypeId(link)
+    }
+
+    return new ObjectQueryBuilderImpl<
+      ObjectTypeWithPropertyTokens,
+      TRegisteredObjectTypes,
+      TValueTypes
+    >({
+      ...this.params,
+      query: {
+        kind: "traverse",
+        input: this.ir,
+        linkId: link.id,
+        direction,
+        // Several object types can declare a link with the same id. The token
+        // names exactly one source type, so incoming traversal pins it —
+        // matching the result type the fluent API advertises.
+        ...(direction === "incoming" ? { sourceObjectTypeId: link.objectTypeId } : {}),
+      },
+    }) as unknown as ObjectQueryBuilder<
+      ObjectTypeWithPropertyTokens,
+      TRegisteredObjectTypes,
+      TValueTypes
+    >
+  }
+
+  expand(
+    link: LinkToken<string, string, string | readonly string[]>,
+    optionsOrBuild?: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild,
+    build?: NestedExpandBuild
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery({
+      kind: "expand",
+      input: this.ir,
+      expansions: [buildExpansion(link, optionsOrBuild, build)],
+    })
+  }
+
+  orderBy(
+    property: PropertyToken<TObjectType["id"], string>,
+    direction?: ObjectQuerySortDirection
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery(
+      appendSortField(this.ir, {
+        kind: "property",
+        propertyId: property.id,
+        direction,
+      })
+    )
+  }
+
+  orderByRelevance(
+    direction?: ObjectQuerySortDirection
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery(
+      appendSortField(this.ir, {
+        kind: "relevance",
+        direction,
+      })
+    )
+  }
+
+  limit(limit: number): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery({
+      kind: "limit",
+      input: this.ir,
+      limit,
+    })
+  }
+
+  page(input: {
+    pageSize: number
+    pageToken?: string
+  }): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return this.withQuery({
+      kind: "page",
+      input: this.ir,
+      pageSize: input.pageSize,
+      pageToken: input.pageToken,
+    })
+  }
+
+  validate() {
+    if (!this.params.executor.validate) {
+      throw new OntologyValidationError(
+        "[Sixb] validate() requires ontology access and is not supported by this query executor. Execute the query to get server-side validation."
+      )
+    }
+    return this.params.executor.validate(this.ir)
+  }
+
+  explain() {
+    if (!this.params.executor.explain) {
+      throw new OntologyValidationError(
+        "[Sixb] explain() requires ontology access and is not supported by this query executor."
+      )
+    }
+    return this.params.executor.explain(this.ir)
+  }
+
+  formatExplanation(): string {
+    return formatObjectQueryExplanation(this.explain())
+  }
+
+  async list(): Promise<ListResult<TwinObject<TObjectType, TValueTypes>>>
+  async list(options: {
+    includeTotal: false
+  }): Promise<ListResultWithoutTotal<TwinObject<TObjectType, TValueTypes>>>
+  async list(options: {
+    includeTotal?: true
+  }): Promise<ListResult<TwinObject<TObjectType, TValueTypes>>>
+  async list(
+    options?: ObjectQueryListOptions
+  ): Promise<
+    | ListResult<TwinObject<TObjectType, TValueTypes>>
+    | ListResultWithoutTotal<TwinObject<TObjectType, TValueTypes>>
+  > {
+    const result = await this.params.executor.list(this.ir, {
+      includeTotal: options?.includeTotal,
+    })
+    const objects = result.objects.map(
+      (row) => row as unknown as TwinObject<TObjectType, TValueTypes>
+    )
+
+    if (options?.includeTotal === false) {
+      return {
+        objects,
+        hasMore: result.hasMore,
+        nextPageToken: result.nextPageToken,
+      }
+    }
+
+    return {
+      objects,
+      hasMore: result.hasMore,
+      nextPageToken: result.nextPageToken,
+      total: result.total ?? result.objects.length,
+    }
+  }
+
+  async count(): Promise<number> {
+    return this.params.executor.count(this.ir)
+  }
+
+  async exists(): Promise<boolean> {
+    return this.params.executor.exists(this.ir)
+  }
+
+  async facets(
+    input: readonly ObjectQueryFacetInput<TObjectType>[]
+  ): Promise<ObjectQueryFacetResult[]> {
+    return this.params.executor.facets(
+      this.ir,
+      input.map((facet) => ({
+        propertyId: facet.property.id,
+        limit: facet.limit,
+      }))
+    )
+  }
+
+  async first(): Promise<TwinObject<TObjectType, TValueTypes> | null> {
+    const result = await this.params.executor.list({ kind: "limit", input: this.ir, limit: 1 })
+    const row = result.objects[0]
+    return row ? (row as unknown as TwinObject<TObjectType, TValueTypes>) : null
+  }
+
+  private withQuery(
+    query: ObjectQuery
+  ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    return new ObjectQueryBuilderImpl<TObjectType, TRegisteredObjectTypes, TValueTypes>({
+      ...this.params,
+      query,
+    }) as unknown as ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes>
+  }
+}
+
+type AnyExpandBuilder = ObjectExpandBuilder<
+  ObjectTypeWithPropertyTokens,
+  ObjectTypeWithPropertyTokens
+>
+type NestedExpandBuild = (nested: AnyExpandBuilder) => AnyExpandBuilder
+
+/**
+ * Runtime backing for the nested `.expand(..., (e) => …)` callback. Immutable,
+ * mirroring the query builder: each `expand` returns a new instance so the
+ * accumulated expansions are never shared between branches.
+ */
+class ObjectExpandBuilderImpl {
+  constructor(readonly expansions: readonly ObjectExpansion[] = []) {}
+
+  expand(
+    link: LinkToken<string, string, string | readonly string[]>,
+    optionsOrBuild?: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild,
+    build?: NestedExpandBuild
+  ): ObjectExpandBuilderImpl {
+    return new ObjectExpandBuilderImpl([
+      ...this.expansions,
+      buildExpansion(link, optionsOrBuild, build),
+    ])
+  }
+}
+
+function buildExpansion(
+  link: LinkToken<string, string, string | readonly string[]>,
+  optionsOrBuild: ObjectExpandOptions<ObjectTypeWithPropertyTokens> | NestedExpandBuild | undefined,
+  build: NestedExpandBuild | undefined
+): ObjectExpansion {
+  // `.expand(link, build)` and `.expand(link, options, build)` are both valid:
+  // a function in the second slot is the nested builder, otherwise it is options.
+  const options = typeof optionsOrBuild === "function" ? undefined : optionsOrBuild
+  const nestedBuild = typeof optionsOrBuild === "function" ? optionsOrBuild : build
+
+  let nested: readonly ObjectExpansion[] = []
+  if (nestedBuild) {
+    const result = nestedBuild(new ObjectExpandBuilderImpl() as unknown as AnyExpandBuilder)
+    nested = (result as unknown as ObjectExpandBuilderImpl).expansions
+  }
+
+  return {
+    linkId: link.id,
+    direction: "outgoing",
+    ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+    ...(options?.orderBy ? { orderBy: options.orderBy.map(expansionSortToField) } : {}),
+    ...(nested.length > 0 ? { expand: nested } : {}),
+  }
+}
+
+function expansionSortToField(sort: {
+  property: PropertyToken
+  direction?: ObjectQuerySortDirection
+}): ObjectQuerySortField {
+  return { kind: "property", propertyId: sort.property.id, direction: sort.direction }
+}
+
+function appendSortField(
+  query: ObjectQuery,
+  field: Extract<ObjectQuery, { kind: "sort" }>["fields"][number]
+): ObjectQuery {
+  if (query.kind === "sort") {
+    return {
+      ...query,
+      fields: [...query.fields, field],
+    }
+  }
+
+  return {
+    kind: "sort",
+    input: query,
+    fields: [field],
+  }
+}
+
+function propertyTokenToId(token: PropertyToken): string {
+  return token.id
+}
+
+function requireSingleTargetObjectTypeId(link: LinkToken): void {
+  const target = link.targetObjectTypeId
+  if (target === "*" || typeof target !== "string") {
+    throw new OntologyValidationError(
+      "[Sixb] Object query traverse requires a single concrete outgoing target type"
+    )
+  }
+}

package/src/objects/sdk/query-executor.ts

@@ -0,0 +1,62 @@
+/**
+ * Execution contract for the fluent object query builder.
+ *
+ * The builder only constructs query IR; terminals delegate here. The server
+ * runtime implements this against storage, and `@sixb/client` implements it
+ * against the HTTP query routes, so both share one builder.
+ */
+import type { ObjectQueryFacetResult } from "../../runtime/types"
+import type { ObjectQueryExplanation } from "../query/explain"
+import type { ObjectQuery } from "../query/ir"
+import type { ValidatedObjectQuery } from "../query/validate"
+
+export type ObjectQueryExecutorRow = {
+  primaryId: string
+  objectTypeId: string
+  properties: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+  /** Linked objects attached by an `expand` node, keyed by link id. The builder
+   * types these precisely; this contract carries them through untyped. Recurses
+   * over the same light row shape so both executors (the server's full
+   * `ObjectRow` and the client's wire-reconstructed row) satisfy it. */
+  links?: ObjectQueryExecutorLinks
+}
+
+export type ObjectQueryExecutorLinks = Record<string, ObjectQueryExecutorLinkValue>
+export type ObjectQueryExecutorLinkValue =
+  | ObjectQueryExecutorExpandedRow
+  | readonly ObjectQueryExecutorExpandedRow[]
+  | null
+export type ObjectQueryExecutorExpandedRow = ObjectQueryExecutorRow & {
+  linkProperties?: Record<string, unknown>
+}
+
+export type ObjectQueryExecutorListResult = {
+  objects: readonly ObjectQueryExecutorRow[]
+  hasMore: boolean
+  total?: number
+  nextPageToken?: string
+}
+
+export type ObjectQueryExecutorFacetRequest = {
+  propertyId: string
+  limit: number
+}
+
+export interface ObjectQueryExecutor {
+  list(
+    query: ObjectQuery,
+    options?: { includeTotal?: boolean }
+  ): Promise<ObjectQueryExecutorListResult>
+  count(query: ObjectQuery): Promise<number>
+  exists(query: ObjectQuery): Promise<boolean>
+  facets(
+    query: ObjectQuery,
+    facets: readonly ObjectQueryExecutorFacetRequest[]
+  ): Promise<ObjectQueryFacetResult[]>
+  /** Validation requires ontology access and is unavailable on remote executors. */
+  validate?(query: ObjectQuery): ValidatedObjectQuery
+  /** Explanation requires ontology access and is unavailable on remote executors. */
+  explain?(query: ObjectQuery): ObjectQueryExplanation
+}

package/src/objects/sdk/runtime-query-executor.ts

@@ -0,0 +1,88 @@
+/**
+ * Server-side ObjectQueryExecutor backed by the shared query executor and storage.
+ * Validation, planning, fallback, and execution all run in-process here; the
+ * HTTP executor in `@sixb/client` is the remote counterpart.
+ */
+
+import type { AuthorizationContext } from "../../authorization"
+import type { OntologyRegistry } from "../../ontology"
+import type { Storage } from "../../storage"
+import {
+  countObjects,
+  executeObjectQuery,
+  existsObjects,
+  facetObjects,
+  ObjectQueryPlanningError,
+} from "../query"
+import { explainObjectQuery } from "../query/explain"
+import type { ObjectQuery } from "../query/ir"
+import { validateObjectQuery } from "../query/validate"
+import type { ObjectQueryExecutor, ObjectQueryExecutorFacetRequest } from "./query-executor"
+
+export function createRuntimeQueryExecutor(params: {
+  projectId: string
+  ontology: OntologyRegistry
+  storage: Storage
+  authorization?: AuthorizationContext
+}): ObjectQueryExecutor {
+  const { projectId, ontology, storage, authorization } = params
+  const executorOptions = { ontology, storage: storage.objects, authorization }
+
+  return {
+    async list(query: ObjectQuery, options?: { includeTotal?: boolean }) {
+      try {
+        return await executeObjectQuery(
+          { projectId, query, includeTotal: options?.includeTotal },
+          executorOptions
+        )
+      } catch (error) {
+        if (error instanceof ObjectQueryPlanningError) {
+          throw addSdkPlanningHints(error)
+        }
+        throw error
+      }
+    },
+
+    async count(query: ObjectQuery) {
+      const result = await countObjects({ projectId, query }, executorOptions)
+      return result.count
+    },
+
+    async exists(query: ObjectQuery) {
+      const result = await existsObjects({ projectId, query }, executorOptions)
+      return result.exists
+    },
+
+    async facets(query: ObjectQuery, facets: readonly ObjectQueryExecutorFacetRequest[]) {
+      const result = await facetObjects({ projectId, query, facets }, executorOptions)
+      return result.facets.map((facet) => ({
+        propertyId: facet.propertyId,
+        buckets: [...facet.buckets],
+      }))
+    },
+
+    validate(query: ObjectQuery) {
+      return validateObjectQuery(query, { ontology, normalize: false })
+    },
+
+    explain(query: ObjectQuery) {
+      return explainObjectQuery(query, { ontology, normalize: false })
+    },
+  }
+}
+
+function addSdkPlanningHints(error: ObjectQueryPlanningError): ObjectQueryPlanningError {
+  if (!error.issues.some((issue) => issue.code === "fallback_requires_bound")) return error
+
+  return new ObjectQueryPlanningError(
+    error.issues.map((issue) =>
+      issue.code === "fallback_requires_bound"
+        ? {
+            ...issue,
+            message:
+              "Object query fallback requires an explicit result bound. Add .limit(n) or .page({ pageSize: n }) before .list().",
+          }
+        : issue
+    )
+  )
+}

package/src/objects/sdk/telemetry-channel.ts

@@ -0,0 +1,81 @@
+/**
+ * Telemetry channel factory for ObjectByIdHandle.
+ *
+ * Creates a per-property channel that writes through the low-level `writeTelemetryBatch` leaf and
+ * reads the same series back through `getTelemetryHistoryBatch`, both keyed by the property token.
+ */
+import type { TelemetryPointWrite } from "../../materialization/model"
+import type { ValueType } from "../../ontology"
+import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import {
+  assertPropertyTokenBelongsToObjectType,
+  assertTelemetryProperty,
+} from "../../ontology/validation"
+import { RuntimeError } from "../../runtime/errors"
+import type {
+  TelemetryChannel,
+  TelemetryHistoryInput,
+  TelemetryPropertyToken,
+} from "../../runtime/types"
+import type { ResolvedObjectContext } from "../context"
+import { getTelemetryHistoryBatch, writeTelemetryBatch } from "../telemetry"
+
+export function createTelemetryChannel<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TValueTypes extends readonly ValueType[],
+>(ctx: ResolvedObjectContext, primaryId: string) {
+  return <TToken extends TelemetryPropertyToken<TObjectType>>(
+    property: TToken
+  ): TelemetryChannel<TToken, TValueTypes> => {
+    const { objectType } = ctx
+    assertPropertyTokenBelongsToObjectType(objectType, property)
+    assertTelemetryProperty(property.property)
+
+    const series = { objectTypeId: objectType.id, objectId: primaryId, propertyId: property.id }
+
+    const channel = {
+      append: async (input: { value: unknown; unit?: string; at: Date }) => {
+        // Value and unit validation, plus schema normalization, happen inside the Materializer.
+        await writeTelemetryBatch(ctx, [
+          {
+            series: {
+              object: { objectTypeId: objectType.id, primaryId },
+              propertyId: property.id,
+            },
+            value: input.value as TelemetryPointWrite["value"],
+            ...(input.unit !== undefined ? { unit: input.unit } : {}),
+            at: input.at.toISOString(),
+          },
+        ])
+      },
+
+      history: async (input: TelemetryHistoryInput = {}) => {
+        const timeseries = ctx.storage.timeseries
+        if (!timeseries) {
+          throw new RuntimeError("[Sixb] Reading telemetry requires storage.timeseries support.")
+        }
+
+        const [result] = await getTelemetryHistoryBatch(
+          {
+            projectId: ctx.projectId,
+            series: [series],
+            ...(input.from !== undefined ? { from: input.from } : {}),
+            ...(input.to !== undefined ? { to: input.to } : {}),
+            ...(input.limit !== undefined ? { limitPerSeries: input.limit } : {}),
+            ...(input.order !== undefined ? { order: input.order } : {}),
+          },
+          { storage: timeseries, authorization: ctx.authorization }
+        )
+
+        return (result?.points ?? []).map((point) => ({
+          value: point.value,
+          at: point.at,
+          ...(point.unit !== undefined ? { unit: point.unit } : {}),
+        }))
+      },
+    }
+
+    // Cast needed: generic token inference boundary — TToken is narrower than what `channel` sees
+    return channel as unknown as TelemetryChannel<TToken, TValueTypes>
+  }
+}

package/src/objects/sdk/where.ts

@@ -0,0 +1,87 @@
+/**
+ * Where-clause builder for typed ObjectSet queries.
+ *
+ * Provides `createWhereBuilder` (predicate DSL) and `resolveWhere` (evaluator).
+ * The builder emits object query IR predicates. Property predicates are created
+ * on demand through a Proxy, so no runtime ontology access is required —
+ * property names are constrained at compile time and validated server-side.
+ */
+import type { ValueType } from "../../ontology"
+import type { ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import type { ObjectWhereBuilder, ObjectWhereClause } from "../../runtime/types"
+import type { ObjectQueryPredicate } from "../query"
+
+function createPropertyPredicate(propertyId: string) {
+  const comparison = (op: "eq" | "neq" | "lt" | "lte" | "gt" | "gte") => {
+    return (value: unknown) => ({
+      propertyId,
+      op,
+      value,
+    })
+  }
+
+  return {
+    eq: comparison("eq"),
+    neq: comparison("neq"),
+    lt: comparison("lt"),
+    lte: comparison("lte"),
+    gt: comparison("gt"),
+    gte: comparison("gte"),
+    in: (values: readonly unknown[]) => ({
+      propertyId,
+      op: "in",
+      values,
+    }),
+    exists: (value = true) => ({
+      propertyId,
+      op: "exists",
+      value,
+    }),
+    contains: (value: unknown) => ({
+      propertyId,
+      op: "contains",
+      value,
+    }),
+  }
+}
+
+export function createWhereBuilder<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TValueTypes extends readonly ValueType[],
+>(): ObjectWhereBuilder<TObjectType, TValueTypes> {
+  const p = new Proxy(
+    {},
+    {
+      get: (_target, propertyId) =>
+        typeof propertyId === "string" ? createPropertyPredicate(propertyId) : undefined,
+    }
+  )
+
+  return {
+    p,
+    and: (...items: readonly ObjectQueryPredicate[]) => ({ op: "and", items }),
+    or: (...items: readonly ObjectQueryPredicate[]) => ({ op: "or", items }),
+    not: (item: ObjectQueryPredicate) => ({ op: "not", item }),
+  } as ObjectWhereBuilder<TObjectType, TValueTypes>
+}
+
+export function resolveWhere<
+  TObjectType extends ObjectTypeWithPropertyTokens,
+  TValueTypes extends readonly ValueType[],
+>(
+  whereFn?: (
+    builder: ObjectWhereBuilder<TObjectType, TValueTypes>
+  ) =>
+    | ObjectWhereClause<TObjectType, TValueTypes>
+    | readonly ObjectWhereClause<TObjectType, TValueTypes>[]
+): ObjectQueryPredicate | undefined {
+  if (!whereFn) return undefined
+  const whereBuilder = createWhereBuilder<TObjectType, TValueTypes>()
+  const whereInput = whereFn(whereBuilder)
+  if (!whereInput) return undefined
+  const predicates = (
+    Array.isArray(whereInput) ? whereInput : [whereInput]
+  ) as readonly ObjectQueryPredicate[]
+  if (predicates.length === 0) return undefined
+  return predicates.length === 1 ? predicates[0] : { op: "and", items: predicates }
+}