@sixb/core 0.1.15 → 0.1.17

package/src/models/reranking-model.ts

@@ -0,0 +1,114 @@
+import type { ModelDefinition } from "./definitions"
+import { ModelProviderError } from "./errors"
+import type { ModelProviderIds, ModelRoute, ModelUsage } from "./events"
+import type { ModelCostEstimator, ModelReportedCost } from "./pricing"
+
+export interface RerankingModelDefinition extends ModelDefinition {
+  readonly kind: "reranking"
+}
+
+/** Serializable identity; the server resolves its own registered binding. */
+export interface RerankingModelRef {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: RerankingModelDefinition
+}
+
+export interface RerankingModelRequest {
+  readonly query: string
+  readonly documents: readonly string[]
+  readonly signal?: AbortSignal
+}
+
+export interface RerankingModelResponseMetadata {
+  readonly usage?: ModelUsage
+  readonly providerIds?: ModelProviderIds
+  readonly responseModelId?: string
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: ModelRoute
+}
+
+export interface RerankingResult {
+  /** Position in the original documents array. */
+  readonly index: number
+  /** Provider relevance score, not a calibrated probability. */
+  readonly score: number
+}
+
+export interface RerankingModelResult extends RerankingModelResponseMetadata {
+  /** One result per input document; Sixb validates completeness and orders by score. */
+  readonly results: readonly RerankingResult[]
+}
+
+export interface RerankingModel extends RerankingModelRef {
+  readonly costEstimator?: ModelCostEstimator
+  resolve?(): Promise<RerankingModel>
+  rerank(request: RerankingModelRequest): Promise<RerankingModelResult>
+}
+
+export function assertRerankingModel(model: RerankingModel): void {
+  if (
+    !model ||
+    typeof model !== "object" ||
+    typeof model.rerank !== "function" ||
+    !validIdentifier(model.providerId) ||
+    !validIdentifier(model.modelId) ||
+    model.definition?.kind !== "reranking" ||
+    model.definition.providerId !== model.providerId ||
+    model.definition.modelId !== model.modelId
+  ) {
+    throw new TypeError("[Sixb] Expected a RerankingModel with a valid identity and rerank method.")
+  }
+}
+
+export function validateRerankingResults(
+  results: unknown,
+  documentCount: number
+): RerankingResult[] {
+  if (!Array.isArray(results) || results.length !== documentCount) {
+    throw new TypeError("[SixbModels] Reranking must return one result per document.")
+  }
+  const seen = new Set<number>()
+  const validated = results.map((result: unknown) => {
+    if (!result || typeof result !== "object") {
+      throw new TypeError("[SixbModels] Invalid reranking result.")
+    }
+    const index: unknown = Reflect.get(result, "index")
+    const score: unknown = Reflect.get(result, "score")
+    if (
+      typeof index !== "number" ||
+      !Number.isSafeInteger(index) ||
+      index < 0 ||
+      index >= documentCount ||
+      seen.has(index) ||
+      typeof score !== "number" ||
+      !Number.isFinite(score)
+    ) {
+      throw new TypeError("[SixbModels] Reranking requires unique valid indices and finite scores.")
+    }
+    seen.add(index)
+    return { index, score }
+  })
+  // Stable ties preserve candidate rank, independent of the provider's response ordering.
+  return validated.sort((left, right) => right.score - left.score || left.index - right.index)
+}
+
+function validIdentifier(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.trim() === value
+}
+
+export class RerankingModelResponseError extends ModelProviderError {
+  constructor(
+    message: string,
+    providerId: string,
+    modelId: string,
+    readonly metadata: RerankingModelResponseMetadata,
+    options?: { cause?: unknown }
+  ) {
+    super(message, providerId, modelId, {
+      code: "invalid_reranking_response",
+      retryable: false,
+      cause: options?.cause,
+    })
+  }
+}

package/src/objects/query/executor.ts

@@ -1,6 +1,6 @@
 import { type AuthorizationContext, assertAuthorized } from "../../authorization"
 import type { RuntimeAuthorization } from "../../execution/types"
