@sixb/core 0.1.21 → 0.1.22

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

@@ -1,11 +1,16 @@
 import { stableJsonStringify } from "../../json"
 import type { EffectiveLinkChange, EffectiveObjectChange } from "../../materialization/model"
+import { canonicalIdentitySortKey } from "../../materialization/refs"
+import type { OntologyRegistry } from "../../ontology"
+import { UNIQUE_VALUE_KEY_VERSION, uniqueValueKey } from "../../ontology/unique-values"
 import type {
+  ExactUniqueValueWrite,
   MaterializationClassificationWorkRecord,
   MaterializationEventWorkRecord,
   MaterializationPlanWorkItem,
   MaterializationPlanWorkRecord,
   MaterializationWorkEntityKind,
+  MaterializationWorkRecord,
 } from "../../storage/ontology"
 import { materializationApplyPhase } from "../../storage/ontology/materializations"
 import type { WorkingLinkEdge, WorkingLinkSlot, WorkingObject } from "../edits/working-state"
@@ -132,6 +137,48 @@ export function appendEffectiveObjectWork(
   }
 }
 
+/**
+ * Releases the unique values an object change gives up and claims those it takes. Storage applies
+ * every release of a commit before its first claim, so values can move between its objects.
+ */
+export function appendUniqueValueWork(
+  work: MaterializationWorkRecord[],
+  change: EffectiveObjectChange,
+  ontology: OntologyRegistry
+): void {
+  const properties = ontology.listUniqueProperties(change.ref.objectTypeId)
+  if (properties.length === 0) return
+
+  const before = change.before?.properties
+  const after = change.kind === "deleted" ? undefined : change.after.properties
+
+  for (const { propertyId, kind } of properties) {
+    const released = uniqueValueKey(kind, before?.[propertyId])
+    const claimed = uniqueValueKey(kind, after?.[propertyId])
+    if (released === claimed) continue
+
+    const sortKey = canonicalIdentitySortKey([
+      change.ref.objectTypeId,
+      change.ref.primaryId,
+      propertyId,
+    ])
+    const value = (valueKey: string): ExactUniqueValueWrite => ({
+      objectTypeId: change.ref.objectTypeId,
+      propertyId,
+      valueKey,
+      primaryId: change.ref.primaryId,
+    })
+
+    if (released !== null) {
+      work.push(planWork({ kind: "unique-value-release", value: value(released) }, sortKey))
+    }
+    if (claimed !== null) {
+      const claim = { ...value(claimed), keyKind: kind, keyVersion: UNIQUE_VALUE_KEY_VERSION }
+      work.push(planWork({ kind: "unique-value-claim", value: claim }, sortKey))
+    }
+  }
+}
+
 export function appendEffectiveLinkWork(
   items: MaterializationPlanWorkItem[],
   change: EffectiveLinkChange

package/src/materializer/projections/finish-run.ts

@@ -95,7 +95,6 @@ function resolveDeployedProjection(
   const identity = createProjectionRunMaterializationIdentity({
     resolved,
     datasetVersion: input.datasetVersion,
-    ontologyRevision: context.projectionRegistry.ontologyRevision,
   })
   return { identity, resolved }
 }

package/src/materializer/projections/replace.ts

@@ -121,7 +121,6 @@ function prepareProjectionReplacement(
   const runIdentity = createProjectionRunMaterializationIdentity({
     resolved,
     datasetVersion,
-    ontologyRevision: context.projectionRegistry.ontologyRevision,
   })
   const identity = createCommitIdentity({
     projectId: context.projectId,
@@ -306,6 +305,7 @@ async function stageOrReuseCandidate(
     execution: command.execution,
     projectionKind: command.projectionKind,
     datasetVersion: command.datasetVersion,
+    ontologyRevision: command.resolved.ontologyRevision,
     projectionRevision: command.resolved.projectionRevision,
     ownershipHash: command.resolved.ownershipHash,
     createdAt: candidate.createdAt,

package/src/materializer/projections/replacement-plan.ts

@@ -35,6 +35,7 @@ import { validateEffectiveObject } from "../effective/validate"
 import {
   appendEffectiveLinkWork,
   appendEffectiveObjectWork,
+  appendUniqueValueWork,
   classificationWork,
   eventWork,
   planWork,
@@ -143,11 +144,12 @@ function planReplacementObject(
   }
 
   if (!change) return work
-  appendObjectChangeWork(work, sortKey, change)
+  appendObjectChangeWork(context, work, sortKey, change)
   return work
 }
 
 function appendObjectChangeWork(
+  context: Pick<MaterializerContext, "ontology">,
   work: MaterializationWorkRecord[],
   sortKey: string,
   change: EffectiveObjectChange
@@ -155,6 +157,7 @@ function appendObjectChangeWork(
   const items: MaterializationPlanWorkItem[] = []
   appendEffectiveObjectWork(items, change)
   for (const item of items) work.push(planWork(item, sortKey))
+  appendUniqueValueWork(work, change, context.ontology)
   work.push(eventWork(buildObjectMaterializationEventDraft(change)))
 }
 

package/src/materializer/projections/source-materialization.ts

@@ -39,6 +39,7 @@ export async function stageProjectionMaterialization(
     readonly execution: ProjectionExecution
     readonly projectionKind: "object" | "link"
     readonly datasetVersion: PinnedDatasetVersion
+    readonly ontologyRevision: string
     readonly projectionRevision: string
     readonly ownershipHash: string
     readonly createdAt: string
@@ -60,7 +61,7 @@ export async function stageProjectionMaterialization(
     datasetVersion: input.datasetVersion,
     projectionRevision: input.projectionRevision,
     ownershipHash: input.ownershipHash,
-    ontologyRevision: context.projectionRegistry.ontologyRevision,
+    ontologyRevision: input.ontologyRevision,
     createdAt: input.createdAt,
     ...(input.base ? { base: input.base } : {}),
   })

package/src/materializer/shared/normalize.ts

@@ -26,6 +26,7 @@ import {
   telemetryPointKey,
 } from "../../materialization/refs"
 import { parseDatasetTimestamp } from "../../projections/timestamp"
+import type { UniqueValueRef } from "../../storage/ontology"
 
 export function normalizeJsonProperties(
   properties: Readonly<Record<string, unknown>>,
@@ -157,6 +158,24 @@ function normalizeOperation(operation: OntologyEditOperation): OntologyEditOpera
   throw new MaterializationValidationError("Unknown ontology edit operation kind.")
 }
 
+function normalizeUnclaimedValues(values: readonly UniqueValueRef[]): readonly UniqueValueRef[] {
+  const normalized = values.map((value) => {
+    if (typeof value.valueKey !== "string") {
+      throw new MaterializationValidationError("Expected unclaimed value key must be a string.")
+    }
+    return Object.freeze({
+      objectTypeId: normalizeNonblank(value.objectTypeId, "Expected unclaimed value type id"),
+      propertyId: normalizeNonblank(value.propertyId, "Expected unclaimed value property id"),
+      valueKey: value.valueKey,
+    })
+  })
+  return deduplicateExpectations(
+    normalized,
+    (value) => JSON.stringify([value.objectTypeId, value.propertyId, value.valueKey]),
+    "Expected unclaimed values"
+  )
+}
+
 function deduplicateExpectations<T>(
   values: readonly T[],
   keyOf: (value: T) => string,
@@ -178,6 +197,16 @@ function deduplicateExpectations<T>(
   )
 }
 
+function normalizeExpectedObjects(
+  values: readonly ExpectedObjectRevision[]
+): readonly ExpectedObjectRevision[] {
+  return deduplicateExpectations(
+    values.map(normalizeExpectedObject),
+    (value) => objectRefKey(value.ref),
+    "Expected objects"
+  )
+}
+
 function normalizeExpectedObject(value: ExpectedObjectRevision): ExpectedObjectRevision {
   const ref = normalizeObjectRef(value.ref)
   if (!value.exists) return Object.freeze({ ref, exists: false })
@@ -281,6 +310,9 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
       ...(input.operationGroups !== undefined
         ? { operationGroups: normalizeOperationGroups(input.operationGroups, operationIds) }
         : {}),
+      ...(input.expectedObjects !== undefined
+        ? { expectedObjects: normalizeExpectedObjects(input.expectedObjects) }
+        : {}),
     })
   }
 
@@ -290,7 +322,6 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
     )
   }
   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)
 
@@ -300,11 +331,7 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
       ? {}
       : { vectorWrites: structuredClone(input.vectorWrites) }),
     operations: Object.freeze(operations),
