@sixb/core 0.1.11 → 0.1.12

package/src/materialization/index.ts

@@ -77,3 +77,4 @@ export {
   telemetryPointSortKey,
   telemetrySeriesKey,
 } from "./refs"
+export type { ObjectVectorWrite, PreparedObjectVector } from "./vectors"

package/src/materialization/model.ts

@@ -3,6 +3,7 @@ import type { EventOrigin } from "../events/envelope"
 import type { PropertyChange, PropertyChangeMap } from "../events/property-changes"
 import type { JsonValue } from "../json"
 import type { ProjectionProtocolIdentity, ProjectionRunFailureCode } from "../projections/types"
+import type { ObjectVectorWrite } from "./vectors"
 
 export type { ProjectionProtocolIdentity } from "../projections/types"
 
@@ -125,6 +126,7 @@ export type OntologyEditCommit =
       readonly source:
         | { readonly kind: "action"; readonly actionId: string; readonly runId: string }
         | { readonly kind: "runtime"; readonly requestId: string }
+      readonly vectorWrites?: readonly ObjectVectorWrite[]
       readonly expectedObjects: readonly ExpectedObjectRevision[]
       readonly expectedLinks: readonly ExpectedLinkRevision[]
       readonly expectedLinkScopes: readonly ExpectedLinkScopeRevision[]

package/src/materialization/vectors.ts

@@ -0,0 +1,18 @@
+import type { ExpectedObjectRevision, OntologyObjectRef } from "./model"
+
+/** Internal observation captured before embedding and fenced by the atomic vector write. */
+export interface PreparedObjectVector {
+  readonly projectId: string
+  readonly ref: OntologyObjectRef
+  readonly profile: string
+  readonly configuration: string
+  readonly text: string
+  readonly sourceFingerprint: string
+  readonly expectedObject: Extract<ExpectedObjectRevision, { exists: true }>
+  readonly expectedVectorCommitId: string | null
+}
+
+export interface ObjectVectorWrite {
+  readonly input: PreparedObjectVector
+  readonly values: readonly number[]
+}

package/src/materializer/README.md

@@ -124,3 +124,17 @@ finish still commit atomically.
 Keep use-case entrypoints explicit. Share mechanics only after they have identical semantics; do
 not hide projection candidate lifecycle, edit continuation, or telemetry batching behind a generic
 workflow engine.
+
+## Vector profiles
+
+The SDK's explicit `index()` captures an internal `PreparedObjectVector`: object/profile identity,
+configuration and source fingerprints, canonical input text, object revision and current vector
+commit id. Source values stay local to preparation rather than being copied into the write payload.
+Text is ordered JSON pairs of source names and values; missing/null values become `null`, while
+empty strings remain distinct. The configuration includes an encoding version.
+
+The configured model runs outside the transaction. Atomic edits then verify the object revision,
+source/configuration fingerprints and vector commit id before storing validated float32 values.
+An unrelated edit may conservatively reject in-flight indexing even when an existing vector remains
+valid. A provider failure leaves the current representation untouched and is never retried here.
+Effective-state changes invalidate affected profiles in the same transaction as the object write.

package/src/materializer/context.ts

@@ -49,6 +49,16 @@ export function createMaterializerContext(input: {
       "Materializer Ontology does not match the Ontology pinned by its projection registry."
     )
   }