-import type { EmbeddingModelCatalog } from "../../models/catalog"
+import type { EmbeddingModelCatalog, RerankingModelCatalog } from "../../models/catalog"
 import type { OntologyRegistry } from "../../ontology"
 import type {
   CountObjectsResult,
@@ -34,6 +34,9 @@ import type {
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
 import { type ObjectQueryPlan, type ObjectQueryPlanningOptions, planObjectQuery } from "./planner"
+import { usePrimaryIdLookups } from "./primary-id"
+import { rerankObjectCandidates } from "./reranking-executor"
+import { findQueryReranking } from "./reranking-query"
 import { compareQueryScalarValues, queryScalarValuesEqual } from "./scalar-values"
 import {
   type ObjectQueryValidationIssue,
@@ -54,6 +57,7 @@ export interface QueryExecutorOptions
   > {
   ontology: OntologyRegistry
   embeddingModels?: EmbeddingModelCatalog
+  rerankingModels?: RerankingModelCatalog
   storage: ObjectReadStorage
   maxLimit?: number
   maxPageSize?: number
@@ -178,6 +182,37 @@ export async function executeObjectQuery(
     throw new ObjectQueryPlanningError(plan.issues)
   }
 
+  if (plan.mode === "pipeline") {
+    const reranking = findQueryReranking(validated.query)
+    if (!reranking || reranking.input.kind !== "vector") {
+      throw new ObjectQueryExecutionError(
+        "invalid_rerank_input",
+        "Reranking requires vector candidates."
+      )
+    }
+    // Resolve the allowlisted server binding before paying for query embedding.
+    const model = options.rerankingModels?.getByRef(reranking.model)?.model
+    if (!model) {
+      throw new ObjectQueryExecutionError(
+        "reranking_model_unavailable",
+        `Reranking model '${reranking.model.provider}/${reranking.model.modelId}' is not configured in models.reranking.`
+      )
+    }
+    const candidates = await executeObjectQuery(
+      { ...input, query: reranking.input, includeTotal: false },
+      options
+    )
+    const result = await rerankObjectCandidates({
+      query: validated.query,
+      vector: reranking.input,
+      candidates: candidates.objects,
+      model,
+      signal: input.signal,
+      includeTotal: input.includeTotal,
+    })
+    return { ...result, plan }
+  }
+
   if (plan.mode === "pushdown") {
     if (!options.storage.queryObjects) {
       throw new ObjectQueryPlanningError(plan.providerIssues)
@@ -386,6 +421,7 @@ export async function facetObjects(
   const maxRows = options.maxFallbackRows ?? DEFAULT_MAX_FALLBACK_ROWS
   const evaluation = await evaluateFallbackQuery(input.projectId, aggregateQuery, options, maxRows)
   return {
+    total: evaluation.entries.length,
     facets: buildFacetResults(
       evaluation.entries.map((entry) => entry.row),
       facets
@@ -432,7 +468,7 @@ function expandPushdownQuery(
   // disagree) cleanly stays on the fallback.
   const ctx: ExpansionResolutionContext = { ontology, maxExpansionFanout }
   const annotated = resolveExpansions(query, ctx)
-  const expanded = expandIncludeSubtypes(annotated, ontology)
+  const expanded = usePrimaryIdLookups(expandIncludeSubtypes(annotated, ontology), ontology)
   if (expanded === annotated) return annotated
 
   const plan = planObjectQuery(expanded, { ...planning, capabilities, allowFallback: false })
@@ -465,6 +501,7 @@ function resolveExpansions(query: ObjectQuery, ctx: ExpansionResolutionContext):
     case "filter":
     case "text":
     case "vector":
+    case "rerank":
     case "traverse":
     case "sort":
     case "limit":
@@ -581,6 +618,7 @@ function expandIncludeSubtypes(query: ObjectQuery, ontology: OntologyRegistry):
     case "filter":
     case "text":
     case "vector":
+    case "rerank":
     case "traverse":
     case "sort":
     case "limit":
@@ -688,6 +726,7 @@ async function evaluateFallbackQuery(
     }
     case "text":
     case "vector":
+    case "rerank":
     case "traverse":
     case "set":
       throw new ObjectQueryExecutionError(
@@ -1186,6 +1225,7 @@ function stripOuterRowShape(query: ObjectQuery): ObjectQuery {
     case "page":
     case "project":
     case "sort":
+    case "rerank":
     // `expand` is output-shaping: it attaches links but does not change which
     // objects match, so aggregates (count/exists/facets) ignore it.
     case "expand":

package/src/objects/query/explain.ts

@@ -145,6 +145,14 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
         },
         children: [buildExplainNode(query.input, `${path}.input`)],
       }
+    case "rerank":
+      return {
+        path,
+        kind: query.kind,
+        summary: `rerank ${query.model.provider}/${query.model.modelId}`,
+        details: { model: query.model },
+        children: [buildExplainNode(query.input, `${path}.input`)],
+      }
     case "set":
       return {
         path,

package/src/objects/query/index.ts

@@ -47,6 +47,7 @@ export type {
   ObjectQueryPredicateNot,
   ObjectQueryProject,
   ObjectQueryRefs,
+  ObjectQueryRerank,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,

package/src/objects/query/ir.ts

@@ -5,6 +5,8 @@
  * storage backend. Providers can push down the subset they support, while the
  * core planner decides whether a bounded fallback is acceptable.
  */
+
+import type { ModelRef } from "../../models/catalog"
 import type { ObjectRef } from "../../ontology/refs"
 
 export type ObjectQueryDirection = "outgoing" | "incoming"
@@ -29,6 +31,7 @@ export type ObjectQuery =
   | ObjectQueryFilter
   | ObjectQueryText
   | ObjectQueryVector
+  | ObjectQueryRerank
   | ObjectQueryTraverse
   | ObjectQuerySet
   | ObjectQuerySort
@@ -102,6 +105,13 @@ export interface ObjectQueryTraverse {
   sourceObjectTypeId?: string
 }
 
+/** Explicit server-side reordering of a bounded vector candidate set. */
+export interface ObjectQueryRerank {
+  kind: "rerank"
+  input: ObjectQuery
+  model: ModelRef
+}
+
 export interface ObjectQuerySet {
   kind: "set"
   op: ObjectQuerySetOperation

package/src/objects/query/normalize.ts

@@ -46,6 +46,8 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
       }
     case "traverse":
       return { ...query, input: normalizeObjectQuery(query.input) }
+    case "rerank":
+      return { ...query, model: { ...query.model }, input: normalizeObjectQuery(query.input) }
     case "set":
       return normalizeSet(query)
     case "sort":

package/src/objects/query/planner.ts

@@ -1,8 +1,9 @@
 import type { ObjectQueryCapabilities, ObjectQueryScalarOperation } from "../../storage"
 import type { ObjectQueryPlanningIssue } from "./errors"
 import type { ObjectExpansion, ObjectQuery, ObjectQueryPredicate, ObjectQuerySortField } from "./ir"
+import { findQueryReranking } from "./reranking-query"
 
-export type ObjectQueryPlanMode = "pushdown" | "fallback" | "rejected"
+export type ObjectQueryPlanMode = "pushdown" | "fallback" | "pipeline" | "rejected"
 export type ObjectQueryProviderOperation =
   | "queryObjects"
   | "countObjects"
@@ -54,6 +55,15 @@ export function planObjectQuery(
   options: ObjectQueryPlanningOptions
 ): ObjectQueryPlan {
   const operation = options.operation ?? "queryObjects"
+  const reranking = findQueryReranking(query)
+  if (reranking) {
+    const candidatePlan = planObjectQuery(reranking.input, options)
+    return {
+      ...candidatePlan,
+      query,
+      mode: candidatePlan.mode === "rejected" ? "rejected" : "pipeline",
+    }
+  }
   // Providers get first refusal. Fallback is considered only after the provider
   // declares that pushdown is unavailable or incomplete for this query.
   const providerIssues = collectProviderIssues(query, options.capabilities, {
@@ -204,6 +214,7 @@ function collectNodeProviderIssues(
       return
     case "text":
     case "vector":
+    case "rerank":
     case "project":
       collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues)
       return

package/src/objects/query/primary-id.ts

@@ -0,0 +1,56 @@
+import type { OntologyDefinitionCatalog } from "../../ontology/registry"
+import type { ObjectQuery, ObjectQueryPredicate } from "./ir"
+
+/** Exact identity predicates can start from primary-key lookups. Keep the original filter:
+ * the optimization must not remove other conditions or expose a projected-out property.
+ * Only a direct start is rewritten; filters after bounds/projections keep their semantics. */
+export function usePrimaryIdLookups(
+  query: ObjectQuery,
+  ontology: OntologyDefinitionCatalog
+): ObjectQuery {
+  if (query.kind === "set")
+    return { ...query, inputs: query.inputs.map((input) => usePrimaryIdLookups(input, ontology)) }
+  if (!("input" in query)) return query
+  const input = usePrimaryIdLookups(query.input, ontology)
+  if (query.kind === "filter" && input.kind === "start" && !input.includeSubtypes) {
+    const propertyId = ontology.getPrimaryPropertyId(input.objectTypeId)
+    const ids = primaryIds(query.predicate, propertyId)
+    if (ids?.length && ids.length <= 1000)
+      return {
+        ...query,
+        input: {
+          kind: "refs",
+          refs: [...new Set(ids)]
+            .sort()
+            .map((primaryId) => ({ objectTypeId: input.objectTypeId, primaryId })),
+        },
+      }
+  }
+  return input === query.input ? query : { ...query, input }
+}
+
+function primaryIds(
+  predicate: ObjectQueryPredicate,
+  propertyId: string
+): readonly string[] | undefined {
+  if (predicate.op === "and") {
+    for (const item of predicate.items) {
+      const ids = primaryIds(item, propertyId)
+      if (ids) return ids
+    }
+    return undefined
+  }
+  if (
+    predicate.op === "eq" &&
+    predicate.propertyId === propertyId &&
+    typeof predicate.value === "string"
+  )
+    return [predicate.value]
+  if (
+    predicate.op === "in" &&
+    predicate.propertyId === propertyId &&
+    predicate.values.every((value) => typeof value === "string")
+  )
+    return predicate.values as readonly string[]
+  return undefined
+}

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

@@ -0,0 +1,91 @@
+import type { RerankingModel } from "../../models/reranking-model"
+import { validateRerankingResults } from "../../models/reranking-model"
+import type { ObjectRow, QueryObjectsResult } from "../../storage"
+import { vectorSources } from "../vectors/profile"
+import { ObjectQueryExecutionError } from "./errors"
+import type { ObjectQuery, ObjectQueryVector } from "./ir"
+import { MAX_RERANK_INPUT_BYTES } from "./reranking-limits"
+
+/** Receives only rows from the authorized reader; never rereads unmasked storage. */
+export async function rerankObjectCandidates(input: {
+  readonly query: ObjectQuery
+  readonly vector: ObjectQueryVector
+  readonly candidates: readonly ObjectRow[]
+  readonly model: RerankingModel
+  readonly signal?: AbortSignal
+  readonly includeTotal?: boolean
+}): Promise<QueryObjectsResult> {
+  const { vector, candidates, model, signal } = input
+  if (typeof vector.vector !== "string" || !vector.source) {
+    throw new ObjectQueryExecutionError(
+      "invalid_rerank_input",
+      "Reranking requires a validated text vector query."
+    )
+  }
+  signal?.throwIfAborted()
+  if (candidates.length > vector.k) {
+    throw new ObjectQueryExecutionError(
+      "rerank_candidate_limit_exceeded",
+      "Storage exceeded the admitted vector candidate bound."
+    )
+  }
+  const source = vector.source
+  const documents = candidates.map((row) => vectorSources(source, row.properties).text)
+  const encoder = new TextEncoder()
+  const bytes =
+    encoder.encode(vector.vector).byteLength +
+    documents.reduce((sum, text) => sum + encoder.encode(text).byteLength, 0)
+  if (bytes > MAX_RERANK_INPUT_BYTES) {
+    throw new ObjectQueryExecutionError(
+      "rerank_input_limit_exceeded",
+      "Reranking input exceeds 1 MiB. Use fewer candidates or shorter profile sources."
+    )
+  }
+
+  const results =
+    documents.length === 0
+      ? []
+      : (await model.rerank({ query: vector.vector, documents, signal })).results
+  signal?.throwIfAborted()
+  const ranking = validateRerankingResults(results, candidates.length)
+  const rows = ranking.map(({ index, score }) => ({ ...candidates[index]!, score }))
+  const shaped = shapeRerankedRows(input.query, rows)
+  return {
+    objects: shaped.rows,
+    hasMore: shaped.hasMore,
+    ...(input.includeTotal === false ? {} : { total: shaped.total }),
+  }
+}
+
+function shapeRerankedRows(
+  query: ObjectQuery,
+  rows: readonly ObjectRow[]
+): { rows: readonly ObjectRow[]; total: number; hasMore: boolean } {
+  if (query.kind === "rerank") return { rows, total: rows.length, hasMore: false }
+  if (query.kind === "limit") {
+    const input = shapeRerankedRows(query.input, rows)
+    return {
+      rows: input.rows.slice(0, query.limit),
+      total: input.total,
+      hasMore: input.hasMore || query.limit < input.rows.length,
+    }
+  }
+  if (query.kind === "project") {
+    const input = shapeRerankedRows(query.input, rows)
+    if (!query.properties) return input
+    const properties = new Set(query.properties)
+    return {
+      ...input,
+      rows: input.rows.map((row) => ({
+        ...row,
+        properties: Object.fromEntries(
+          Object.entries(row.properties).filter(([key]) => properties.has(key))
+        ),
+      })),
+    }
+  }
+  throw new ObjectQueryExecutionError(
+    "invalid_rerank_composition",
+    "Only limit and project may follow reranking."
+  )
+}

package/src/objects/query/reranking-limits.ts

@@ -0,0 +1,3 @@
+// Bound synchronous inference independently of the storage's vector-search capacity.
+export const MAX_RERANK_CANDIDATES = 100
+export const MAX_RERANK_INPUT_BYTES = 1_048_576

package/src/objects/query/reranking-query.ts

@@ -0,0 +1,8 @@
+import type { ObjectQuery, ObjectQueryRerank } from "./ir"
+
+/** Validation permits output shaping only after the explicit reranking stage. */
+export function findQueryReranking(query: ObjectQuery): ObjectQueryRerank | undefined {
+  if (query.kind === "rerank") return query
+  if (query.kind === "limit" || query.kind === "project") return findQueryReranking(query.input)
+  return undefined
+}

package/src/objects/query/validate.ts

@@ -31,6 +31,7 @@ import type {
   QueryScalarKind,
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
+import { MAX_RERANK_CANDIDATES } from "./reranking-limits"
 
 export interface ObjectQueryValidationIssue {
   path: string
@@ -223,7 +224,7 @@ function validateVectorComposition(query: ObjectQuery, ctx: QueryValidationConte
       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.",
+        "Vector profiles support one top-k over one concrete type, with filters, traversals or sets before ranking, optional reranking, then limit/project.",
     })
 }
 
@@ -373,6 +374,37 @@ function dispatchQueryNode(
         ),
       }
     }
+    case "rerank": {
+      const input = validateQueryNode(query.input, `${path}.input`, ctx)
+      if (
+        input.query.kind !== "vector" ||
+        typeof input.query.vector !== "string" ||
+        input.query.k > MAX_RERANK_CANDIDATES
+      ) {
+        addIssue(
+          ctx,
+          path,
+          "invalid_rerank_input",
+          `Reranking requires a text vector query with k at most ${MAX_RERANK_CANDIDATES}, before limit or project.`
+        )
+      }
+      if (
+        typeof query.model?.provider !== "string" ||
+        !query.model.provider.trim() ||
+        query.model.provider.trim() !== query.model.provider ||
+        typeof query.model.modelId !== "string" ||
+        !query.model.modelId.trim() ||
+        query.model.modelId.trim() !== query.model.modelId
+      ) {
+        addIssue(
+          ctx,
+          path,
+          "invalid_rerank_model",
+          "Reranking requires an explicit provider and model ID."
+        )
+      }
+      return { ...input, query: { ...query, model: { ...query.model }, input: input.query } }
+    }
     case "set":
       return validateSet(query.inputs, query.op, path, ctx)
     case "sort": {
@@ -923,15 +955,6 @@ function validateVectorProfileQuery(
     )
     return query
   }
-  let input = query.input
-  while (input.kind === "filter") input = input.input
-  if (input.kind !== "start" || input.includeSubtypes)
-    addIssue(
-      ctx,
-      path,
-      "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]

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

@@ -6,6 +6,8 @@
  * `ObjectQueryExecutor` — the server runtime executor or the HTTP client
  * executor — so the same builder serves both sides.
  */
+
+import type { RerankingModelRef } from "../../models/reranking-model"
 import { OntologyValidationError } from "../../ontology/errors"
 import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
 import { RuntimeError } from "../../runtime/errors"
@@ -16,7 +18,7 @@ import type {
   ObjectExpandOptions,
   ObjectQueryBuilder,
   ObjectQueryFacetInput,
-  ObjectQueryFacetResult,
+  ObjectQueryFacetsResult,
   ObjectQueryListOptions,
   ObjectWhereBuilder,
   ObjectWhereClause,
@@ -118,6 +120,17 @@ class ObjectQueryBuilderImpl<TObjectType extends ObjectTypeWithPropertyTokens> {
     })
   }
 
+  rerank(options: { model: RerankingModelRef }): ObjectQueryBuilder<TObjectType> {
+    if (options.model?.definition?.kind !== "reranking") {
+      throw new TypeError("[Sixb] rerank() requires an explicit reranking model.")
+    }
+    return this.withQuery({
+      kind: "rerank",
+      input: this.ir,
+      model: { provider: options.model.providerId, modelId: options.model.modelId },
+    })
+  }
+
   traverse(
     link: LinkToken<TObjectType["id"], string, string>,
     options?: { direction?: "outgoing" }
@@ -269,7 +282,7 @@ class ObjectQueryBuilderImpl<TObjectType extends ObjectTypeWithPropertyTokens> {
 
   async facets(
     input: readonly ObjectQueryFacetInput<TObjectType>[]
-  ): Promise<ObjectQueryFacetResult[]> {
+  ): Promise<ObjectQueryFacetsResult> {
     return this.params.executor.facets(
       this.ir,
       input.map((facet) => ({

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

@@ -5,7 +5,7 @@
  * 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 { ObjectQueryFacetsResult } from "../../runtime/types"
 import type { ObjectQueryExplanation } from "../query/explain"
 import type { ObjectQuery } from "../query/ir"
 import type { ValidatedObjectQuery } from "../query/validate"
@@ -55,7 +55,7 @@ export interface ObjectQueryExecutor {
   facets(
     query: ObjectQuery,
     facets: readonly ObjectQueryExecutorFacetRequest[]
-  ): Promise<ObjectQueryFacetResult[]>
+  ): Promise<ObjectQueryFacetsResult>
   /** Validation requires ontology access and is unavailable on remote executors. */
   validate?(query: ObjectQuery): ValidatedObjectQuery
   /** Explanation requires ontology access and is unavailable on remote executors. */

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

@@ -46,10 +46,13 @@ export function createRuntimeQueryExecutor(params: {
 
     async facets(query: ObjectQuery, facets: readonly ObjectQueryExecutorFacetRequest[]) {
       const result = await objectReader.facet({ query, facets })
-      return result.facets.map((facet) => ({
-        propertyId: facet.propertyId,
-        buckets: [...facet.buckets],
-      }))
+      return {
+        total: result.total,
+        facets: result.facets.map((facet) => ({
+          propertyId: facet.propertyId,
+          buckets: [...facet.buckets],
+        })),
+      }
     },
 
     validate(query: ObjectQuery) {

package/src/objects/vectors/README.md

@@ -2,9 +2,18 @@
 
 A named profile identifies a derived representation, separate from object properties.
 
+Indexing sends embedding purpose `document`; search sends `query`. The execution wrapper preserves
+that role through model resolution, admission and accounting. Symmetric providers may ignore it.
+
+Vector candidates may come from filters, traversals, explicit refs or set operations. Canonical
+validation requires one concrete result type and admits every intermediate type, edge and source
+property. Model lookup uses that resolved result type, not the query's initial type. SQL ranks the
+eligible set after link and property authorization; it never filters a global top-k afterward.
+
 ```text
 Effective object change → invalidate stale vector + persist latest intent (one transaction)
-ProjectionWorker → durable queue → project AI admission → provider → save result → fenced commit
+Commit wake-up (or API maintenance pass) → durable queue
+ProjectionWorker → project AI admission → provider → save result → fenced commit
 ```
 
 `materializer/effective/vector-indexing.ts` compares effective source fingerprints after projection
@@ -14,7 +23,10 @@ There is no historical scan or configuration-only backfill.
 
 The queue owns delivery leases. Ontology storage owns intent keyed by project/object/profile, plus
 its generation id and `pending → running → ready` state. Dispatch has a separate due time so long
-queues cannot starve later entries. Reconciliation can enqueue the same generation safely.
+queues cannot starve later entries. `indexing-dispatch.ts` enqueues due intent after every commit
+in the committing process and pushes its due time 30 seconds out; the API's maintenance pass
+drains the same path, so intent a crash left undispatched waits at most one pass. Enqueueing the
+same generation twice is safe.
 
 `indexing.ts` exposes only a core-owned processing capability. Kernel authority cannot bind the
 public domain SDK. `ontology.indexVectors` authorizes only the persisted results of its work item or durable group.