@sixb/core 0.1.11 → 0.1.13

package/src/objects/vectors/profile.ts

@@ -0,0 +1,64 @@
+import { MaterializationValidationError } from "../../materialization/errors"
+import { sha256Canonical } from "../../materialization/identity"
+import type { ObjectVectorSearchProfile } from "../../ontology/types"
+
+export const MAX_VECTOR_K = 1000
+export const VECTOR_INPUT_VERSION = 1
+
+export function vectorConfiguration(profile: ObjectVectorSearchProfile): string {
+  return sha256Canonical({
+    format: VECTOR_INPUT_VERSION,
+    sources: [...profile.source],
+    provider: profile.model.providerId,
+    model: profile.model.modelId,
+    representation: profile.model.definition.representation ?? { name: profile.model.modelId },
+    dimensions: profile.model.definition.dimensions,
+    metric: "cosine",
+    precision: "float32",
+    normalization: "l2-v1",
+  })
+}
+
+export function vectorSources(
+  source: readonly string[],
+  properties: Readonly<Record<string, unknown>>
+) {
+  const values: Record<string, string | null> = Object.create(null)
+  for (const key of source) {
+    const value = properties[key]
+    if (value !== undefined && value !== null && typeof value !== "string") {
+      throw new MaterializationValidationError(`Vector source must be text: ${key}`)
+    }
+    values[key] = typeof value === "string" ? value : null
+  }
+  // Ordered JSON pairs preserve field boundaries, escaping and absent/empty distinction.
+  const text = JSON.stringify(source.map((key) => [key, values[key]]))
+  return { text, sourceFingerprint: sha256Canonical(text) }
+}
+
+/** Unit-length float32 representation keeps native cosine arithmetic within range. */
+export function normalizeVector(values: readonly number[], dimensions: number): readonly number[] {
+  if (!Array.isArray(values) || values.length !== dimensions) {
+    throw new MaterializationValidationError(`Vector dimension mismatch; expected ${dimensions}`)
+  }
+  const normalized = Array.from(values, (value) => {
+    if (
+      typeof value !== "number" ||
+      !Number.isFinite(value) ||
+      !Number.isFinite(Math.fround(value))
+    ) {
+      throw new MaterializationValidationError("Vector values must be finite float32 numbers.")
+    }
+    return Math.fround(value)
+  })
+  if (!normalized.some((value) => value !== 0)) {
+    throw new MaterializationValidationError("Cosine search requires a nonzero vector.")
+  }
+  const norm = Math.hypot(...normalized)
+  return Object.freeze(normalized.map((value) => Math.fround(value / norm)))
+}
+
+/** V1 envelope for exact SQL scoring; exceeding it must fail rather than truncate candidates. */
+export function vectorSearchCandidateLimit(dimensions: number): number {
+  return Math.min(10000, Math.floor(16000000 / dimensions))
+}

package/src/objects/vectors/query.ts

@@ -0,0 +1,16 @@
+import type { ObjectQuery } from "../query/ir"
+
+export function hasVectorProfile(query: ObjectQuery): boolean {
+  if (query.kind === "vector") return true
+  if (query.kind === "set") return query.inputs.some(hasVectorProfile)
+  return "input" in query && hasVectorProfile(query.input)
+}
+
+/** V1 supports one exact top-k, with filters applied before ranking. */
+export function isVectorProfileQuery(query: ObjectQuery): boolean {
+  if (query.kind === "limit" || query.kind === "project") return isVectorProfileQuery(query.input)
+  if (query.kind !== "vector" || !query.profile) return false
+  let input = query.input
+  while (input.kind === "filter") input = input.input
+  return input.kind === "start" && !input.includeSubtypes
+}

package/src/objects/vectors/resolve-query.ts

