@sixb/core 0.1.16 → 0.1.18

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
@@ -41,7 +42,10 @@ export interface ObjectQueryValidationIssue {
 export interface ValidatedObjectQuery {
   query: ObjectQuery
   result: ObjectQueryResultShape
-  /** Every object type the query touches, including intermediate traversal types. */
+  /**
+   * Every object type the query touches, including intermediate traversal types and the subtypes
+   * an outgoing link can reach.
+   */
   touchedObjectTypeIds: readonly string[]
 }
 
@@ -158,6 +162,67 @@ const NOOP_QUERY_ADMISSION: ObjectQuerySemanticAdmission = Object.freeze({
     input.states[0] ?? NOOP_ADMISSION_STATE,
 })
 
+/**
+ * Admit a query only when both admissions admit it, each reducing its own state.
+ *
+ * The first denial wins, in order, so composing keeps each admission's messages unchanged.
+ */
+export function composeObjectQueryAdmissions(
+  first: ObjectQuerySemanticAdmission,
+  second: ObjectQuerySemanticAdmission
+): ObjectQuerySemanticAdmission {
+  const parts = new WeakMap<
+    ObjectQueryAdmissionState,
+    readonly [ObjectQueryAdmissionState, ObjectQueryAdmissionState]
+  >()
+  const join = (
+    left: ObjectQueryAdmissionState,
+    right: ObjectQueryAdmissionState
+  ): ObjectQueryAdmissionState => {
+    const state = Object.freeze({})
+    parts.set(state, [left, right])
+    return state
+  }
+  const split = (state: ObjectQueryAdmissionState) => {
+    const pair = parts.get(state)
+    if (!pair) throw new Error("[Sixb] Composed query admission received a foreign state.")
+    return pair
+  }
+  const transition = (
+    left: ObjectQueryAdmissionTransition,
+    right: ObjectQueryAdmissionTransition
+  ): ObjectQueryAdmissionTransition => {
+    const denial = left.denial ?? right.denial
+    return { state: join(left.state, right.state), ...(denial ? { denial } : {}) }
+  }
+
+  const admission: ObjectQuerySemanticAdmission = {
+    empty: () => join(first.empty(), second.empty()),
+    source: (input) => transition(first.source(input), second.source(input)),
+    edge: (input) => {
+      const [left, right] = split(input.state)
+      return transition(
+        first.edge({ ...input, state: left }),
+        second.edge({ ...input, state: right })
+      )
+    },
+    property: (input) => {
+      const [left, right] = split(input.state)
+      return (
+        first.property({ ...input, state: left }) ?? second.property({ ...input, state: right })
+      )
+    },
+    set: (input) => {
+      const pairs = input.states.map(split)
+      return join(
+        first.set({ ...input, states: pairs.map(([left]) => left) }),
+        second.set({ ...input, states: pairs.map(([, right]) => right) })
+      )
+    },
+  }
+  return Object.freeze(admission)
+}
+
 export function validateObjectQuery(
   query: ObjectQuery,
   options: ObjectQueryValidationOptions
@@ -223,7 +288,7 @@ function validateVectorComposition(query: ObjectQuery, ctx: QueryValidationConte
       path: "$",
       code: "vector.composition",
       message:
-        "Vector profiles support one top-k over one concrete type, with filters, traversals or sets 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 +438,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": {
@@ -498,9 +594,7 @@ function validateStart(
     return { result: { objectTypeIds: [] }, query: { kind: "start", objectTypeId } }
   }
 
-  const objectTypeIds = includeSubtypes
-    ? uniqueStrings([objectTypeId, ...ctx.ontology.listSubTypes(objectTypeId)])
-    : [objectTypeId]
+  const objectTypeIds = includeSubtypes ? withSubtypes([objectTypeId], ctx) : [objectTypeId]
 
   return { result: { objectTypeIds }, query: { kind: "start", objectTypeId, includeSubtypes } }
 }
@@ -863,16 +957,15 @@ function validateTextQuery(
       continue
     }
 
-    if (fieldsByObjectType) fieldsByObjectType[objectType.id] = uniqueStrings(fieldIds)
+    const admitted = admitTextFields(fieldIds, fields === undefined, {
+      state: admissionState,
+      objectTypeId: objectType.id,
+      path: `${path}.fields`,
+      ctx,
+    })
+    if (fieldsByObjectType) fieldsByObjectType[objectType.id] = uniqueStrings(admitted)
 
     for (const fieldId of fieldIds) {
-      admitProperty(ctx, {
-        state: admissionState,
-        propertyId: fieldId,
-        objectTypeId: objectType.id,
-        use: "text",
-        path: `${path}.fields`,
-      })
       const property = getProperty(objectType, fieldId)
       if (!property) {
         addIssue(
@@ -901,6 +994,43 @@ function validateTextQuery(
   return fieldsByObjectType ? { fieldsByObjectType } : {}
 }
 
+/**
+ * Admit the fields a text query searches. Every explicit field must be admitted. Default fields
+ * come from the type's search profile, so a reader that cannot use one searches the others
+ * instead; only a type left with no usable default field is denied.
+ */
+function admitTextFields(
+  fieldIds: readonly string[],
+  defaults: boolean,
+  input: {
+    readonly state: ObjectQueryAdmissionState
+    readonly objectTypeId: string
+    readonly path: string
+    readonly ctx: QueryValidationContext
+  }
+): readonly string[] {
+  const admitted: string[] = []
+  let firstDenial: Error | undefined
+  for (const fieldId of fieldIds) {
+    const denial = input.ctx.admission.property({
+      state: input.state,
+      propertyId: fieldId,
+      objectTypeId: input.objectTypeId,
+      use: "text",
+      path: input.path,
+    })
+    if (!denial) {
+      admitted.push(fieldId)
+    } else if (!defaults) {
+      recordAdmissionDenial(input.ctx, denial)
+    } else {
+      firstDenial ??= denial
+    }
+  }
+  if (admitted.length === 0 && firstDenial) recordAdmissionDenial(input.ctx, firstDenial)
+  return admitted
+}
+
 function validateVectorProfileQuery(
   query: ObjectQueryVector,
   shape: ObjectQueryResultShape,
@@ -1028,7 +1158,9 @@ function validateOutgoingTraverse(
     }
   }
 
-  return { objectTypeIds: uniqueStrings(targetTypeIds) }
+  const objectTypeIds = uniqueStrings(targetTypeIds)
+  touchLinkTargets(objectTypeIds, ctx)
+  return { objectTypeIds }
 }
 
 function validateIncomingTraverse(
@@ -1229,7 +1361,22 @@ function resolveOutgoingExpansionTargets(
     )
   }
 
-  return { objectTypeIds: uniqueStrings(targetTypeIds) }
+  const objectTypeIds = uniqueStrings(targetTypeIds)
+  touchLinkTargets(objectTypeIds, ctx)
+  return { objectTypeIds }
+}
+
+/**
+ * Following a link outgoing reads every subtype of its declared targets: links accept subtype
+ * targets and storage follows them by link id alone. Authorize those reads like a `start` that
+ * includes subtypes; the result shape keeps the declared targets that later nodes validate against.
+ * Incoming edges already name every source type they can return: storage matches a pinned
+ * `sourceObjectTypeId` exactly, and otherwise subtypes inherit the link.
+ */
+function touchLinkTargets(objectTypeIds: readonly string[], ctx: QueryValidationContext): void {
+  for (const objectTypeId of withSubtypes(objectTypeIds, ctx)) {
+    ctx.touchedObjectTypeIds.add(objectTypeId)
+  }
 }
 
 function resolveIncomingExpansionTargets(
@@ -1625,6 +1772,10 @@ function uniqueStrings(values: readonly string[]): string[] {
   return [...new Set(values)]
 }
 
+function withSubtypes(objectTypeIds: readonly string[], ctx: QueryValidationContext): string[] {
+  return uniqueStrings(objectTypeIds.flatMap((id) => [id, ...ctx.ontology.listSubTypes(id)]))
+}
+
 function admitTransition(
   ctx: QueryValidationContext,
   transition: ObjectQueryAdmissionTransition

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

@@ -0,0 +1,77 @@
+/**
+ * File handle factory for ObjectReadByIdHandle.
+ *
+ * Opens a `fileRef` property through the object that holds it, the way the object file content
+ * route does: the object is read again with the caller's permissions, the FileRef is resolved in
+ * that authorized row, then checked against the stored blob before it is opened.
+ */
+import { AuthorizationError } from "../../authorization/errors"
+import { jsonPointerSegment, openFileRef, resolveFileRefAtPath } from "../../blob-storage/internal"
+import type { Property } from "../../ontology"
+import { OntologyValidationError } from "../../ontology/errors"
+import type { PropertyToken } from "../../ontology/tokens"
+import { assertPropertyTokenBelongsToObjectType } from "../../ontology/validation"
+import type { ObjectFileHandle } from "../../runtime/types"
+import type { ObjectSetContext } from "../context"
+
+export function createObjectFileHandle(
+  ctx: ObjectSetContext,
+  primaryId: string,
+  property: PropertyToken<string, string, Property>,
+  index?: number
+): ObjectFileHandle {
+  const { objectType } = ctx
+  assertPropertyTokenBelongsToObjectType(objectType, property)
+  const registered = ctx.ontology
+    .resolveObjectType(objectType.id)
+    .properties.find((candidate) => candidate.id === property.id)
+  if (!registered) {
+    throw new OntologyValidationError(
+      `[Sixb] Unknown property '${property.id}' for object type '${objectType.id}'`
+    )
+  }
+  const path = filePropertyPath(objectType.id, registered, index)
+
+  return {
+    async open() {
+      const row = await ctx.objectReader.getByPrimaryId({ objectTypeId: objectType.id, primaryId })
+      if (!row) return null
+      if (row.redactions?.[property.id]) {
+        // Redacted, so the registered property has a marking the caller is not cleared for.
+        const markings = registered.markings ?? []
+        const marking =
+          markings.find((markingId) => !ctx.authorization?.clearances?.has(markingId)) ??
+          markings[0]
+        throw new AuthorizationError(
+          `clearance:marking:${marking}`,
+          `[Sixb] Cannot open file '${objectType.id}.${property.id}': it requires clearance for marking '${marking}'.`
+        )
+      }
+      const fileRef = resolveFileRefAtPath(row, path)
+      return fileRef ? openFileRef(ctx.blobStorage, fileRef) : null
+    },
+  }
+}
+
+/** JSON Pointer to the file in an object row, validated against the property's schema. */
+function filePropertyPath(objectTypeId: string, property: Property, index: number | undefined) {
+  const { schema } = property
+  const name = `${objectTypeId}.${property.id}`
+  if (schema === "fileRef") {
+    if (index !== undefined) {
+      throw new OntologyValidationError(`[Sixb] Property ${name} holds one file; omit the index.`)
+    }
+    return `/properties/${jsonPointerSegment(property.id)}`
+  }
+  if (typeof schema === "object" && schema.type === "array" && schema.items === "fileRef") {
+    if (index === undefined || !Number.isSafeInteger(index) || index < 0) {
+      throw new OntologyValidationError(
+        `[Sixb] Property ${name} holds a list of files; pass the index of the file to open.`
+      )
+    }
+    return `/properties/${jsonPointerSegment(property.id)}/${index}`
+  }
+  throw new OntologyValidationError(
+    `[Sixb] Property ${name} is not a file: file() takes a "fileRef" property or a list of them.`
+  )
+}

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

@@ -5,26 +5,27 @@
  */
 
 import type { ActionDefinition } from "../../actions"
-import type { ObjectLink, ObjectRef } from "../../ontology"
+import type { ObjectLink, ObjectRef, Property } from "../../ontology"
 import { OntologyValidationError } from "../../ontology/errors"
-import type { LinkToken, ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
 import { assertLinkTokenBelongsToObjectType } from "../../ontology/validation"
 import type { ObjectByIdHandle, TwinObject } from "../../runtime/types"
 import {
   requestActionAndWait as requestActionAndWaitLeaf,
   requestAction as requestActionLeaf,
 } from "../action"
-import type { ExecutionObjectContext, ResolvedLinkContext } from "../context"
+import type { ObjectSetContext, ResolvedLinkContext } from "../context"
 import { removeLink as removeLinkLeaf, upsertLink as upsertLinkLeaf } from "../link"
 import { deleteObject, restoreObject } from "../object"
 import { createObjectVectorHandle } from "../vectors/handle"
+import { createObjectFileHandle } from "./file-handle"
 import { createTelemetryChannel } from "./telemetry-channel"
 
 type ObjectRefInput = ObjectRef
 type AnyLinkToken = LinkToken<string, string, string | readonly string[], ObjectLink>
 
 export function createObjectByIdHandle<TObjectType extends ObjectTypeWithPropertyTokens>(
-  ctx: ExecutionObjectContext,
+  ctx: ObjectSetContext,
   primaryId: string
 ): ObjectByIdHandle<TObjectType> {
   const objectHandle = {
@@ -130,6 +131,9 @@ export function createObjectByIdHandle<TObjectType extends ObjectTypeWithPropert
     },
 
     telemetry: createTelemetryChannel<TObjectType>(ctx, primaryId),
+
+    file: (property: PropertyToken<string, string, Property>, index?: number) =>
+      createObjectFileHandle(ctx, primaryId, property, index),
   }
 
   return objectHandle as unknown as ObjectByIdHandle<TObjectType>

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

@@ -6,6 +6,7 @@
 
 import type { ActionDefinition } from "../../actions"
 import type { AuthorizationContext } from "../../authorization"
+import type { BlobStorage } from "../../blob-storage"
 import { shareSixbErrorReporter } from "../../error-reporting/capability"
 import type { ExecutionContext } from "../../execution"
 import { assertAuthorizedObjectReaderBinding } from "../../execution/authorized-object-reader"
@@ -22,7 +23,7 @@ import {
   requestActionAndWait as requestActionAndWaitLeaf,
   requestAction as requestActionLeaf,
 } from "../action"
-import type { ExecutionObjectContext, ResolvedLinkContext } from "../context"
+import type { ObjectSetContext, ResolvedLinkContext } from "../context"
 import { requireLinkDefinition } from "../context"
 import { removeLink as removeLinkLeaf, upsertLink as upsertLinkLeaf } from "../link"
 import { upsertObject as upsertObjectLeaf } from "../object"
@@ -36,6 +37,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     readonly execution: ExecutionContext
     readonly objectType: TObjectType
     readonly authorization?: AuthorizationContext
+    readonly blobStorage: Pick<BlobStorage, "stat" | "open">
   }
 ): ObjectSet<TObjectType> {
   assertAuthorizedObjectReaderBinding({
@@ -67,7 +69,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     objectReader,
   })
 
-  const resolvedCtx: ExecutionObjectContext = {
+  const resolvedCtx: ObjectSetContext = {
     embeddingModels: params.embeddingModels,
     projectId,
     broker,
@@ -80,6 +82,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     runtimeAuthorization,
     authorization,
     execution,
+    blobStorage: params.blobStorage,
     objectType,
     primaryPropertyId,
   }

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

@@ -12,7 +12,8 @@ eligible set after link and property authorization; it never filters a global to
 
 ```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
@@ -22,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.