@sixb/core 0.1.16 → 0.1.17

package/src/materializer/shared/batching.ts

@@ -6,6 +6,11 @@ export interface MaterializationBatching {
   readonly statePageRows: number
   readonly planChunkRows: number
   readonly planChunkBytes: number
+  /**
+   * Stale identities a projection commit plans again inside its own transaction. A refresh that
+   * finds more gives them back to a round outside it.
+   */
+  readonly transactionReplanRows: number
 }
 
 export const DEFAULT_MATERIALIZATION_BATCHING: MaterializationBatching = Object.freeze({
@@ -17,6 +22,8 @@ export const DEFAULT_MATERIALIZATION_BATCHING: MaterializationBatching = Object.
   statePageRows: 1_000,
   planChunkRows: 1_000,
   planChunkBytes: 4 * 1024 * 1024,
+  // One state page: a few hundred milliseconds of planning while the commit holds its locks.
+  transactionReplanRows: 1_000,
 })
 
 /** Internal test/provider override. Application configuration never exposes these chunk targets. */

package/src/materializer/telemetry/append.ts

@@ -32,7 +32,7 @@ import {
   type MaterializerExecution,
   prepareMaterializerExecution,
 } from "../execution/scope"
-import { drainStagedEvents, drainStagedWork } from "../execution/work-executor"
+import { applyStagedWork } from "../execution/work-executor"
 import type { MaterializerCommand } from "../materializer"
 import {
   createProjectionTelemetryIdempotencyKey,
@@ -397,20 +397,9 @@ async function executeTelemetryTransaction(
     storage.ontology.materializations,
     session,
     command.input,
-    command.identity,
-    origin,
-    {
-      correlationId: command.execution.correlationId,
-      attribution: command.execution.attribution,
-    }
-  )
-  await drainStagedWork(context, storage, session)
-  const eventCount = await drainStagedEvents(
-    context,
-    storage.ontology.materializations,
-    session,
     command.identity
   )
+  const eventCount = await applyStagedWork(context, storage, session)
   const result: TelemetryCommitResult = {
     kind: "telemetry",
     commitId: command.identity.commitId,
@@ -475,7 +464,6 @@ function telemetryCommit(
     requestHash: command.identity.requestHash,
     executionId: command.execution.executionId,
     origin,
-    ...command.execution.attribution,
     ontologyRevision: command.ontologyRevision,
     intent: telemetryCommitIntent(command),
     committedAt: command.identity.committedAt,

package/src/materializer/telemetry/plan.ts

@@ -1,7 +1,6 @@
 import { stableJsonStringify } from "../../json"
 import { MaterializationObjectNotFoundError } from "../../materialization/errors"
 import type {
-  OntologyMaterializationOrigin,
   OntologyObjectRef,
   TelemetryAppend,
   TelemetryPointWrite,
@@ -29,7 +28,6 @@ import {
 import { diffEffectiveObject } from "../effective/diff"
 import { loadState, oneStateRequest } from "../effective/load-state"
 import { validateEffectiveObject } from "../effective/validate"
-import type { MaterializerAttribution } from "../execution/scope"
 import { stageWorkBounded } from "../execution/work-executor"
 import {
   appendEffectiveObjectWork,
@@ -62,13 +60,6 @@ interface TelemetryObjectGroup {
 interface TelemetryPlanContext {
   readonly input: TelemetryAppend
   readonly identity: TimedCommitIdentity
-  readonly origin: OntologyMaterializationOrigin
-  readonly event: TelemetryEventContext
-}
-
-interface TelemetryEventContext {
-  readonly correlationId: string
-  readonly attribution: MaterializerAttribution
 }
 
 export async function planTelemetryAppend(
@@ -76,12 +67,10 @@ export async function planTelemetryAppend(
   storage: OntologyMaterializationStorage,
   session: MaterializationSession,
   input: TelemetryAppend,
-  identity: TimedCommitIdentity,
-  origin: OntologyMaterializationOrigin,
-  event: TelemetryEventContext
+  identity: TimedCommitIdentity
 ): Promise<TelemetryPlanCounts> {
   const counts = emptyTelemetryCounts()
-  const planContext = { input, identity, origin, event }
+  const planContext = { input, identity }
   const objects = await loadTelemetryObjects(context, storage, session, input.points)
   const existingPoints = await loadExistingPoints(context, storage, session, input.points)
   for (const group of telemetryObjectGroups(input.points)) {
@@ -137,7 +126,7 @@ async function planTelemetryObject(
   for (let start = group.start; start < group.end; start += context.batching.statePageRows) {
     const end = Math.min(group.end, start + context.batching.statePageRows)
     const points = planContext.input.points.slice(start, end)
-    const work = planTelemetryChunk(context, planContext, points, existingPoints, latest, counts)
+    const work = planTelemetryChunk(planContext, points, existingPoints, latest, counts)
     await stageWorkBounded(context, storage, session, work)
   }
 
@@ -164,7 +153,6 @@ async function loadTelemetryObjects(
 }
 
 function planTelemetryChunk(
-  context: Pick<MaterializerContext, "projectId">,
   planContext: TelemetryPlanContext,
   points: readonly TelemetryPointWrite[],
   existingPoints: ReadonlyMap<string, StoredTelemetryPoint>,
@@ -173,7 +161,7 @@ function planTelemetryChunk(
 ): MaterializationWorkRecord[] {
   const work: MaterializationWorkRecord[] = []
   for (const point of points) {
-    work.push(...planTelemetryPoint(context, planContext, point, existingPoints, latest, counts))
+    work.push(...planTelemetryPoint(planContext, point, existingPoints, latest, counts))
   }
   return work
 }
@@ -205,7 +193,6 @@ async function loadExistingPoints(
 }
 
 function planTelemetryPoint(
-  context: Pick<MaterializerContext, "projectId">,
   planContext: TelemetryPlanContext,
   point: TelemetryPointWrite,
   existingPoints: ReadonlyMap<string, StoredTelemetryPoint>,
@@ -223,7 +210,7 @@ function planTelemetryPoint(
   } else {
     countTelemetryPointChange(counts, existing)
     work.push(planWork(telemetryPointUpsert(point, existing, planContext.identity), sortKey))
-    work.push(eventWork(buildTelemetryEvent(context, planContext, point)))
+    work.push(eventWork(buildTelemetryMaterializationEventDraft(point)))
   }
 
   updateLatestPoint(latest, point, existing, unchanged, planContext.identity)
@@ -282,15 +269,6 @@ function storedTelemetryPointWithUnit<T extends object>(
   return { ...point, unit }
 }
 
-function buildTelemetryEvent(
-  context: Pick<MaterializerContext, "projectId">,
-  planContext: TelemetryPlanContext,
-  point: TelemetryPointWrite
-) {
-  const eventContext = telemetryEventContext(context, planContext)
-  return buildTelemetryMaterializationEventDraft({ ...eventContext, point })
-}
-
 function updateLatestPoint(
   latest: Map<string, StoredTelemetryPoint>,
   point: TelemetryPointWrite,
@@ -341,26 +319,11 @@ async function stageTelemetryObjectPlan(
     const items: MaterializationPlanWorkItem[] = []
     appendEffectiveObjectWork(items, change)
     work.push(...items.map((item) => planWork(item, sortKey)))
-    const eventContext = telemetryEventContext(context, planContext)
-    work.push(eventWork(buildObjectMaterializationEventDraft({ ...eventContext, change })))
+    work.push(eventWork(buildObjectMaterializationEventDraft(change)))
   }
   await stageWorkBounded(context, storage, session, work)
 }
 
-function telemetryEventContext(
-  context: Pick<MaterializerContext, "projectId">,
-  planContext: TelemetryPlanContext
-) {
-  return {
-    projectId: context.projectId,
-    commitId: planContext.identity.commitId,
-    committedAt: planContext.identity.committedAt,
-    origin: planContext.origin,
-    correlationId: planContext.event.correlationId,
-    attribution: planContext.event.attribution,
-  }
-}
-
 function emptyTelemetryCounts(): MutableTelemetryPlanCounts {
   return {
     pointsCreated: 0,

package/src/models/audio/catalog.ts

@@ -0,0 +1,90 @@
+import type { ModelRef } from "../catalog"
+import { indexModelBindings } from "../catalog-index"
+import type { TranscriptionModel } from "./types"
+
+export interface TranscriptionModelEntry extends ModelRef {
+  readonly model: TranscriptionModel
+}
+
+export interface TranscriptionModelCatalog {
+  readonly default: TranscriptionModelEntry
+  list(): readonly TranscriptionModelEntry[]
+  getByRef(ref: ModelRef): TranscriptionModelEntry | null
+}
+
+export interface AudioModelCatalog {
+  readonly transcription?: TranscriptionModelCatalog
+}
+
+export interface AudioModelCatalogInput {
+  /** Ordered; the first entry is the default transcriber. */
+  readonly transcription?: readonly TranscriptionModel[]
+}
+
+export function createAudioCatalog(
+  input: AudioModelCatalogInput | undefined
+): AudioModelCatalog | undefined {
+  if (input === undefined) return undefined
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    !Array.isArray(input.transcription)
+  ) {
+    throw new TypeError(
+      "[Sixb] models.audio.transcription must be a nonempty array of transcription models."
+    )
+  }
+
+  const index = indexModelBindings(
+    input.transcription,
+    "audio.transcription",
+    assertTranscriptionModel
+  )
+  const [defaultEntry] = index.list()
+  if (!defaultEntry) {
+    throw new TypeError("[Sixb] models.audio.transcription must contain at least one model.")
+  }
+
+  return Object.freeze({ transcription: Object.freeze({ ...index, default: defaultEntry }) })
+}
+
+export function assertTranscriptionModel(model: unknown): asserts model is TranscriptionModel {
+  const candidate = model as Partial<TranscriptionModel> | null
+  const definition = candidate?.definition
+  if (
+    !candidate ||
+    !isValidId(candidate.providerId) ||
+    !isValidId(candidate.modelId) ||
+    typeof candidate.transcribe !== "function" ||
+    definition?.kind !== "transcription" ||
+    definition.providerId !== candidate.providerId ||
+    definition.modelId !== candidate.modelId
+  ) {
+    throw invalidModel()
+  }
+
+  if (!Number.isSafeInteger(definition.maxInputBytes) || definition.maxInputBytes <= 0) {
+    throw invalidModel()
+  }
+
+  const mediaTypes = definition.mediaTypes
+  if (
+    mediaTypes !== undefined &&
+    (!Array.isArray(mediaTypes) ||
+      mediaTypes.length === 0 ||
+      !mediaTypes.every((type) => typeof type === "string" && /^audio\/[a-z0-9.+-]+$/.test(type)))
+  ) {
+    throw invalidModel()
+  }
+}
+
+function isValidId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.trim() === value
+}
+
+function invalidModel(): TypeError {
+  return new TypeError(
+    "[SixbModels] Invalid transcription model identity, definition or input limits."
+  )
+}

package/src/models/audio/errors.ts

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

package/src/models/audio/file.ts

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto"
+import type { BlobStorage, FileRef } from "../../blob-storage/types"
+import { isFileRef } from "../../blob-storage/validation"
+
+/** Snapshot caller-owned metadata before model resolution or storage introduces an await. */
+export function prepareTranscriptionFile(input: FileRef): { audio: FileRef; mediaType: string } {
+  if (!isFileRef(input) || !Number.isSafeInteger(input.sizeBytes) || input.sizeBytes <= 0) {
+    throw new TypeError("[SixbModels] Transcription requires a nonempty FileRef.")
+  }
+
+  const audio = { ...input }
+  const mediaType = audio.mediaType?.split(";", 1)[0]?.trim().toLowerCase()
+  if (!mediaType || !/^audio\/[a-z0-9.+-]+$/.test(mediaType)) {
+    throw new TypeError("[SixbModels] Audio FileRef must declare an audio mediaType.")
+  }
+
+  return { audio, mediaType }
+}
+
+/** Read an already validated reference, bounded by its verified size and the model's limit. */
+export async function readTranscriptionFile(
+  storage: BlobStorage,
+  file: FileRef,
+  signal: AbortSignal
+): Promise<Uint8Array> {
+  const info = await storage.stat(file.blobId)
+  signal.throwIfAborted()
+  if (
+    !info ||
+    info.blobId !== file.blobId ||
+    info.digest !== file.digest ||
+    info.sizeBytes !== file.sizeBytes
+  ) {
+    throw new Error("[SixbModels] Audio reference does not match the stored file.")
+  }
+
+  const stream = await storage.open(file.blobId)
+  const reader = stream.getReader()
+  const cancel = () => {
+    void reader.cancel(signal.reason).catch(() => undefined)
+  }
+  signal.addEventListener("abort", cancel, { once: true })
+
+  let complete = false
+  try {
+    signal.throwIfAborted()
+
+    const bytes = new Uint8Array(file.sizeBytes)
+    const hash = createHash("sha256")
+    let offset = 0
+
+    while (true) {
+      const { value, done } = await reader.read()
+      signal.throwIfAborted()
+      if (done) break
+      if (!(value instanceof Uint8Array) || value.byteLength > bytes.byteLength - offset) {
+        throw new Error("[SixbModels] Audio stream exceeds its declared size.")
+      }
+
+      bytes.set(value, offset)
+      hash.update(value)
+      offset += value.byteLength
+    }
+
+    if (offset !== file.sizeBytes || `sha256:${hash.digest("hex")}` !== file.digest) {
+      throw new Error("[SixbModels] Audio stream does not match its content-addressed reference.")
+    }
+
+    complete = true
+    return bytes
+  } finally {
+    signal.removeEventListener("abort", cancel)
+    if (!complete) {
+      void reader.cancel().catch(() => undefined)
+    }
+    reader.releaseLock()
+  }
+}

package/src/models/audio/runtime.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto"
+import { assertProviderAccess } from "../../authorization"
+import type { BlobStorage } from "../../blob-storage/types"
+import type { ExecutionContext } from "../../execution"
+import type { SixbRuntimeContext } from "../../runtime/types"
+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 { estimateModelCall, type ModelMoney } from "../pricing"
+import { assertTranscriptionModel } from "./catalog"
+import { TranscriptionModelResponseError } from "./errors"
+import { prepareTranscriptionFile, readTranscriptionFile } from "./file"
+import type {
+  AudioModelsRuntime,
+  TranscriptionModel,
+  TranscriptionModelResponseMetadata,
+  TranscriptionModelResult,
+} from "./types"
+
+export function createAudioRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  catalog: ModelCatalog | undefined,
+  session: ModelExecutionSession,
+  blobs: BlobStorage | undefined
+): AudioModelsRuntime {
+  return {
+    async transcribe(input) {
+      assertProviderAccess(runtime, execution, "models.audio.transcribe")
+
+      const { audio, mediaType } = prepareTranscriptionFile(input.audio)
+      if (!blobs) {
+        throw new Error("[SixbModels] Transcription requires blob storage.")
+      }
+
+      const signal = session.signal(input.signal)
+      signal.throwIfAborted()
+
+      const binding = selectModel(catalog, input.model)
+      assertTranscriptionModel(binding)
+      assertFileSupport(binding, audio.sizeBytes, mediaType)
+
+      const accounting = await session.accounting()
+      accounting.assertHealthy()
+
+      const model = binding.resolve ? await binding.resolve() : binding
+      assertTranscriptionModel(model)
+      if (model.providerId !== binding.providerId || model.modelId !== binding.modelId) {
+        throw new TypeError(
+          "[SixbModels] Resolved transcription model identity does not match the selected model."
+        )
+      }
+      assertFileSupport(model, audio.sizeBytes, mediaType)
+
+      signal.throwIfAborted()
+      const bytes = await readTranscriptionFile(blobs, audio, signal)
+      accounting.assertHealthy()
+
+      const reservationCost = estimateReservationCost(model, bytes.byteLength, mediaType)
+      const callId = `call_${randomUUID()}`
+      await accounting.admitCall({
+        callId,
+        providerId: model.providerId,
+        modelId: model.modelId,
+        modelKind: "transcription",
+        inputTokens: { status: "unavailable", reason: "nonTextInput" },
+        outputTokenAllowance: 0,
+        reservationCost,
+      })
+
+      let result: TranscriptionModelResult
+      try {
+        signal.throwIfAborted()
+        result = await model.transcribe({ audio: bytes, mediaType, signal })
+      } catch (error) {
+        await recordTranscription(
+          accounting,
+          model,
+          callId,
+          error instanceof TranscriptionModelResponseError ? error.metadata : {}
+        )
+        throw error
+      }
+
+      // A completed, billable reply must survive cancellation and transcript validation failures.
+      const event = await recordTranscription(accounting, model, callId, result ?? {})
+      signal.throwIfAborted()
+      if (typeof result?.output?.text !== "string") {
+        throw new TranscriptionModelResponseError(
+          "[SixbModels] Invalid transcription response.",
+          model.providerId,
+          model.modelId,
+          result ?? {}
+        )
+      }
+
+      return {
+        output: { text: result.output.text },
+        usage: event.usage,
+        cost: event.cost,
+        callId,
+      }
+    },
+  }
+}
+
+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
+
+  if (!selected) {
+    throw new Error(
+      "[SixbModels] Configure the selected model in models.audio.transcription, or supply a model when no catalog is configured."
+    )
+  }
+
+  return selected
+}
+
+function assertFileSupport(model: TranscriptionModel, sizeBytes: number, mediaType: string): void {
+  if (sizeBytes > model.definition.maxInputBytes) {
+    throw new RangeError(
+      `[SixbModels] Audio exceeds the model's ${model.definition.maxInputBytes}-byte input limit.`
+    )
+  }
+  if (model.definition.mediaTypes && !model.definition.mediaTypes.includes(mediaType)) {
+    throw new TypeError(
+      `[SixbModels] Audio media type '${mediaType}' is not supported by the selected model.`
+    )
+  }
+}
+
+function estimateReservationCost(
+  model: TranscriptionModel,
+  sizeBytes: number,
+  mediaType: string
+): ModelMoney | undefined {
+  try {
+    return model.costEstimator?.estimateReservation?.({ sizeBytes, mediaType })
+  } catch {
+    // Optional pricing cannot bypass an enforced budget: admission fails closed without it.
+    return undefined
+  }
+}
+
+async function recordTranscription(
+  accounting: AiModelCallRecorder,
+  model: TranscriptionModel,
+  callId: string,
+  metadata: TranscriptionModelResponseMetadata
+): Promise<ModelCallEndEvent> {
+  const usage = metadata.usage ?? {}
+  const estimate = estimateModelCall(model, {
+    usage,
+    route: metadata.route,
+    responseModelId: metadata.responseModelId,
+  })
+  const event: ModelCallEndEvent = {
+    callId,
+    modelKind: "transcription",
+    providerId: model.providerId,
+    modelId: model.modelId,
+    responseId: metadata.providerIds?.responseId ?? callId,
+    providerIds: metadata.providerIds,
+    responseModelId: metadata.responseModelId,
+    usage,
+    cost: metadata.reportedCost ? { status: "reported", ...metadata.reportedCost } : estimate,
+    ...(metadata.reportedCost ? { estimate } : {}),
+    route: metadata.route,
+  }
+
+  await accounting.onModelCallEnd(event)
+  return event
+}

package/src/models/audio/types.ts

@@ -0,0 +1,69 @@
+import type { FileRef } from "../../blob-storage/types"
+import type { ModelDefinition } from "../definitions"
+import type { ModelProviderIds, ModelRoute, ModelUsage } from "../events"
+import type { ModelCallCost, ModelCostEstimator, ModelMoney, ModelReportedCost } from "../pricing"
+
+export interface TranscriptionModelDefinition extends ModelDefinition {
+  readonly kind: "transcription"
+  /** Bounds memory consumption before a file is opened. Providers may impose lower limits. */
+  readonly maxInputBytes: number
+  /** Omitted when the provider does not publish a reliable format list. */
+  readonly mediaTypes?: readonly string[]
+}
+
+export interface TranscriptionModelRequest {
+  readonly audio: Uint8Array
+  readonly mediaType: string
+  readonly signal?: AbortSignal
+}
+
+export interface TranscriptionOutput {
+  readonly text: string
+}
+
+export interface TranscriptionModelResponseMetadata {
+  readonly usage?: ModelUsage
+  readonly providerIds?: ModelProviderIds
+  readonly responseModelId?: string
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: ModelRoute
+}
+
+export interface TranscriptionModelResult extends TranscriptionModelResponseMetadata {
+  readonly output: TranscriptionOutput
+}
+
+export interface TranscriptionCostEstimator extends Pick<ModelCostEstimator, "estimate"> {
+  /** Return undefined if the request cannot be priced safely before inference. */
+  estimateReservation?(input: {
+    readonly sizeBytes: number
+    readonly mediaType: string
+  }): ModelMoney | undefined
+}
+
+/** Provider binding. Resolving it may fetch metadata, but must never perform inference. */
+export interface TranscriptionModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: TranscriptionModelDefinition
+  readonly costEstimator?: TranscriptionCostEstimator
+  resolve?(): Promise<TranscriptionModel>
+  transcribe(request: TranscriptionModelRequest): Promise<TranscriptionModelResult>
+}
+
+export interface AudioTranscribeInput {
+  readonly audio: FileRef
+  readonly model?: TranscriptionModel
+  readonly signal?: AbortSignal
+}
+
+export interface AudioTranscribeResult {
+  readonly output: TranscriptionOutput
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+  readonly callId: string
+}
+
+export interface AudioModelsRuntime {
+  transcribe(input: AudioTranscribeInput): Promise<AudioTranscribeResult>
+}