@sixb/core 0.1.11 → 0.1.13

package/src/objects/query/executor.ts

@@ -1,5 +1,6 @@
 import { type AuthorizationContext, assertAuthorized } from "../../authorization"
 import type { RuntimeAuthorization } from "../../execution/types"
+import type { EmbeddingModelCatalog } from "../../models/catalog"
 import type { OntologyRegistry } from "../../ontology"
 import type {
   CountObjectsResult,
@@ -17,6 +18,7 @@ import type {
   QueryObjectsResult,
 } from "../../storage"
 import { linkBatchKey, MAX_OBJECT_READ_FACETS, objectBatchKey } from "../../storage"
+import { resolveVectorSearchText } from "../vectors/resolve-query"
 import {
   ObjectQueryExecutionError,
   ObjectQueryPlanningError,
@@ -28,6 +30,7 @@ import type {
   ObjectQueryPredicate,
   ObjectQueryResultShape,
   ObjectQuerySortField,
+  QueryScalarKind,
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
 import { type ObjectQueryPlan, type ObjectQueryPlanningOptions, planObjectQuery } from "./planner"
@@ -50,6 +53,7 @@ export interface QueryExecutorOptions
     | "hasFacetObjects"
   > {
   ontology: OntologyRegistry
+  embeddingModels?: EmbeddingModelCatalog
   storage: ObjectReadStorage
   maxLimit?: number
   maxPageSize?: number
@@ -68,6 +72,7 @@ export interface QueryExecutorOptions
 }
 
 export interface ExecuteObjectQueryInput {
+  signal?: AbortSignal
   projectId: string
   query: ObjectQuery
   includeTotal?: boolean
@@ -179,7 +184,12 @@ export async function executeObjectQuery(
     }
     const result = await options.storage.queryObjects({
       projectId: input.projectId,
-      query: plan.query,
+      query: await resolveVectorSearchText(
+        plan.query,
+        options.ontology,
+        options.embeddingModels,
+        input.signal
+      ),
       includeTotal: input.includeTotal,
     })
     return { ...result, plan }
@@ -244,7 +254,7 @@ export async function countObjects(
     }
     const result = await options.storage.countObjects({
       projectId: input.projectId,
-      query: plan.query,
+      query: await resolveVectorSearchText(plan.query, options.ontology, options.embeddingModels),
     })
     return { ...result, plan }
   }
@@ -305,7 +315,7 @@ export async function existsObjects(
     }
     const result = await options.storage.existsObjects({
       projectId: input.projectId,
-      query: plan.query,
+      query: await resolveVectorSearchText(plan.query, options.ontology, options.embeddingModels),
     })
     return { ...result, plan }
   }
@@ -367,7 +377,7 @@ export async function facetObjects(
     }
     const result = await options.storage.facetObjects({
       projectId: input.projectId,
-      query: plan.query,
+      query: await resolveVectorSearchText(plan.query, options.ontology, options.embeddingModels),
       facets,
     })
     return { ...result, plan }
@@ -1095,17 +1105,25 @@ function matchesPredicate(row: ObjectRow, predicate: ObjectQueryPredicate): bool
       return predicate.value ? exists : !exists
     }
     case "contains":
-      return containsValue(row.properties[predicate.propertyId], predicate.value)
+      return containsValue(
+        row.properties[predicate.propertyId],
+        predicate.value,
+        predicate.scalarKind
+      )
   }
 }
 