@@ -0,0 +1,89 @@
+import type { EmbeddingModelCatalog } from "../../models/catalog"
+import { type EmbeddingModel, sameEmbeddingModel } from "../../models/embedding-model"
+import type { OntologyRegistry } from "../../ontology"
+import { ObjectQueryExecutionError } from "../query/errors"
+import type { ObjectQuery, ObjectQueryVector } from "../query/ir"
+import { normalizeVector } from "./profile"
+
+const QUERY_EMBEDDING_TIMEOUT_MS = 30_000
+
+/** Called only after query validation, authorization and provider planning have succeeded. */
+export async function resolveVectorSearchText(
+  query: ObjectQuery,
+  ontology: OntologyRegistry,
+  models: EmbeddingModelCatalog | undefined,
+  signal?: AbortSignal
+): Promise<ObjectQuery> {
+  if (query.kind === "limit" || query.kind === "project") {
+    const input = await resolveVectorSearchText(query.input, ontology, models, signal)
+    return { ...query, input }
+  }
+  if (query.kind !== "vector" || typeof query.vector !== "string") return query
+
+  const model = resolveProfileEmbeddingModel(query, ontology, models)
+  const vector = await embedSearchText(query.vector, model, signal)
+  return { ...query, vector }
+}
+
+function resolveProfileEmbeddingModel(
+  query: ObjectQueryVector,
+  ontology: OntologyRegistry,
+  models: EmbeddingModelCatalog | undefined
+): EmbeddingModel {
+  let input = query.input
+  while (input.kind === "filter") input = input.input
+  if (input.kind !== "start" || !query.profile) {
+    throw new ObjectQueryExecutionError(
+      "embedding_model_unavailable",
+      "Vector search requires the embedding model registered for its profile."
+    )
+  }
+
+  const profile = ontology.resolveObjectType(input.objectTypeId).search?.vectors?.[query.profile]
+  if (!profile) {
+    throw new ObjectQueryExecutionError(
+      "embedding_model_unavailable",
+      "Vector search requires the embedding model registered for its profile."
+    )
+  }
+
+  const model = models?.getByRef({
+    provider: profile.model.providerId,
+    modelId: profile.model.modelId,
+  })?.model
+  if (!model || !sameEmbeddingModel(model, profile.model)) {
+    throw new ObjectQueryExecutionError(
+      "embedding_model_unavailable",
+      "Vector search requires the embedding model registered for its profile."
+    )
+  }
+  return model
+}
+
+async function embedSearchText(
+  text: string,
+  model: EmbeddingModel,
+  signal?: AbortSignal
+): Promise<readonly number[]> {
+  const dimensions = model.definition.dimensions
+  const timeout = AbortSignal.timeout(QUERY_EMBEDDING_TIMEOUT_MS)
+  const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout
+  requestSignal.throwIfAborted()
+  const result = await model.embed({ texts: [text], signal: requestSignal })
+  requestSignal.throwIfAborted()
+
+  if (!Array.isArray(result?.vectors) || result.vectors.length !== 1) {
+    throw new ObjectQueryExecutionError(
+      "invalid_embedding_response",
+      "Embedding model must return exactly one vector for the search text."
+    )
+  }
+  try {
+    return normalizeVector(result.vectors[0]!, dimensions)
+  } catch {
+    throw new ObjectQueryExecutionError(
+      "invalid_embedding_response",
+      "Embedding model returned an invalid vector for the search profile."
+    )
+  }
+}

package/src/objects/vectors/types.ts

@@ -0,0 +1,10 @@
+import type { ObjectType } from "../../ontology"
+
+export type VectorProfileName<T extends ObjectType> = T extends { search: { vectors: infer P } }
+  ? Extract<keyof P, string>
+  : never
+
+export interface ObjectVectorHandle {
+  /** Generate and atomically store this profile using its configured model. Conflicts are not retried. */
+  index(): Promise<void>
+}

package/src/ontology/builders.ts