-    expectedObjects: deduplicateExpectations(
-      expectedObjects,
-      (value) => objectRefKey(value.ref),
-      "Expected objects"
-    ),
+    expectedObjects: normalizeExpectedObjects(input.expectedObjects),
     expectedLinks: deduplicateExpectations(
       expectedLinks,
       (value) => linkRefKey(value.ref),
@@ -315,6 +342,10 @@ export function normalizeOntologyEditCommit(input: OntologyEditCommit): Ontology
       (value) => linkScopeKey(value.source, value.linkId),
       "Expected link scopes"
     ),
+    // Only when present, so commits without them keep the intent they hashed to.
+    ...(input.expectedUnclaimedValues?.length
+      ? { expectedUnclaimedValues: normalizeUnclaimedValues(input.expectedUnclaimedValues) }
+      : {}),
   }
 
   if (input.source.kind === "action") {

package/src/materializer/shared/projection-run.ts

@@ -25,7 +25,6 @@ interface ProjectionRunIdentityInput<
 > {
   readonly resolved: ResolvedProjection<TDefinition>
   readonly datasetVersion: PinnedDatasetVersion
-  readonly ontologyRevision: string
 }
 
 export function createProjectionRunMaterializationIdentity(
@@ -43,7 +42,7 @@ export function createProjectionRunMaterializationIdentity(
   const base = {
     projectionId: input.resolved.projectionId,
     datasetVersion: input.datasetVersion,
-    ontologyRevision: input.ontologyRevision,
+    ontologyRevision: input.resolved.ontologyRevision,
     projectionRevision: input.resolved.projectionRevision,
     ownershipHash: input.resolved.ownershipHash,
   }

package/src/materializer/telemetry/append.ts

@@ -91,18 +91,11 @@ function prepareTelemetryAppend(
   })
   const inputPointCount = telemetryInputPointCount(input, rawInputPointCount)
 
-  const ontologyRevision = context.projectionRegistry.ontologyRevision
   const execution = prepareMaterializerExecution(context.projectId, raw.scope)
   if (input.source.kind === "runtime") {
-    return {
-      ...prepareRuntimeTelemetry(context, input, input.source, inputPointCount, ontologyRevision),
-      execution,
-    }
-  }
-  return {
-    ...prepareProjectionTelemetry(context, input, input.source, inputPointCount, ontologyRevision),
-    execution,
+    return { ...prepareRuntimeTelemetry(context, input, input.source, inputPointCount), execution }
   }
+  return { ...prepareProjectionTelemetry(context, input, input.source, inputPointCount), execution }
 }
 
 function telemetryInputPointCount(
@@ -114,11 +107,10 @@ function telemetryInputPointCount(
 }
 
 function prepareRuntimeTelemetry(
-  context: Pick<MaterializerContext, "projectId" | "clock">,
+  context: Pick<MaterializerContext, "projectId" | "projectionRegistry" | "clock">,
   input: NormalizedTelemetryAppend,
   source: RuntimeTelemetrySource,
-  inputPointCount: number,
-  ontologyRevision: string
+  inputPointCount: number
 ): Omit<PreparedRuntimeTelemetry, "execution"> {
   const identity = createTimedCommitIdentity({
     projectId: context.projectId,
@@ -126,15 +118,21 @@ function prepareRuntimeTelemetry(
     normalizedCallerIntent: input,
     now: context.clock(),
   })
-  return { kind: "runtime", input, source, inputPointCount, ontologyRevision, identity }
+  return {
+    kind: "runtime",
+    input,
+    source,
+    inputPointCount,
+    ontologyRevision: context.projectionRegistry.ontologyRevision,
+    identity,
+  }
 }
 
 function prepareProjectionTelemetry(
   context: Pick<MaterializerContext, "projectId" | "projectionRegistry" | "clock">,
   input: NormalizedTelemetryAppend,
   source: ProjectionTelemetrySource,
-  inputPointCount: number,
-  ontologyRevision: string
+  inputPointCount: number
 ): Omit<PreparedProjectionTelemetry, "execution"> {
   const resolvedProjection = context.projectionRegistry.resolveTelemetry(
     source.projection.projectionId
@@ -146,7 +144,6 @@ function prepareProjectionTelemetry(
   const runIdentity = createProjectionRunMaterializationIdentity({
     resolved: resolvedProjection,
     datasetVersion: source.datasetVersion,
-    ontologyRevision,
   })
   const identity = createTimedCommitIdentity({
     projectId: context.projectId,
@@ -160,7 +157,7 @@ function prepareProjectionTelemetry(
     input,
     source,
     inputPointCount,
-    ontologyRevision,
+    ontologyRevision: runIdentity.ontologyRevision,
     identity,
     resolvedProjection,
     runIdentity,

package/src/materializer/telemetry/plan.ts

@@ -31,6 +31,7 @@ import { validateEffectiveObject } from "../effective/validate"
 import { stageWorkBounded } from "../execution/work-executor"
 import {
   appendEffectiveObjectWork,
+  appendUniqueValueWork,
   classificationWork,
   eventWork,
   planWork,
@@ -319,6 +320,7 @@ async function stageTelemetryObjectPlan(
     const items: MaterializationPlanWorkItem[] = []
     appendEffectiveObjectWork(items, change)
     work.push(...items.map((item) => planWork(item, sortKey)))
+    appendUniqueValueWork(work, change, context.ontology)
     work.push(eventWork(buildObjectMaterializationEventDraft(change)))
   }
   await stageWorkBounded(context, storage, session, work)

package/src/models/audio/catalog.ts

@@ -1,6 +1,6 @@
 import type { ModelRef } from "../catalog"
 import { indexModelBindings } from "../catalog-index"
-import type { TranscriptionModel } from "./types"
+import type { SpeechModel, TranscriptionModel } from "./types"
 
 export interface TranscriptionModelEntry extends ModelRef {
   readonly model: TranscriptionModel
@@ -12,13 +12,26 @@ export interface TranscriptionModelCatalog {
   getByRef(ref: ModelRef): TranscriptionModelEntry | null
 }
 
+export interface SpeechModelEntry extends ModelRef {
+  readonly model: SpeechModel
+}
+
+export interface SpeechModelCatalog {
+  readonly default: SpeechModelEntry
+  list(): readonly SpeechModelEntry[]
+  getByRef(ref: ModelRef): SpeechModelEntry | null
+}
+
 export interface AudioModelCatalog {
   readonly transcription?: TranscriptionModelCatalog
+  readonly speech?: SpeechModelCatalog
 }
 
 export interface AudioModelCatalogInput {
   /** Ordered; the first entry is the default transcriber. */
   readonly transcription?: readonly TranscriptionModel[]
+  /** Ordered; the first entry is the default speech model. */
+  readonly speech?: readonly SpeechModel[]
 }
 
 export function createAudioCatalog(
@@ -29,24 +42,41 @@ export function createAudioCatalog(
     !input ||
     typeof input !== "object" ||
     Array.isArray(input) ||
-    !Array.isArray(input.transcription)
+    (input.transcription === undefined && input.speech === undefined)
   ) {
-    throw new TypeError(
-      "[Sixb] models.audio.transcription must be a nonempty array of transcription models."
-    )
+    throw new TypeError("[Sixb] models.audio must configure transcription or speech models.")
   }
 
-  const index = indexModelBindings(
+  const transcription = familyCatalog(
     input.transcription,
-    "audio.transcription",
+    "transcription",
     assertTranscriptionModel
   )
+  const speech = familyCatalog(input.speech, "speech", assertSpeechModel)
+  return Object.freeze({
+    ...(transcription === undefined ? {} : { transcription }),
+    ...(speech === undefined ? {} : { speech }),
+  })
+}
+
+function familyCatalog<TModel extends { readonly providerId: string; readonly modelId: string }>(
+  models: readonly TModel[] | undefined,
+  family: "transcription" | "speech",
+  validate: (model: TModel) => void
+) {
+  if (models === undefined) return undefined
+  if (!Array.isArray(models)) {
+    throw new TypeError(
+      `[Sixb] models.audio.${family} must be a nonempty array of ${family} models.`
+    )
+  }
+
+  const index = indexModelBindings(models, `audio.${family}`, validate)
   const [defaultEntry] = index.list()
   if (!defaultEntry) {
-    throw new TypeError("[Sixb] models.audio.transcription must contain at least one model.")
+    throw new TypeError(`[Sixb] models.audio.${family} must contain at least one model.`)
   }
-
-  return Object.freeze({ transcription: Object.freeze({ ...index, default: defaultEntry }) })
+  return Object.freeze({ ...index, default: defaultEntry })
 }
 
 export function assertTranscriptionModel(model: unknown): asserts model is TranscriptionModel {
@@ -88,3 +118,52 @@ function invalidModel(): TypeError {
     "[SixbModels] Invalid transcription model identity, definition or input limits."
   )
 }
+
+export function assertSpeechModel(model: unknown): asserts model is SpeechModel {
+  const candidate = model as Partial<SpeechModel> | null
+  const definition = candidate?.definition
+  if (
+    !candidate ||
+    !isValidId(candidate.providerId) ||
+    !isValidId(candidate.modelId) ||
+    typeof candidate.speak !== "function" ||
+    definition?.kind !== "speech" ||
+    definition.providerId !== candidate.providerId ||
+    definition.modelId !== candidate.modelId
+  ) {
+    throw invalidSpeechModel("identity")
+  }
+
+  const limit = definition.maxInputCharacters
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+    throw invalidSpeechModel("maxInputCharacters")
+  }
+  if (!isOptionalList(definition.voices)) throw invalidSpeechModel("voices")
+  if (
+    !isOptionalList(definition.outputMediaTypes) ||
+    definition.outputMediaTypes?.some((type) => !/^audio\/[a-z0-9.+-]+$/.test(type))
+  ) {
+    throw invalidSpeechModel("outputMediaTypes")
+  }
+  if (definition.instructions !== undefined && typeof definition.instructions !== "boolean") {
+    throw invalidSpeechModel("instructions")
+  }
+  if (
+    candidate.defaultVoice !== undefined &&
+    (!isValidId(candidate.defaultVoice) ||
+      (definition.voices !== undefined && !definition.voices.includes(candidate.defaultVoice)))
+  ) {
+    throw invalidSpeechModel("defaultVoice")
+  }
+}
+
+function isOptionalList(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (Array.isArray(value) && value.length > 0 && value.every((entry) => isValidId(entry)))
+  )
+}
+
+function invalidSpeechModel(field: string): TypeError {
+  return new TypeError(`[SixbModels] Invalid speech model ${field}.`)
+}

package/src/models/audio/errors.ts

@@ -1,5 +1,5 @@
 import { ModelProviderError } from "../errors"
-import type { TranscriptionModelResponseMetadata } from "./types"
+import type { SpeechModelResponseMetadata, TranscriptionModelResponseMetadata } from "./types"
 
 /** Retains billing metadata even when the provider returns an invalid transcript. */
 export class TranscriptionModelResponseError extends ModelProviderError {
@@ -17,3 +17,20 @@ export class TranscriptionModelResponseError extends ModelProviderError {
     })
   }
 }
+
+/** Retains billing metadata even when the provider returns invalid audio. */
+export class SpeechModelResponseError extends ModelProviderError {
+  constructor(
+    message: string,
+    providerId: string,
+    modelId: string,
+    readonly metadata: SpeechModelResponseMetadata,
+    options?: ErrorOptions
+  ) {
+    super(message, providerId, modelId, {
+      ...options,
+      code: "invalid_speech_response",
+      retryable: false,
+    })
+  }
+}

package/src/models/audio/runtime.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto"
-import { assertProviderAccess } from "../../authorization"
+import { assertModelAccess } from "../../authorization"
 import type { BlobStorage } from "../../blob-storage/types"
 import type { ExecutionContext } from "../../execution"
 import type { SixbRuntimeContext } from "../../runtime/types"
@@ -7,10 +7,11 @@ import type { ModelCatalog } from "../catalog"
 import type { ModelCallEndEvent } from "../events"
 import type { AiModelCallRecorder } from "../execution/model-call-recorder"
 import type { ModelExecutionSession } from "../execution/session"
+import { prepareModelInputFile, readModelInputFile } from "../input-file"
 import { estimateModelCall, type ModelMoney } from "../pricing"
 import { assertTranscriptionModel } from "./catalog"
 import { TranscriptionModelResponseError } from "./errors"
-import { prepareTranscriptionFile, readTranscriptionFile } from "./file"
+import { createSpeak } from "./speech"
 import type {
   AudioModelsRuntime,
   TranscriptionModel,
@@ -26,10 +27,11 @@ export function createAudioRuntime(
   blobs: BlobStorage | undefined
 ): AudioModelsRuntime {
   return {
+    speak: createSpeak(runtime, execution, catalog, session, blobs),
     async transcribe(input) {
-      assertProviderAccess(runtime, execution, "models.audio.transcribe")
+      assertModelAccess(runtime, execution, "models.audio.transcribe")
 
-      const { audio, mediaType } = prepareTranscriptionFile(input.audio)
+      const { file: audio, mediaType } = prepareModelInputFile(input.audio, "audio")
       if (!blobs) {
         throw new Error("[SixbModels] Transcription requires blob storage.")
       }
@@ -54,7 +56,7 @@ export function createAudioRuntime(
       assertFileSupport(model, audio.sizeBytes, mediaType)
 
       signal.throwIfAborted()
-      const bytes = await readTranscriptionFile(blobs, audio, signal)
+      const bytes = await readModelInputFile(blobs, audio, signal)
       accounting.assertHealthy()
 
       const reservationCost = estimateReservationCost(model, bytes.byteLength, mediaType)
@@ -109,16 +111,11 @@ function selectModel(
   catalog: ModelCatalog | undefined,
   requested: TranscriptionModel | undefined
 ): TranscriptionModel {
-  if (!catalog && requested) return requested
-
-  const transcribers = catalog?.audio?.transcription
-  const selected = requested
-    ? transcribers?.getByRef({ provider: requested.providerId, modelId: requested.modelId })?.model
-    : transcribers?.default.model
-
+  // A model the caller passes runs as given, listed or not; the catalog supplies the default.
+  const selected = requested ?? catalog?.audio?.transcription?.default.model
   if (!selected) {
     throw new Error(
-      "[SixbModels] Configure the selected model in models.audio.transcription, or supply a model when no catalog is configured."
+      "[SixbModels] Configure models.audio.transcription in createSixb() or supply a model to transcribe()."
     )
   }