-function containsValue(actual: unknown, expected: unknown): boolean {
+function containsValue(
+  actual: unknown,
+  expected: unknown,
+  itemScalarKind: QueryScalarKind | undefined
+): boolean {
   if (typeof actual === "string" && typeof expected === "string") {
     return actual.includes(expected)
   }
 
   if (Array.isArray(actual)) {
-    return actual.some((item) => queryScalarValuesEqual(item, expected))
+    return actual.some((item) => queryScalarValuesEqual(item, expected, itemScalarKind))
   }
 
   if (isPlainObject(actual) && typeof expected === "string") {

package/src/objects/query/explain.ts

@@ -119,8 +119,13 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
       return {
         path,
         kind: query.kind,
-        summary: `vector ${query.propertyId} k=${query.k}`,
-        details: { propertyId: query.propertyId, dimensions: query.vector.length, k: query.k },
+        summary: `vector profile ${query.profile} k=${query.k}`,
+        details: {
+          profile: query.profile,
+          input: typeof query.vector === "string" ? "text" : "vector",
+          dimensions: typeof query.vector === "string" ? undefined : query.vector.length,
+          k: query.k,
+        },
         children: [buildExplainNode(query.input, `${path}.input`)],
       }
     case "traverse":

package/src/objects/query/index.ts

@@ -1,3 +1,5 @@
+export { normalizeVector, vectorSearchCandidateLimit } from "../vectors/profile"
+export { hasVectorProfile, isVectorProfileQuery } from "../vectors/query"
 export type { ObjectQueryPlanningIssue } from "./errors"
 export {
   ObjectQueryExecutionError,

package/src/objects/query/ir.ts

@@ -20,6 +20,8 @@ export type QueryScalarKind =
   | "decimal"
   | "date"
   | "timestamp"
+  /** A `{ type: "user", id }` value, equal when both fields are. */
+  | "userRef"
 
 export type ObjectQuery =
   | ObjectQueryStart
@@ -77,8 +79,12 @@ export interface ObjectQueryText {
 export interface ObjectQueryVector {
   kind: "vector"
   input: ObjectQuery
-  vector: readonly number[]
-  propertyId: string
+  /** Text is embedded by the server using the named profile's model before storage execution. */
+  vector: readonly number[] | string
+  profile: string
+  /** Populated by canonical validation, never trusted from the wire. */
+  configuration?: string
+  source?: readonly string[]
   k: number
 }
 
@@ -210,6 +216,11 @@ export interface ObjectQueryPredicateContains {
   op: "contains"
   propertyId: string
   value: unknown
+  /**
+   * Core-resolved scalar schema of the array's items when the property is an array; never
+   * authored by callers. String substring and map key matches carry none.
+   */
+  scalarKind?: QueryScalarKind
 }
 
 export type ObjectQuerySortField =

package/src/objects/query/normalize.ts

@@ -39,7 +39,11 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
           : undefined,
       }
     case "vector":
-      return { ...query, input: normalizeObjectQuery(query.input), vector: [...query.vector] }
+      return {
+        ...query,
+        input: normalizeObjectQuery(query.input),
+        vector: typeof query.vector === "string" ? query.vector : [...query.vector],
+      }
     case "traverse":
       return { ...query, input: normalizeObjectQuery(query.input) }
     case "set":

package/src/objects/query/planner.ts

@@ -338,6 +338,7 @@ function predicateScalarOperation(
     case "eq":
     case "neq":
     case "in":
+    case "contains":
       return "equality"
     case "lt":
     case "lte":

package/src/objects/query/scalar-values.ts

@@ -33,6 +33,9 @@ export function compareQueryScalarValues(
     case "date":
     case "timestamp":
       return compareTemporalValues(left, right)
+    case "userRef":
+      // Identity only: user references have no order.
+      return Number.NaN
   }
 }
 
@@ -52,10 +55,26 @@ export function queryScalarValuesEqual(
     return !Number.isNaN(comparison) && comparison === 0
   }
 
+  if (scalarKind === "userRef") return userRefsEqual(left, right)
   if (scalarKind !== undefined) return Object.is(left, right)
   return runtimeValuesEqual(left, right)
 }
 
+function userRefsEqual(left: unknown, right: unknown): boolean {
+  if (left === null || right === null) return left === right
+  return (
+    isRecord(left) &&
+    isRecord(right) &&
+    left.type === right.type &&
+    typeof left.id === "string" &&
+    left.id === right.id
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
 function compareRuntimeValues(left: unknown, right: unknown): number {
   if (typeof left === "number" && typeof right === "number") return left - right
   if (typeof left === "string" && typeof right === "string") return compareStrings(left, right)

package/src/objects/query/validate.ts

@@ -8,7 +8,16 @@ import type {
 } from "../../ontology"
 import { normalizeDecimalValue } from "../../ontology"
 import { formatUnknownObjectTypeMessage } from "../../ontology/errors"
+import {
+  isContainsSchema,
+  isExactSchema,
+  isSortableSchema,
+  isTextSchema,
+  queryScalarKindForSchema,
+} from "../../ontology/query-capabilities"
 import { validatePropertyValue, validateSchemaValue } from "../../ontology/validation"
+import { MAX_VECTOR_K, normalizeVector, vectorConfiguration } from "../vectors/profile"
+import { hasVectorProfile, isVectorProfileQuery } from "../vectors/query"
 import { ObjectQueryValidationError } from "./errors"
 import type {
   ObjectExpansion,
@@ -18,6 +27,7 @@ import type {
   ObjectQueryResultShape,
   ObjectQuerySetOperation,
   ObjectQuerySortField,
+  ObjectQueryVector,
   QueryScalarKind,
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
@@ -172,6 +182,7 @@ export function validateObjectQueryWithAdmission(
 ): AdmittedObjectQuery {
   const normalized = options.normalize === false ? query : normalizeObjectQuery(query)
   const ctx = createValidationContext(options, admission)
+  validateVectorComposition(query, ctx)
   const validation = validateQueryNode(normalized, "$", ctx)
 
   if (ctx.issues.length > 0) {
@@ -194,6 +205,7 @@ export function collectObjectQueryValidationIssues(
 ): readonly ObjectQueryValidationIssue[] {
   const normalized = options.normalize === false ? query : normalizeObjectQuery(query)
   const ctx = createValidationContext(options, NOOP_QUERY_ADMISSION)
+  validateVectorComposition(query, ctx)
   validateQueryNode(normalized, "$", ctx)
   return ctx.issues
 }
@@ -205,6 +217,16 @@ export function resolveObjectQueryResultShape(
   return validateObjectQuery(query, options).result
 }
 
+function validateVectorComposition(query: ObjectQuery, ctx: QueryValidationContext): void {
+  if (hasVectorProfile(query) && !isVectorProfileQuery(query))
+    ctx.issues.push({
+      path: "$",
+      code: "vector.composition",
+      message:
+        "Vector profiles support one top-k over one concrete type, with filters before ranking and optional limit/project after it.",
+    })
+}
+
 function createValidationContext(
   options: ObjectQueryValidationOptions,
   admission: ObjectQuerySemanticAdmission
@@ -312,18 +334,15 @@ function dispatchQueryNode(
     }
     case "vector": {
       const input = validateQueryNode(query.input, `${path}.input`, ctx)
-      validateVectorQuery(
-        query.vector,
-        query.propertyId,
-        query.k,
-        input.result,
-        input.admissionState,
-        path,
-        ctx
-      )
       return {
         result: input.result,
-        query: { ...query, input: input.query },
+        query: validateVectorProfileQuery(
+          { ...query, input: input.query },
+          input.result,
+          input.admissionState,
+          path,
+          ctx
+        ),
         admissionState: input.admissionState,
       }
     }
@@ -581,8 +600,15 @@ function validatePredicate(
         addIssue(ctx, path, "invalid_exists_value", "Predicate 'exists' value must be boolean")
       }
       return predicate
-    case "contains":
-      resolveAndValidatePredicateProperty(predicate.propertyId, predicate.op, shape, path, ctx)
+    case "contains": {
+      const { scalarKind: _authoredScalarKind, ...authoredPredicate } = predicate
+      const scalarKind = resolveAndValidatePredicateProperty(
+        predicate.propertyId,
+        predicate.op,
+        shape,
+        path,
+        ctx
+      )
       validateContainsValue(predicate.propertyId, predicate.value, shape, path, ctx)
       admitProperty(ctx, {
         state: admissionState,
@@ -590,7 +616,12 @@ function validatePredicate(
         use: "filter",
         path,
       })
-      return predicate
+      return {
+        ...authoredPredicate,
+        value: normalizeObjectQueryValue(predicate.value, scalarKind),
+        ...(scalarKind ? { scalarKind } : {}),
+      }
+    }
   }
 }
 
@@ -653,10 +684,41 @@ function resolveAndValidatePredicateProperty(
     }
   }
 
-  if (op === "exists" || op === "contains") return undefined
+  if (op === "exists") return undefined
+  if (op === "contains") return resolveArrayItemScalarKind(schemas, ctx)
   return resolveCommonQueryScalarKind(schemas, propertyId, path, ctx)
 }
 
+/**
+ * Item scalar kind for `contains` over arrays, so array membership compares items the way `eq`
+ * compares values. Strings and maps keep substring and key semantics, and mixed item kinds keep the
+ * untyped comparison.
+ */
+function resolveArrayItemScalarKind(
+  schemas: readonly Schema[],
+  ctx: QueryValidationContext
+): QueryScalarKind | undefined {
+  const kinds = new Set<QueryScalarKind | undefined>()
+  for (const schema of schemas) {
+    if (typeof schema === "string" || schema.type !== "array") return undefined
+    const items = resolveValueTypeRefs(schema.items, ctx.valueTypesById)
+    kinds.add(items ? queryScalarKindForSchema(items) : undefined)
+  }
+  return kinds.size === 1 ? [...kinds][0] : undefined
+}
+
+function resolveValueTypeRefs(
+  schema: Schema,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  seen = new Set<string>()
+): Schema | undefined {
+  if (typeof schema === "string" || schema.type !== "valueTypeRef") return schema
+  if (seen.has(schema.valueTypeId)) return undefined
+  seen.add(schema.valueTypeId)
+  const resolved = schema._resolved ?? valueTypesById.get(schema.valueTypeId)?.schema
+  return resolved ? resolveValueTypeRefs(resolved, valueTypesById, seen) : undefined
+}
+
 function normalizeObjectQueryValue(value: unknown, scalarKind: QueryScalarKind | undefined) {
   if (scalarKind !== "decimal" || typeof value !== "string") return value
   try {
@@ -691,12 +753,6 @@ function resolveCommonQueryScalarKind(
   return undefined
 }
 
-function queryScalarKindForSchema(schema: Schema): QueryScalarKind | undefined {
-  if (typeof schema === "string") return schema === "fileRef" ? undefined : schema
-  if (schema.type === "enum") return schema.valueType === "integer" ? "integer" : "string"
-  return undefined
-}
-
 function validatePredicateValue(
   propertyId: string,
   value: unknown,
@@ -736,7 +792,7 @@ function validateContainsValue(
     if (!schema) continue
 
     if (typeof schema === "string") {
-      if (schema === "string" || schema === "uuid") {
+      if (isContainsSchema(schema)) {
         if (typeof value !== "string") {
           addIssue(
             ctx,
@@ -845,67 +901,63 @@ function validateTextQuery(
   return fieldsByObjectType ? { fieldsByObjectType } : {}
 }
 
-function validateVectorQuery(
-  vector: readonly number[],
-  propertyId: string,
-  k: number,
+function validateVectorProfileQuery(
+  query: ObjectQueryVector,
   shape: ObjectQueryResultShape,
-  admissionState: ObjectQueryAdmissionState,
+  state: ObjectQueryAdmissionState,
   path: string,
   ctx: QueryValidationContext
-): void {
-  if (!Number.isInteger(k) || k <= 0) {
-    addIssue(ctx, path, "invalid_vector_k", "Vector query k must be a positive integer")
-  }
-
-  if (vector.length === 0) {
-    addIssue(ctx, path, "empty_vector", "Vector query vector must not be empty")
-  }
-
-  if (vector.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
-    addIssue(ctx, path, "invalid_vector_value", "Vector query vector values must be finite numbers")
+): ObjectQueryVector {
+  const types = getObjectTypesForResult(shape, ctx)
+  if (
+    types.length !== 1 ||
+    !Number.isSafeInteger(query.k) ||
+    query.k < 1 ||
+    query.k > MAX_VECTOR_K
+  ) {
+    addIssue(
+      ctx,
+      path,
+      "invalid_vector_profile_query",
+      `Vector search requires one type, one profile and k between 1 and ${MAX_VECTOR_K}`
+    )
+    return query
   }
-
-  for (const objectType of getObjectTypesForResult(shape, ctx)) {
-    admitProperty(ctx, {
-      state: admissionState,
-      propertyId,
-      objectTypeId: objectType.id,
-      use: "vector",
+  let input = query.input
+  while (input.kind === "filter") input = input.input
+  if (input.kind !== "start" || input.includeSubtypes)
+    addIssue(
+      ctx,
       path,
-    })
-    const property = getProperty(objectType, propertyId)
-    if (!property) {
-      addIssue(
-        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) {
-      addIssue(
-        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)) {
-      addIssue(
-        ctx,
-        path,
-        "vector_property_not_numeric_array",
-        `Vector query property '${propertyId}' on '${objectType.id}' must be a numeric array`
-      )
+      "unsupported_vector_composition",
+      "Vector profile input must be a type with optional filters."
+    )
+  const objectType = types[0]!
+  const profile =
+    query.profile === undefined ? undefined : objectType.search?.vectors?.[query.profile]
+  if (!profile) {
+    addIssue(ctx, path, "unknown_vector_profile", `Unknown vector profile: ${query.profile}`)
+    return query
+  }
+  for (const propertyId of profile.source)
+    admitProperty(ctx, { state, propertyId, objectTypeId: objectType.id, use: "vector", path })
+  let values = query.vector
+  try {
+    if (typeof values === "string") {
+      if (!values.trim() || values.length > 8000) {
+        throw new Error("Vector search text must be nonempty and at most 8000 characters.")
+      }
+    } else {
+      values = normalizeVector(values, profile.model.definition.dimensions)
     }
+  } catch (error) {
+    addIssue(ctx, path, "invalid_vector", error instanceof Error ? error.message : "Invalid vector")
+  }
+  return {
+    ...query,
+    vector: values,
+    source: [...profile.source],
+    configuration: vectorConfiguration(profile),
   }
 }
 
@@ -1515,7 +1567,7 @@ function assertStaticSearchProperty(
 function assertQueryFlag(
   objectTypeId: string,
   property: Property,
-  flag: "text" | "vector",
+  flag: "text",
   context: string,
   path: string,
   ctx: QueryValidationContext
@@ -1574,46 +1626,6 @@ function isPrimaryExactPredicate(property: Property, op: ObjectQueryPredicate["o
   return property.primary === true && (op === "eq" || op === "in")
 }
 
-function isTextSchema(schema: Schema): boolean {
-  if (schema === "string") return true
-  return typeof schema !== "string" && schema.type === "enum" && schema.valueType === "string"
-}
-
-function isExactSchema(schema: Schema): boolean {
-  if (typeof schema === "string") return schema !== "fileRef"
-  return schema.type === "enum"
-}
-
-function isSortableSchema(schema: Schema): boolean {
-  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: Schema): boolean {
-  return (
-    schema === "string" ||
-    schema === "uuid" ||
-    (typeof schema !== "string" && (schema.type === "array" || schema.type === "map"))
-  )
-}
-
-function isVectorSchema(schema: Schema, ctx: QueryValidationContext): boolean {
-  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: readonly string[]): string {
   return uniqueStrings(typeIds).sort().join("\0")
 }

package/src/objects/sdk/object-handle.ts

@@ -3,8 +3,9 @@
  * Created via `sixb.objects(MyType).byId("id-1")`, it provides link/unlink and
  * per-property telemetry appenders with compile-time unit and value type safety.
  */
+
 import type { ActionDefinition } from "../../actions"
-import type { ObjectLink, ObjectRef, ValueType } from "../../ontology"
+import type { ObjectLink, ObjectRef } from "../../ontology"
 import { OntologyValidationError } from "../../ontology/errors"
 import type { LinkToken, ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
 import { assertLinkTokenBelongsToObjectType } from "../../ontology/validation"
@@ -16,22 +17,24 @@ import {
 import type { ExecutionObjectContext, ResolvedLinkContext } from "../context"
 import { removeLink as removeLinkLeaf, upsertLink as upsertLinkLeaf } from "../link"
 import { deleteObject, restoreObject } from "../object"
+import { createObjectVectorHandle } from "../vectors/handle"
 import { createTelemetryChannel } from "./telemetry-channel"
 
 type ObjectRefInput = ObjectRef
 type AnyLinkToken = LinkToken<string, string, string | readonly string[], ObjectLink>
 
-export function createObjectByIdHandle<
-  TObjectType extends ObjectTypeWithPropertyTokens,
-  TValueTypes extends readonly ValueType[],
->(ctx: ExecutionObjectContext, primaryId: string): ObjectByIdHandle<TObjectType, TValueTypes> {
+export function createObjectByIdHandle<TObjectType extends ObjectTypeWithPropertyTokens>(
+  ctx: ExecutionObjectContext,
+  primaryId: string
+): ObjectByIdHandle<TObjectType> {
   const objectHandle = {
+    vector: (profileName: string) => createObjectVectorHandle(ctx, primaryId, profileName),
     get: async () => {
       const row = await ctx.objectReader.getByPrimaryId({
         objectTypeId: ctx.objectType.id,
         primaryId,
       })
-      return row ? (row as unknown as TwinObject<TObjectType, TValueTypes>) : null
+      return row ? (row as unknown as TwinObject<TObjectType>) : null
     },
 
     listLinks: async (linkToken?: AnyLinkToken) => {
@@ -126,8 +129,8 @@ export function createObjectByIdHandle<
       })
     },
 
-    telemetry: createTelemetryChannel<TObjectType, TValueTypes>(ctx, primaryId),
+    telemetry: createTelemetryChannel<TObjectType>(ctx, primaryId),
   }
 
-  return objectHandle as unknown as ObjectByIdHandle<TObjectType, TValueTypes>
+  return objectHandle as unknown as ObjectByIdHandle<TObjectType>
 }