@sixb/core 0.1.11 → 0.1.12

package/src/objects/query/validate.ts

@@ -9,6 +9,8 @@ import type {
 import { normalizeDecimalValue } from "../../ontology"
 import { formatUnknownObjectTypeMessage } from "../../ontology/errors"
 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 +20,7 @@ import type {
   ObjectQueryResultShape,
   ObjectQuerySetOperation,
   ObjectQuerySortField,
+  ObjectQueryVector,
   QueryScalarKind,
 } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
@@ -172,6 +175,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 +198,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 +210,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 +327,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,
       }
     }
@@ -845,67 +857,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 +1523,7 @@ function assertStaticSearchProperty(
 function assertQueryFlag(
   objectTypeId: string,
   property: Property,
-  flag: "text" | "vector",
+  flag: "text",
   context: string,
   path: string,
   ctx: QueryValidationContext
@@ -1607,13 +1615,6 @@ function isContainsSchema(schema: Schema): boolean {
   )
 }
 
-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,6 +3,7 @@
  * 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 { OntologyValidationError } from "../../ontology/errors"
@@ -16,6 +17,7 @@ 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
@@ -26,6 +28,7 @@ export function createObjectByIdHandle<
   TValueTypes extends readonly ValueType[],
 >(ctx: ExecutionObjectContext, primaryId: string): ObjectByIdHandle<TObjectType, TValueTypes> {
   const objectHandle = {
+    vector: (profileName: string) => createObjectVectorHandle(ctx, primaryId, profileName),
     get: async () => {
       const row = await ctx.objectReader.getByPrimaryId({
         objectTypeId: ctx.objectType.id,

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

@@ -73,6 +73,7 @@ export function createObjectSet<
   })
 
   const resolvedCtx: ExecutionObjectContext = {
+    embeddingModels: params.embeddingModels,
     projectId,
     broker,
     ontology,

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

@@ -93,14 +93,17 @@ class ObjectQueryBuilderImpl<
   }
 
   vector(
-    property: PropertyToken<TObjectType["id"], string>,
-    vector: readonly number[],
+    profile: string,
+    vector: string,
     options: { k: number }
   ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes> {
+    if (typeof profile !== "string" || typeof vector !== "string") {
+      throw new Error("[Sixb] Vector search requires a named profile and search text")
+    }
     return this.withQuery({
       kind: "vector",
       input: this.ir,
-      propertyId: property.id,
+      profile,
       vector,
       k: options.k,
     })
@@ -227,9 +230,11 @@ class ObjectQueryBuilderImpl<
   async list(): Promise<ListResult<TwinObject<TObjectType, TValueTypes>>>
   async list(options: {
     includeTotal: false
+    signal?: AbortSignal
   }): Promise<ListResultWithoutTotal<TwinObject<TObjectType, TValueTypes>>>
   async list(options: {
     includeTotal?: true
+    signal?: AbortSignal
   }): Promise<ListResult<TwinObject<TObjectType, TValueTypes>>>
   async list(
     options?: ObjectQueryListOptions
@@ -239,6 +244,7 @@ class ObjectQueryBuilderImpl<
   > {
     const result = await this.params.executor.list(this.ir, {
       includeTotal: options?.includeTotal,
+      signal: options?.signal,
     })
     const objects = result.objects.map(
       (row) => row as unknown as TwinObject<TObjectType, TValueTypes>

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

@@ -11,6 +11,7 @@ import type { ObjectQuery } from "../query/ir"
 import type { ValidatedObjectQuery } from "../query/validate"
 
 export type ObjectQueryExecutorRow = {
+  score?: number
   primaryId: string
   objectTypeId: string
   properties: Record<string, unknown>
@@ -47,7 +48,7 @@ export type ObjectQueryExecutorFacetRequest = {
 export interface ObjectQueryExecutor {
   list(
     query: ObjectQuery,
-    options?: { includeTotal?: boolean }
+    options?: { includeTotal?: boolean; signal?: AbortSignal }
   ): Promise<ObjectQueryExecutorListResult>
   count(query: ObjectQuery): Promise<number>
   exists(query: ObjectQuery): Promise<boolean>

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

@@ -19,9 +19,13 @@ export function createRuntimeQueryExecutor(params: {
   const { ontology, objectReader } = params
 
   return {
-    async list(query: ObjectQuery, options?: { includeTotal?: boolean }) {
+    async list(query: ObjectQuery, options?: { includeTotal?: boolean; signal?: AbortSignal }) {
       try {
-        return await objectReader.executeQuery({ query, includeTotal: options?.includeTotal })
+        return await objectReader.executeQuery({
+          query,
+          includeTotal: options?.includeTotal,
+          signal: options?.signal,
+        })
       } catch (error) {
         if (error instanceof ObjectQueryPlanningError) {
           throw addSdkPlanningHints(error)

package/src/objects/vectors/README.md

@@ -0,0 +1,59 @@
+# Vector indexing
+
+A named profile identifies a derived representation, separate from object properties.
+
+```text
+Effective object change → invalidate stale vector + persist latest intent (one transaction)
+ProjectionWorker → durable queue → project AI admission → provider → save result → fenced commit
+```
+
+`materializer/effective/vector-indexing.ts` compares effective source fingerprints after projection
+conflict resolution, including managed overrides. New objects schedule every profile. Unrelated
+changes schedule nothing. Deletion removes intent; each new generation replaces the old id.
+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.
+
+`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.
+The Materializer checks membership, identity, values and each object/vector revision in the transaction. Execution provenance
+references the source ontology commit; requester and groups are empty, so only project budgets apply.
+
+The durable `running` fence precedes admission, so superseded work cannot reserve budget. The
+provider starts only after both succeed. An admission rejection returns work to pending for retry.
+Redelivered `running` work has an uncertain provider outcome: fail visibly through `onError`, never
+silently repeat inference. The provider may have billed a lost response. Failures remain inspectable until superseded or explicitly indexed.
+
+Persist `ready` values before committing. On unrelated edits, reprepare the object revision and reuse
+those values. Source changes, deletion/recreation, or configuration mismatch discard obsolete work.
+A vector-only commit never schedules itself. Manual indexing remains available through authorized
+SDK executions; its valid result also makes queued work unnecessary.
+
+Projection replacement assigns `batchId` within each materialization page: same object type,
+profile, configuration and source commit, at most 32 members / 32 KiB of serialized source text.
+Membership is stored alongside intent in the activation transaction; there is no fill timer, process
+buffer or cross-run aggregation. An oversized text is isolated, never truncated.
+
+Dispatch uses the group id. Processing reads current members, drops obsolete work, and splits them
+to the adapter's optional `EmbeddingModel.batching` count / UTF-8 byte bounds. Unknown bounds or
+oversized inputs use individual calls. Search, explicit indexing and managed edits stay individual.
+Each actual provider request produces one usage/cost record, under the project's group execution.
+Admission claims all prepared members atomically before reserving budget; a superseded member
+aborts that claim. Results become ready atomically for surviving members, then publish together in
+one materialization transaction. PostgreSQL groups vector writes and intent cleanup in SQL; SQLite
+reuses prepared statements within that transaction. Every object and vector retains its own revision
+fence. A conflict rolls back publication and reprepares the current subset without inference. After
+three conflicts, individual publication lets stable peers finish while contended members are deferred.
+Restarted ready members only retry storage; running members fail with an unknown outcome.
+A partly processed group publishes ready members together and resumes other members individually.
+
+Network calls never hold storage transactions. Applications without projections do not start this
+indexing consumer. Byte bounds are conservative transport eligibility, not the accounting layer's
+token estimate; they do not reject or truncate a text that can still be sent individually.
+
+Terminal failures persist a canonical `SixbFailure` before `onError`: `vector.model_unavailable`,
+`vector.response_invalid`, or `vector.outcome_unknown` for interrupted calls. Unclassified failures
+use `internal.unexpected`. These codes never authorize automatic inference retries. Accounting uses
+`ModelExecutionSession`; its existing recovery consumer can replay accounting without inference.

package/src/objects/vectors/handle.ts

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto"
+import { assertCanEdit } from "../../authorization"
+import { AuthorizationError } from "../../authorization/errors"
+import { MaterializationValidationError } from "../../materialization/errors"
+import type { PreparedObjectVector } from "../../materialization/vectors"
+import { sameEmbeddingModel } from "../../models/embedding-model"
+import { getOntologyMutationRuntime } from "../../runtime/ontology-mutations"
+import type { ExecutionObjectContext } from "../context"
+import { normalizeVector, vectorConfiguration, vectorSources } from "./profile"
+import type { ObjectVectorHandle } from "./types"
+
+export function createObjectVectorHandle(
+  ctx: ExecutionObjectContext,
+  primaryId: string,
+  profileName: string
+): ObjectVectorHandle {
+  const ref = Object.freeze({ objectTypeId: ctx.objectType.id, primaryId })
+  const profileDefinition = ctx.ontology.resolveObjectType(ref.objectTypeId).search?.vectors?.[
+    profileName
+  ]
+  if (!profileDefinition)
+    throw new MaterializationValidationError(`Unknown vector profile: ${profileName}`)
+  const vectors = ctx.storage.ontology.vectors
+  if (!vectors)
+    throw new MaterializationValidationError("Storage does not support vector profiles.")
+
+  const assertReadable = async () => {
+    const allowed = await ctx.objectReader.canReadObjectPropertiesBatch({
+      items: profileDefinition.source.map((propertyId) => ({ ...ref, propertyId })),
+    })
+    if (allowed.some((value) => !value))
+      throw new AuthorizationError(
+        `view:object:${ref.objectTypeId}`,
+        "[Sixb] Vector profile requires access to all its source properties."
+      )
+  }
+
+  return Object.freeze({
+    async index(): Promise<void> {
+      assertCanEdit(ctx, ref.objectTypeId)
+      await assertReadable()
+      const mutations = getOntologyMutationRuntime(ctx)
+      const model = ctx.embeddingModels?.getByRef({
+        provider: profileDefinition.model.providerId,
+        modelId: profileDefinition.model.modelId,
+      })?.model
+      if (!model || !sameEmbeddingModel(model, profileDefinition.model)) {
+        throw new MaterializationValidationError(
+          `Vector profile '${profileName}' requires its configured embedding model.`
+        )
+      }
+      const row = await ctx.objectReader.getByPrimaryId(ref)
+      if (!row) throw new MaterializationValidationError("Cannot index a missing object.")
+      const current = (await vectors.list({ projectId: ctx.projectId, ref })).find(
+        (entry) => entry.profile === profileName
+      )
+      const input: PreparedObjectVector = {
+        projectId: ctx.projectId,
+        ref,
+        profile: profileName,
+        configuration: vectorConfiguration(profileDefinition),
+        ...vectorSources(profileDefinition.source, row.properties),
+        expectedObject: { ref, exists: true, version: row.version, lastCommitId: row.lastCommitId },
+        expectedVectorCommitId: current?.lastCommitId ?? null,
+      }
+
+      // Network work never holds a storage transaction or retries an obsolete computation.
+      const result = await model.embed({ texts: [input.text] })
+      if (!Array.isArray(result?.vectors) || result.vectors.length !== 1) {
+        throw new MaterializationValidationError(
+          "Embedding model must return exactly one vector for one input text."
+        )
+      }
+      const values = normalizeVector(
+        result.vectors[0]!,
+        profileDefinition.model.definition.dimensions
+      )
+      assertCanEdit(ctx, ref.objectTypeId)
+      await assertReadable()
+      await mutations.commitEdits({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: randomUUID() },
+        operations: [],
+        vectorWrites: [{ input, values }],
+        expectedObjects: [input.expectedObject],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    },
+  })
+}

package/src/objects/vectors/indexing-batch.ts

@@ -0,0 +1,163 @@
+import type { OntologyMaterializerContract } from "../../materializer/materializer"
+import type { EmbeddingBatchLimits } from "../../models/embedding-model"
+import type { SixbHostContext } from "../../runtime/types"
+import type { VectorIndexingWork } from "../../storage/ontology/vector-indexing"
+import { generateVectors, type PreparedIndexingWork } from "./indexing-generate"
+import { indexingScope, prepare, VectorIndexingDeferred } from "./indexing-shared"
+import { processVector } from "./indexing-single"
+import { storeVectorBatch } from "./indexing-store-batch"
+
+/** Membership was persisted by one projection commit; there is no fill timer or memory queue. */
+export async function processVectorBatch(
+  runtime: SixbHostContext,
+  materializer: OntologyMaterializerContract,
+  batchId: string,
+  batch: readonly VectorIndexingWork[],
+  attempt: number,
+  signal: AbortSignal
+): Promise<void> {
+  if (batch.some((work) => work.status !== "pending")) {
+    await resumeBatch(runtime, materializer, batchId, batch, attempt, signal)
+    return
+  }
+
+  const entries = await prepareBatch(runtime, batch, signal)
+  const first = entries[0]
+  if (!first) return
+
+  const limits = getBatchLimits(runtime, first.work)
+  if (!limits) {
+    // Unknown provider batch limits: embed each object/profile individually.
+    for (const { work } of entries) {
+      await processVector(runtime, materializer, work.id, attempt, signal)
+    }
+    return
+  }
+
+  assertCompatibleEntries(entries, first.work)
+  const scope = await indexingScope(runtime, first.work, batchId)
+
+  for (const group of partition(entries, limits)) {
+    if (group.length === 1) {
+      await processVector(runtime, materializer, group[0]!.work.id, attempt, signal)
+    } else {
+      await generateVectors(runtime, group, scope, attempt, signal)
+    }
+  }
+
+  await storeVectorBatch(runtime, materializer, batchId, scope, signal)
+}
+
+/** Resume storage or terminalize interrupted calls; never repeat paid inference. */
+async function resumeBatch(
+  runtime: SixbHostContext,
+  materializer: OntologyMaterializerContract,
+  batchId: string,
+  batch: readonly VectorIndexingWork[],
+  attempt: number,
+  signal: AbortSignal
+): Promise<void> {
+  const ready = batch.find((work) => work.status === "ready")
+  if (ready) {
+    const scope = await indexingScope(runtime, ready, batchId)
+    await storeVectorBatch(runtime, materializer, batchId, scope, signal)
+  }
+
+  for (const work of batch) {
+    if (work.status !== "ready") {
+      await processVector(runtime, materializer, work.id, attempt, signal)
+    }
+  }
+}
+
+async function prepareBatch(
+  runtime: SixbHostContext,
+  batch: readonly VectorIndexingWork[],
+  signal: AbortSignal
+): Promise<PreparedIndexingWork[]> {
+  const availableAt = batch.reduce(
+    (latest, work) => (work.availableAt > latest ? work.availableAt : latest),
+    ""
+  )
+  if (Date.parse(availableAt) > Date.now()) {
+    throw new VectorIndexingDeferred(availableAt)
+  }
+
+  const entries: PreparedIndexingWork[] = []
+  const indexing = runtime.storage.ontology.vectorIndexing!
+
+  for (const work of batch) {
+    signal.throwIfAborted()
+    const input = await prepare(runtime, work)
+
+    if (input) {
+      entries.push({ work, input })
+    } else {
+      await indexing.remove({ projectId: runtime.projectId, id: work.id })
+    }
+  }
+
+  return entries
+}
+
+function getBatchLimits(
+  runtime: SixbHostContext,
+  work: VectorIndexingWork
+): EmbeddingBatchLimits | undefined {
+  const profile = runtime.ontology.resolveObjectType(work.ref.objectTypeId).search!.vectors![
+    work.profile
+  ]!
+
+  return runtime.embeddingModels?.getByRef({
+    provider: profile.model.providerId,
+    modelId: profile.model.modelId,
+  })?.model.batching
+}
+
+/** Do not mix commits or configurations, even with malformed storage membership. */
+function assertCompatibleEntries(
+  entries: readonly PreparedIndexingWork[],
+  reference: VectorIndexingWork
+): void {
+  const incompatible = entries.some(
+    ({ work }) =>
+      work.sourceCommitId !== reference.sourceCommitId ||
+      work.ref.objectTypeId !== reference.ref.objectTypeId ||
+      work.profile !== reference.profile ||
+      work.configuration !== reference.configuration
+  )
+
+  if (incompatible) {
+    throw new Error("[Sixb] Incompatible vector batch membership.")
+  }
+}
+
+/** Split an already durable, bounded page; never wait for more work or truncate input. */
+function* partition(entries: readonly PreparedIndexingWork[], limits: EmbeddingBatchLimits) {
+  let group: PreparedIndexingWork[] = []
+  let bytes = 0
+
+  for (const entry of entries) {
+    const size = Buffer.byteLength(entry.input.text)
+    const exceedsGroupLimit =
+      group.length >= limits.maxInputs ||
+      bytes + size > limits.maxTotalInputBytes ||
+      size > limits.maxInputBytes
+
+    if (group.length > 0 && exceedsGroupLimit) {
+      yield group
+      group = []
+      bytes = 0
+    }
+
+    if (size > limits.maxInputBytes || size > limits.maxTotalInputBytes) {
+      yield [entry]
+      continue
+    }
+
+    group.push(entry)
+    bytes += size
+  }
+
+  if (group.length > 0) yield group
+}