@@ -26,7 +26,7 @@
  * ```
  */
 
-import type { ObjectTypeWithPropertyTokens, ObjectTypeWithTokens, PropertyTokenMap } from "./tokens"
+import type { ObjectTypeWithPropertyTokens, ObjectTypeWithTokens } from "./tokens"
 import { createLinkTokenMap, createPropertyTokenMap } from "./tokens"
 import type {
   EnumSchema,
@@ -450,18 +450,12 @@ export type DirectLinkTarget<
   TId extends string,
   TName extends string,
   TProperties extends Property[],
-> = {
+> = ObjectTypeWithPropertyTokens<{
   id: TId
   name: TName
   properties: TProperties
   links: ObjectLink[]
-  readonly p: PropertyTokenMap<{
-    id: TId
-    name: TName
-    properties: TProperties
-    links: ObjectLink[]
-  }>
-}
+}>
 
 type DirectLinkTargetFor<TTarget extends ObjectType> = TTarget extends ObjectTypeWithPropertyTokens
   ? DirectLinkTarget<TTarget["id"], TTarget["name"], TTarget["properties"]>
@@ -635,10 +629,17 @@ export const link: LinkBuilder = Object.assign(linkImpl, {
 export function valueTypeRef<const TId extends string>(
   valueTypeId: TId
 ): ValueTypeRefSchema & { valueTypeId: TId }
-// 2. ValueType object (concise, self-contained)
+// 2. ValueType object (concise, self-contained: carries the schema and the semantic type)
 export function valueTypeRef<const TVT extends ValueType>(
   valueType: TVT
-): { type: "valueTypeRef"; valueTypeId: TVT["id"]; _resolved: TVT["schema"] }
+): TVT extends { semanticType: infer TSemanticType extends QuantitativeTypeId }
+  ? {
+      type: "valueTypeRef"
+      valueTypeId: TVT["id"]
+      _resolved: TVT["schema"]
+      _semanticType: TSemanticType
+    }
+  : { type: "valueTypeRef"; valueTypeId: TVT["id"]; _resolved: TVT["schema"] }
 // 3. String id + explicit schema (escape hatch)
 export function valueTypeRef<const TId extends string, const TResolved extends Schema>(
   valueTypeId: TId,
@@ -659,6 +660,9 @@ export function valueTypeRef(
     type: "valueTypeRef",
     valueTypeId: idOrValueType.id,
     _resolved: idOrValueType.schema,
+    ...(idOrValueType.semanticType === undefined
+      ? {}
+      : { _semanticType: idOrValueType.semanticType }),
   }
 }
 

package/src/ontology/index.ts

@@ -10,6 +10,7 @@
 
 // ── Types ───────────────────────────────────────────────────
 
+export type { EmbeddingModelDefinition, EmbeddingModelRef } from "../models/embedding-model"
 export type { DecimalValue } from "./decimal"
 export {
   compareDecimalValues,
@@ -29,6 +30,7 @@ export { isObjectRefSchema, objectRef, ref } from "./refs"
 export type {
   LinkToken,
   LinkTokenMap,
+  ObjectPropertiesMetadata,
   ObjectTypeWithPropertyTokens,
   ObjectTypeWithTokens,
   PropertyToken,
@@ -48,6 +50,7 @@ export type {
   ObjectSchema,
   ObjectType,
   ObjectTypeSearchMetadata,
+  ObjectVectorSearchProfile,
   Ontology,
   PrimitiveSchema,
   Property,
@@ -55,9 +58,12 @@ export type {
   PropertyQueryMetadata,
   Schema,
   SixbObjectTypeMap,
+  SixbValueTypeMap,
   ValueType,
   ValueTypeRefSchema,
 } from "./types"
+export type { UserRef } from "./user-ref"
+export { userRef } from "./user-ref"
 
 // ── Registry ──────────────────────────────────────────────
 

package/src/ontology/inference/index.ts

@@ -13,13 +13,16 @@ import type {
   ValueTypeRefSchema,
 } from ".."
 import type { DecimalValue } from "../decimal"
+import type { RegisteredValueTypes } from "../registered"
 import type { QuantitativeTypeId, UnitsOf } from "../units"
+import type { UserRef } from "../user-ref"
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
 
 /**
  * Look up a referenced value type by `id` from the value-type tuple passed
- * into the inference utilities.
+ * into the inference utilities — the generated registry unless a caller passes
+ * its own tuple.
  */
 type ResolveValueType<
   TValueTypes extends readonly ValueType[],
@@ -30,13 +33,17 @@ type ResolveValueType<
  * Resolve `{ type: "valueTypeRef" }` recursively.
  *
  * Unknown references intentionally degrade to `unknown` so type-level callsites
- * can decide how strict they want to be.
+ * can decide how strict they want to be. The `[never]` guard is what keeps that
+ * promise: an unresolved lookup is `never`, and a distributive check over `never`
+ * would yield `never` — a value assignable to everything.
  */
 type InferValueTypeRef<TValueTypeId extends string, TValueTypes extends readonly ValueType[]> =
   ResolveValueType<TValueTypes, TValueTypeId> extends infer TValueType
-    ? TValueType extends ValueType
-      ? InferSchema<TValueType["schema"], TValueTypes>
-      : unknown
+    ? [TValueType] extends [never]
+      ? unknown
+      : TValueType extends ValueType
+        ? InferSchema<TValueType["schema"], TValueTypes>
+        : unknown
     : unknown
 
 type RequiredFieldIds<TFields extends Record<string, ObjectFieldSchema>> = {
@@ -68,6 +75,7 @@ type InferObjectFields<
 
 interface PrimitiveSchemaValueMap {
   fileRef: FileRef
+  userRef: UserRef
   string: string
   uuid: string
   boolean: boolean
@@ -102,26 +110,37 @@ type InferValueTypeRefSchema<
  * Convert ontology schema definitions into runtime value types.
  *
  * This is the core typing bridge used by the future object SDK APIs.
+ *
+ * A schema typed as the whole `Schema` union (a helper returning `Schema`, say) infers `unknown`:
+ * its array, map and object children are `Schema` again, so inferring it never terminates.
  */
 export type InferSchema<
   TSchema extends Schema,
-  TValueTypes extends readonly ValueType[] = [],
-> = TSchema extends PrimitiveSchema
-  ? PrimitiveSchemaValueMap[TSchema]
-  : TSchema extends ComplexSchema
-    ? InferComplexSchema<TSchema, TValueTypes>
-    : TSchema extends ValueTypeRefSchema
-      ? InferValueTypeRefSchema<TSchema, TValueTypes>
-      : never
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = Schema extends TSchema
+  ? unknown
+  : TSchema extends PrimitiveSchema
+    ? PrimitiveSchemaValueMap[TSchema]
+    : TSchema extends ComplexSchema
+      ? InferComplexSchema<TSchema, TValueTypes>
+      : TSchema extends ValueTypeRefSchema
+        ? InferValueTypeRefSchema<TSchema, TValueTypes>
+        : never
 
 /** Property-level value inference with nullable support. */
 export type InferPropertyValue<
   TProperty extends Pick<Property, "schema" | "nullable">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = TProperty["nullable"] extends true
   ? InferSchema<TProperty["schema"], TValueTypes> | null
   : InferSchema<TProperty["schema"], TValueTypes>
 
+/**
+ * A registered value type wins over the semantic type carried on the ref, as it does at runtime:
+ * the registry keeps an explicit value type and only auto-registers the ref's copy when none
+ * exists. `valueTypeRef(VT)` carries `_semanticType` so a value type that is not registered
+ * (defined outside `ontology/`) still constrains units.
+ */
 type InferPropertySemanticTypeFromValueTypeRef<
   TProperty extends Pick<Property, "schema">,
   TValueTypes extends readonly ValueType[],
@@ -129,16 +148,20 @@ type InferPropertySemanticTypeFromValueTypeRef<
   type: "valueTypeRef"
   valueTypeId: infer TValueTypeId extends string
 }
-  ? ResolveValueType<TValueTypes, TValueTypeId> extends {
-      semanticType: infer TSemanticType extends QuantitativeTypeId
-    }
-    ? TSemanticType
-    : never
+  ? [ResolveValueType<TValueTypes, TValueTypeId>] extends [never]
+    ? TProperty["schema"] extends { _semanticType: infer TSemanticType extends QuantitativeTypeId }
+      ? TSemanticType
+      : never
+    : ResolveValueType<TValueTypes, TValueTypeId> extends {
+          semanticType: infer TSemanticType extends QuantitativeTypeId
+        }
+      ? TSemanticType
+      : never
   : never
 
 export type InferPropertySemanticType<
   TProperty extends Pick<Property, "schema" | "semanticType">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = TProperty["semanticType"] extends QuantitativeTypeId
   ? TProperty["semanticType"]
   : InferPropertySemanticTypeFromValueTypeRef<TProperty, TValueTypes>
@@ -152,7 +175,7 @@ export type InferPropertySemanticType<
  */
 export type InferPropertyUnit<
   TProperty extends Pick<Property, "schema" | "semanticType">,
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > =
   InferPropertySemanticType<TProperty, TValueTypes> extends infer TSemanticType extends
     QuantitativeTypeId
@@ -163,7 +186,7 @@ export type InferPropertyUnit<
 
 export type InferObjectProperties<
   TObjectType extends { properties: readonly Property[] },
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > =
   // Object types whose property ids are not statically known (the broad
   // `ObjectTypeWithPropertyTokens` base, e.g. as a generic constraint or
@@ -197,22 +220,19 @@ export type InferTelemetryPropertyIds<TObjectType extends { properties: readonly
  *
  * Iterates over the extracted telemetry property union directly (via `as P["id"]` remapping)
  * so that `P` is already resolved — avoids repeated indexed access through the token map
- * which would cause TS2589 on object types with many telemetry properties.
+ * which would cause TS2589 on object types with many telemetry properties. The semantic type is
+ * resolved as for a single append, so a batch requires exactly the units `telemetry()` does.
  */
 export type InferTelemetryBatchProperties<
   TObjectType extends { properties: readonly Property[] },
-  TValueTypes extends readonly ValueType[] = [],
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
 > = {
-  [P in Extract<
-    TObjectType["properties"][number],
-    { mode: "telemetry" }
-  > as P["id"]]?: P["semanticType"] extends QuantitativeTypeId
-    ? { value: InferPropertyValue<P, TValueTypes>; unit: UnitsOf<P["semanticType"]> }
-    : P["schema"] extends { type: "valueTypeRef"; valueTypeId: infer TVtId extends string }
-      ? ResolveValueType<TValueTypes, TVtId> extends {
-          semanticType: infer TSem extends QuantitativeTypeId
-        }
-        ? { value: InferPropertyValue<P, TValueTypes>; unit: UnitsOf<TSem> }
-        : InferPropertyValue<P, TValueTypes>
-      : InferPropertyValue<P, TValueTypes>
+  [P in Extract<TObjectType["properties"][number], { mode: "telemetry" }> as P["id"]]?: [
+    InferPropertySemanticType<P, TValueTypes>,
+  ] extends [never]
+    ? InferPropertyValue<P, TValueTypes>
+    : {
+        value: InferPropertyValue<P, TValueTypes>
+        unit: UnitsOf<InferPropertySemanticType<P, TValueTypes>>
+      }
 }

package/src/ontology/internal.ts

@@ -1,4 +1,5 @@
 export { schemaFieldsToJsonSchema, schemaRecordToJsonSchema } from "./json-schema"
+export { resolvePropertyQueryCapabilities } from "./query-capabilities"
 export { validateSchemaOrRefValue } from "./refs"
 export { createLinkTokenMap, createPropertyTokenMap } from "./tokens"
 export {

package/src/ontology/json-schema.ts

@@ -101,6 +101,18 @@ function schemaJsonSchema(
           required: ["blobId", "digest", "sizeBytes"],
           additionalProperties: false,
         }
+      case "userRef":
+        return {
+          type: "object",
+          properties: {
+            type: { type: "string", enum: ["user"] },
+            id: { type: "string", minLength: 1 },
+          },
+          required: ["type", "id"],
+          additionalProperties: false,
+        }
+      default:
+        schema satisfies never
     }
   }
 

package/src/ontology/primitives.ts

@@ -0,0 +1,91 @@
+import type { QueryScalarKind } from "../objects/query/ir"
+import type { PrimitiveSchema } from "./types"
+
+/**
+ * Yes/no decisions a primitive schema makes for rules that several modules share.
+ *
+ * Every primitive states every decision: adding one to `PrimitiveSchema` fails to compile until it
+ * has a row here, instead of inheriting string-like behavior from a denylist. Per-type behavior
+ * (value validation, normalization, JSON Schema, inference) stays in exhaustive switches next to
+ * the code that performs it.
+ */
+export interface PrimitiveTraits {
+  /** Scalar kind object queries compare values with; `undefined` when values are not comparable. */
+  readonly queryScalarKind: QueryScalarKind | undefined
+  /** Exact matching: `eq`/`neq`/`in`/`exists` predicates and `query.filterable`. */
+  readonly exact: boolean
+  /** Exact-match search profile: `query.exact` and `search.exact`, matched against search input. */
+  readonly exactSearch: boolean
+  /** Ordering: range predicates and `query.sortable`. */
+  readonly sortable: boolean
+  /** Keyword search: `query.text`, search titles, and vector sources. */
+  readonly text: boolean
+  /** Substring `contains` predicates. */
+  readonly contains: boolean
+  /** Facet buckets: `query.facet`. */
+  readonly facet: boolean
+  /** Allowed anywhere inside a telemetry property's schema. */
+  readonly telemetry: boolean
+  /** Allowed anywhere inside a shared Action parameter's schema. */
+  readonly shareableParam: boolean
+}
+
+const comparable = {
+  exact: true,
+  exactSearch: true,
+  sortable: true,
+  text: false,
+  contains: false,
+  facet: true,
+  telemetry: true,
+  shareableParam: true,
+} as const
+
+const PRIMITIVE_TRAITS = {
+  string: { ...comparable, queryScalarKind: "string", text: true, contains: true },
+  uuid: { ...comparable, queryScalarKind: "uuid", contains: true },
+  integer: { ...comparable, queryScalarKind: "integer" },
+  double: { ...comparable, queryScalarKind: "double" },
+  decimal: { ...comparable, queryScalarKind: "decimal" },
+  date: { ...comparable, queryScalarKind: "date" },
+  timestamp: { ...comparable, queryScalarKind: "timestamp" },
+  boolean: { ...comparable, queryScalarKind: "boolean", sortable: false },
+  // Blob references are resolved through the object that holds them, never compared.
+  fileRef: {
+    queryScalarKind: undefined,
+    exact: false,
+    exactSearch: false,
+    sortable: false,
+    text: false,
+    contains: false,
+    facet: false,
+    telemetry: false,
+    shareableParam: false,
+  },
+  // User references match by identity, never against typed search input. They are not text, carry
+  // no order, and stay out of telemetry and shared sessions, which cannot disclose who they point to.
+  userRef: {
+    queryScalarKind: "userRef",
+    exact: true,
+    exactSearch: false,
+    sortable: false,
+    text: false,
+    contains: false,
+    facet: true,
+    telemetry: false,
+    shareableParam: false,
+  },
+} as const satisfies Record<PrimitiveSchema, PrimitiveTraits>
+
+export function isPrimitiveSchema(schema: unknown): schema is PrimitiveSchema {
+  return typeof schema === "string" && Object.hasOwn(PRIMITIVE_TRAITS, schema)
+}
+
+/**
+ * Traits for a primitive schema. Property schemas are not shape-validated at registration, so an
+ * untyped definition can still carry a string outside `PrimitiveSchema`: it gets `undefined`, and
+ * callers treat it as supporting no query feature.
+ */
+export function primitiveTraits(schema: PrimitiveSchema): PrimitiveTraits | undefined {
+  return isPrimitiveSchema(schema) ? PRIMITIVE_TRAITS[schema] : undefined
+}