+  if (
+    (!input.storage.ontology.vectors || !input.storage.ontology.vectorIndexing) &&
+    input.ontology
+      .listObjectTypes()
+      .some((type) => Object.keys(type.search?.vectors ?? {}).length > 0)
+  ) {
+    throw new MaterializationValidationError(
+      "Storage does not support transactional vector profiles and automatic indexing."
+    )
+  }
   const dependencies = input.dependencies ?? {}
   const maxSerializationRetries = dependencies.maxSerializationRetries ?? 2
   if (!Number.isSafeInteger(maxSerializationRetries) || maxSerializationRetries < 0) {

package/src/materializer/edits/commit.ts

@@ -34,6 +34,8 @@ import { compileEditExecutionUnits, type EditExecutionUnit } from "./execution-u
 import { loadEditWorkingState } from "./load-state"
 import { applyEditOperation, type EditUndoJournal, undoEditJournal } from "./operations"
 import { stageEditPlan } from "./plan"
+import { authorizeVectorIndexingCommit } from "./vector-authority"
+import { commitVectorWrites } from "./vectors"
 import type { EditWorkingState } from "./working-state"
 
 type NormalizedEditCommit = ReturnType<typeof normalizeOntologyEditCommit>
@@ -106,6 +108,7 @@ async function validateMutationExecution(
   input: NormalizedEditCommit,
   execution: MaterializerExecution
 ): Promise<void> {
+  if (await authorizeVectorIndexingCommit(storage, projectId, input, execution)) return
   if (input.source.kind !== "action") {
     assertRuntimeMutationExecution(execution)
     return
@@ -182,7 +185,8 @@ async function executeEditTransaction(
     workingState,
     editPlanContext(command)
   )
-  await drainStagedWork(context, storage.ontology.materializations, session)
+  await drainStagedWork(context, storage, session)
+  await commitVectorWrites(context, storage, command.input, command.identity.commitId, session)
   const eventCount = await drainStagedEvents(
     context,
     storage.ontology.materializations,
@@ -234,6 +238,9 @@ function buildEditCommit(
       kind: "edit",
       mode: command.input.mode,
       operationCount: command.input.operations.length,
+      ...(command.input.mode === "atomic" && command.input.vectorWrites?.length
+        ? { vectorWriteCount: command.input.vectorWrites.length }
+        : {}),
     },
     committedAt: command.identity.committedAt,
   }

package/src/materializer/edits/vector-authority.ts

@@ -0,0 +1,108 @@
+import {
+  MaterializationConflictError,
+  MaterializationValidationError,
+} from "../../materialization/errors"
+import type { OntologyEditCommit } from "../../materialization/model"
+import { objectRefKey } from "../../materialization/refs"
+import type { ObjectVectorWrite } from "../../materialization/vectors"
+import type { Storage } from "../../storage"
+import type { VectorIndexingWork } from "../../storage/ontology/vector-indexing"
+import type { MaterializerExecution } from "../execution/scope"
+
+/** Kernel indexing can publish only its persisted results, never change business data. */
+export async function authorizeVectorIndexingCommit(
+  storage: Storage,
+  projectId: string,
+  input: OntologyEditCommit,
+  execution: MaterializerExecution
+): Promise<boolean> {
+  const executor = execution.scope.execution.executor
+  if (executor.type !== "kernel" || executor.operation.type !== "ontology.indexVectors")
+    return false
+  if (
+    input.mode !== "atomic" ||
+    input.source.kind !== "runtime" ||
+    input.operations.length ||
+    !input.vectorWrites?.length ||
+    input.expectedLinks.length ||
+    input.expectedLinkScopes.length
+  ) {
+    throw new MaterializationValidationError(
+      "Vector indexing authority only permits its persisted vector writes."
+    )
+  }
+  const writes = input.vectorWrites!
+  const refs = new Set(writes.map((write) => objectRefKey(write.input.ref)))
+  if (
+    input.expectedObjects.length !== refs.size ||
+    input.expectedObjects.some((expected) => !refs.has(objectRefKey(expected.ref)))
+  ) {
+    throw new MaterializationValidationError(
+      "Vector indexing must fence exactly its written objects."
+    )
+  }
+
+  const indexing = storage.ontology.vectorIndexing
+  const indexingId = executor.operation.indexingId
+  const single = await indexing?.get({ projectId, id: indexingId })
+  if (single && writes.length !== 1) {
+    throw new MaterializationValidationError(
+      "Individual indexing authority only permits one vector write."
+    )
+  }
+
+  // Multi-object publication reads membership/results once, not once per object.
+  let members: readonly VectorIndexingWork[]
+  if (single) {
+    members = [single]
+  } else if (writes.length === 1) {
+    const member = await indexing?.getBatchMember({
+      projectId,
+      batchId: indexingId,
+      ref: writes[0]!.input.ref,
+      profile: writes[0]!.input.profile,
+    })
+    members = member ? [member] : []
+  } else {
+    members = (await indexing?.getBatch({ projectId, batchId: indexingId })) ?? []
+  }
+
+  const byProfile = new Map(
+    members.map((work) => [JSON.stringify([objectRefKey(work.ref), work.profile]), work])
+  )
+  const source = execution.scope.execution.source
+
+  for (const write of writes) {
+    const work = byProfile.get(JSON.stringify([objectRefKey(write.input.ref), write.input.profile]))
+    if (!work || work.status !== "ready") {
+      throw new MaterializationConflictError(
+        "effective-state",
+        "Vector indexing work is no longer ready."
+      )
+    }
+    if (
+      source.type !== "ontologyCommit" ||
+      source.commitId !== work.sourceCommitId ||
+      !matchesStoredResult(write, work)
+    ) {
+      throw new MaterializationValidationError(
+        "Vector indexing authority only permits its current prepared representation."
+      )
+    }
+  }
+  return true
+}
+
+function matchesStoredResult(write: ObjectVectorWrite, work: VectorIndexingWork): boolean {
+  const prepared = write.input
+  return (
+    prepared.ref.objectTypeId === work.ref.objectTypeId &&
+    prepared.ref.primaryId === work.ref.primaryId &&
+    prepared.profile === work.profile &&
+    prepared.configuration === work.configuration &&
+    prepared.sourceFingerprint === work.sourceFingerprint &&
+    work.values !== undefined &&
+    work.values.length === write.values.length &&
+    work.values.every((value, index) => value === write.values[index])
+  )
+}

package/src/materializer/edits/vectors.ts

@@ -0,0 +1,100 @@
+import {
+  MaterializationConflictError,
+  MaterializationValidationError,
+} from "../../materialization/errors"
+import type { OntologyEditCommit } from "../../materialization/model"
+import { objectRefKey } from "../../materialization/refs"
+import { normalizeVector, vectorConfiguration, vectorSources } from "../../objects/vectors/profile"
+import type { Storage } from "../../storage"
+import { objectBatchKey } from "../../storage/objects/keys"
+import type { MaterializationSession, OntologyVectorStorage } from "../../storage/ontology"
+import type { MaterializerContext } from "../context"
+
+export async function commitVectorWrites(
+  context: MaterializerContext,
+  storage: Storage,
+  input: OntologyEditCommit,
+  commitId: string,
+  session: MaterializationSession
+): Promise<void> {
+  if (input.mode !== "atomic" || !input.vectorWrites?.length) return
+  const vectors = storage.ontology.vectors
+  if (!vectors)
+    throw new MaterializationValidationError("Storage does not support vector profiles.")
+  const rows = await storage.objects.getByPrimaryIdBatch({
+    projectId: context.projectId,
+    items: input.vectorWrites.map((write) => write.input.ref),
+  })
+  const expectations = new Map(
+    input.expectedObjects.map((expected) => [objectRefKey(expected.ref), expected])
+  )
+  const entries: Parameters<OntologyVectorStorage["writeBatch"]>[0]["entries"][number][] = []
+  const seen = new Set<string>()
+  for (const write of input.vectorWrites) {
+    const prepared = write.input
+    const key = JSON.stringify([objectRefKey(prepared.ref), prepared.profile])
+    if (seen.has(key)) throw new MaterializationValidationError(`Duplicate vector write: ${key}`)
+    seen.add(key)
+    const profileDefinition = context.ontology.resolveObjectType(prepared.ref.objectTypeId).search
+      ?.vectors?.[prepared.profile]
+    if (
+      prepared.projectId !== context.projectId ||
+      !profileDefinition ||
+      vectorConfiguration(profileDefinition) !== prepared.configuration
+    ) {
+      throw new MaterializationConflictError(
+        "effective-state",
+        "Vector profile configuration changed; index it again."
+      )
+    }
+    const expected = expectations.get(objectRefKey(prepared.ref))
+    if (
+      !expected?.exists ||
+      !prepared.expectedObject?.exists ||
+      objectRefKey(prepared.expectedObject.ref) !== objectRefKey(prepared.ref) ||
+      expected.version !== prepared.expectedObject.version ||
+      expected.lastCommitId !== prepared.expectedObject.lastCommitId
+    ) {
+      throw new MaterializationValidationError(
+        "Vector writes must fence their prepared object revision."
+      )
+    }
+    const row = rows.get(objectBatchKey(prepared.ref.objectTypeId, prepared.ref.primaryId))
+    if (
+      !row ||
+      row.version !== expected.version ||
+      row.lastCommitId !== expected.lastCommitId ||
+      vectorSources(profileDefinition.source, row.properties).sourceFingerprint !==
+        prepared.sourceFingerprint
+    ) {
+      throw new MaterializationConflictError(
+        "effective-state",
+        "Vector sources changed; index the profile again."
+      )
+    }
+    entries.push({
+      expectedCommitId: prepared.expectedVectorCommitId,
+      value: {
+        ref: prepared.ref,
+        profile: prepared.profile,
+        configuration: prepared.configuration,
+        source: profileDefinition.source,
+        sourceFingerprint: prepared.sourceFingerprint,
+        values: normalizeVector(write.values, profileDefinition.model.definition.dimensions),
+        lastCommitId: commitId,
+      },
+    })
+  }
+
+  await vectors.writeBatch({ session, projectId: context.projectId, entries })
+  await storage.ontology.vectorIndexing?.complete({
+    session,
+    projectId: context.projectId,
+    entries: input.vectorWrites.map(({ input: prepared }) => ({
+      ref: prepared.ref,
+      profile: prepared.profile,
+      configuration: prepared.configuration,
+      sourceFingerprint: prepared.sourceFingerprint,
+    })),
+  })
+}

package/src/materializer/effective/validate.ts

@@ -1,3 +1,4 @@
+import { withFailureMessage } from "../../errors/failure-message"
 import type { JsonValue } from "../../json"
 import { MaterializationValidationError } from "../../materialization/errors"
 import type {
@@ -113,8 +114,11 @@ export function validateEffectiveObject(
         property.required &&
         properties[property.id] === undefined
       ) {
-        throw new Error(
-          `[Sixb] Missing required property '${property.id}' for object type '${objectType.id}'`
+        throw withFailureMessage(
+          new Error(
+            `[Sixb] Missing required property '${property.id}' for object type '${objectType.id}'`
+          ),
+          `Missing required property '${objectType.id}.${property.id}'.`
         )
       }
     }
@@ -175,6 +179,9 @@ function materializationValidation<T>(run: () => T): T {
     return run()
   } catch (error) {
     if (error instanceof MaterializationValidationError) throw error
-    throw new MaterializationValidationError(error instanceof Error ? error.message : String(error))
+    throw new MaterializationValidationError(
+      error instanceof Error ? error.message : String(error),
+      { cause: error }
+    )
   }
 }

package/src/materializer/effective/vector-indexing.ts

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto"
+import type { OntologyObjectRef } from "../../materialization/model"
+import { vectorConfiguration, vectorSources } from "../../objects/vectors/profile"
+import type { Storage } from "../../storage"
+import { objectBatchKey } from "../../storage/objects/keys"
+import type { MaterializationSession } from "../../storage/ontology"
+import type { VectorIndexingRequest } from "../../storage/ontology/vector-indexing"
+import type { MaterializerContext } from "../context"
+import type { MaterializationPlanItem } from "../execution/plan-stream"
+
+/** Source assertions are not effective values: schedule only after conflict resolution. */
+export async function scheduleVectorChanges(
+  context: Pick<MaterializerContext, "projectId" | "ontology" | "clock">,
+  storage: Storage,
+  items: readonly MaterializationPlanItem[],
+  session: MaterializationSession,
+  projection = false
+): Promise<void> {
+  const indexing = storage.ontology.vectorIndexing
+  if (!indexing) return
+  const upserts = items
+    .filter((item) => item.kind === "object-upsert")
+    .filter(
+      (item) =>
+        Object.keys(
+          context.ontology.resolveObjectType(item.value.row.ref.objectTypeId).search?.vectors ?? {}
+        ).length > 0
+    )
+  const previous = await storage.objects.getByPrimaryIdBatch({
+    projectId: context.projectId,
+    items: upserts.map((item) => item.value.row.ref),
+  })
+  const requests: VectorIndexingRequest[] = []
+  const deleted: OntologyObjectRef[] = []
+  // Groups exist only for this materialization page and are persisted in its transaction.
+  const groups = new Map<string, { id: string; count: number; bytes: number }>()
+  for (const item of items) {
+    if (item.kind === "object-delete") {
+      deleted.push(item.value.ref)
+      continue
+    }
+    if (item.kind !== "object-upsert") continue
+    const row = item.value.row
+    const profiles = context.ontology.resolveObjectType(row.ref.objectTypeId).search?.vectors ?? {}
+    const before = previous.get(objectBatchKey(row.ref.objectTypeId, row.ref.primaryId))
+    for (const [profile, definition] of Object.entries(profiles)) {
+      const { sourceFingerprint, text } = vectorSources(definition.source, row.properties)
+      if (
+        before &&
+        vectorSources(definition.source, before.properties).sourceFingerprint === sourceFingerprint
+      )
+        continue
+      const configuration = vectorConfiguration(definition)
+      const bytes = Buffer.byteLength(text)
+      const key = JSON.stringify([row.ref.objectTypeId, profile, configuration, row.lastCommitId])
+      let group = projection ? groups.get(key) : undefined
+      if (projection && (!group || group.count === 32 || group.bytes + bytes > 32_768)) {
+        group = { id: randomUUID(), count: 0, bytes: 0 }
+        groups.set(key, group)
+      }
+      if (group) {
+        group.count++
+        group.bytes += bytes
+      }
+      requests.push({
+        ...(group ? { batchId: group.id } : {}),
+        id: randomUUID(),
+        ref: row.ref,
+        profile,
+        sourceFingerprint,
+        configuration,
+        sourceCommitId: row.lastCommitId,
+      })
+    }
+  }
+  if (requests.length || deleted.length)
+    await indexing.schedule({
+      projectId: context.projectId,
+      session,
+      requests,
+      deleted,
+      availableAt: context.clock().toISOString(),
+    })
+}

package/src/materializer/effective/vectors.ts

@@ -0,0 +1,47 @@
+import { objectRefKey } from "../../materialization/refs"
+import { vectorSources } from "../../objects/vectors/profile"
+import type { MaterializationSession } from "../../storage/ontology"
+import type { OntologyVectorStorage } from "../../storage/ontology/vectors"
+import type { MaterializationPlanItem } from "../execution/plan-stream"
+
+/** Invalidate a bounded materialization page, including stored profiles no longer declared. */
+export async function invalidateVectorChanges(
+  projectId: string,
+  vectors: OntologyVectorStorage | undefined,
+  items: readonly MaterializationPlanItem[],
+  session: MaterializationSession
+): Promise<void> {
+  if (!vectors) return
+  const changes = new Map(
+    items.flatMap((item) => {
+      if (item.kind !== "object-upsert" && item.kind !== "object-delete") return []
+      const ref = item.kind === "object-upsert" ? item.value.row.ref : item.value.ref
+      return [[objectRefKey(ref), { ref, item }] as const]
+    })
+  )
+  if (!changes.size) return
+
+  const stored = await vectors.listBatch({
+    projectId,
+    refs: [...changes.values()].map(({ ref }) => ref),
+  })
+  const removals: Parameters<OntologyVectorStorage["removeBatch"]>[0]["entries"][number][] = []
+  for (const entry of stored) {
+    const change = changes.get(objectRefKey(entry.ref))
+    if (!change) continue
+    const { item } = change
+    if (
+      item.kind === "object-upsert" &&
+      entry.source.every((id) => {
+        const value = item.value.row.properties[id]
+        return value === undefined || value === null || typeof value === "string"
+      }) &&
+      vectorSources(entry.source, item.value.row.properties).sourceFingerprint ===
+        entry.sourceFingerprint
+    )
+      continue
+
+    removals.push({ ref: entry.ref, profile: entry.profile, expectedCommitId: entry.lastCommitId })
+  }
+  if (removals.length) await vectors.removeBatch({ session, projectId, entries: removals })
+}

package/src/materializer/execution/work-executor.ts

@@ -1,5 +1,6 @@
 import { MaterializationValidationError } from "../../materialization/errors"
 import { utf8JsonByteLength } from "../../materialization/refs"
+import type { Storage } from "../../storage"
 import type {
   MaterializationSession,
   MaterializationWorkRecord,
@@ -7,6 +8,8 @@ import type {
 } from "../../storage/ontology"
 import type { MaterializerContext } from "../context"
 import { sequenceMaterializationEvent } from "../effective/build-events"
+import { scheduleVectorChanges } from "../effective/vector-indexing"
+import { invalidateVectorChanges } from "../effective/vectors"
 import { throwIfAborted } from "../shared/abort"
 import { chunkBySize } from "../shared/chunking"
 import type { TimedCommitIdentity } from "../shared/identity"
@@ -46,15 +49,20 @@ export async function stageWorkBounded(
 }
 
 export async function drainStagedWork(
-  context: BatchingContext,
-  storage: OntologyMaterializationStorage,
+  context: Pick<MaterializerContext, "batching" | "projectId" | "ontology" | "clock">,
+  transactionStorage: Storage,
   session: MaterializationSession,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  projection = false
 ): Promise<void> {
+  const ontologyStorage = transactionStorage.ontology
+  const storage = ontologyStorage.materializations
   let phase: number | null = null
   let pending: MaterializationPlanItem[] = []
   const flush = async () => {
     if (pending.length === 0) return
+    await scheduleVectorChanges(context, transactionStorage, pending, session, projection)
+    await invalidateVectorChanges(context.projectId, ontologyStorage.vectors, pending, session)
     await applyItems(context, storage, session, pending, signal)
     pending = []
   }

package/src/materializer/projections/replace.ts

@@ -347,7 +347,7 @@ async function executeProjectionTransaction(
     ready,
     origin
   )
-  await drainStagedWork(context, storage.ontology.materializations, session, command.signal)
+  await drainStagedWork(context, storage, session, command.signal, true)
   const eventCount = await drainStagedEvents(
     context,
     storage.ontology.materializations,

package/src/materializer/shared/normalize.ts

@@ -269,6 +269,8 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
   })
 
   if (input.mode === "continue") {
+    if ("vectorWrites" in input)
+      throw new MaterializationValidationError("Vector writes require an atomic commit.")
     return Object.freeze({
       mode: "continue",
       source: Object.freeze({
@@ -293,12 +295,21 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
           kind: "runtime" as const,
           requestId: normalizeNonblank(input.source.requestId, "Runtime request id"),
         })
+  if (input.vectorWrites?.length && (operations.length || input.source.kind !== "runtime")) {
+    throw new MaterializationValidationError(
+      "Vector writes require a dedicated atomic runtime commit."
+    )
+  }
+  if (input.vectorWrites !== undefined) assertJsonValue(input.vectorWrites, "Vector writes")
   const expectedObjects = input.expectedObjects.map(normalizeExpectedObject)
   const expectedLinks = input.expectedLinks.map(normalizeExpectedLink)
   const expectedLinkScopes = input.expectedLinkScopes.map(normalizeExpectedLinkScope)
 
   return Object.freeze({
     mode: "atomic",
+    ...(input.vectorWrites === undefined
+      ? {}
+      : { vectorWrites: structuredClone(input.vectorWrites) }),
     source,
     operations: Object.freeze(operations),
     expectedObjects: deduplicateExpectations(

package/src/materializer/telemetry/append.ts

@@ -404,7 +404,7 @@ async function executeTelemetryTransaction(
       ...(command.execution.actor === undefined ? {} : { actor: command.execution.actor }),
     }
   )
-  await drainStagedWork(context, storage.ontology.materializations, session)
+  await drainStagedWork(context, storage, session)
   const eventCount = await drainStagedEvents(
     context,
     storage.ontology.materializations,

package/src/models/catalog-index.ts

@@ -0,0 +1,38 @@
+import { RuntimeError } from "../runtime/errors"
+import type { ModelRef } from "./catalog"
+
+interface ModelBinding {
+  readonly providerId: string
+  readonly modelId: string
+}
+
+interface ModelEntry<TModel> extends ModelRef {
+  readonly model: TModel
+}
+
+/** Private index shared by model families; default selection belongs to each family. */
+export function indexModelBindings<TModel extends ModelBinding>(
+  models: readonly TModel[],
+  kind: string,
+  validate: (model: TModel, index: number) => void
+) {
+  const byRef = new Map<string, ModelEntry<TModel>>()
+
+  for (const [index, model] of models.entries()) {
+    validate(model, index)
+    const key = JSON.stringify([model.providerId, model.modelId])
+    if (byRef.has(key)) {
+      throw new RuntimeError(
+        `[Sixb] Duplicate ${kind} model '${model.providerId}/${model.modelId}' in 'models.${kind}'. Each provider and model id pair may be configured once.`
+      )
+    }
+
+    byRef.set(key, Object.freeze({ provider: model.providerId, modelId: model.modelId, model }))
+  }
+
+  const entries = Object.freeze([...byRef.values()])
+  return Object.freeze({
+    list: () => entries,
+    getByRef: (ref: ModelRef) => byRef.get(JSON.stringify([ref.provider, ref.modelId])) ?? null,
+  })
+}