@sixb/core 0.1.8 → 0.1.10

package/src/materializer/projections/replace.ts

@@ -10,6 +10,8 @@ import type {
   ProjectionCommitResult,
   ProjectionExecution,
   ProjectionMaterializationIdentity,
+  ProjectionSourceBase,
+  ProjectionSourceDeletion,
   ProjectionSourceEntry,
   ProjectionSourceRef,
   ProjectionSourceReplacement,
@@ -19,6 +21,7 @@ import type {
   OntologyCommitRecord,
   OntologyCommitWrite,
   OntologyMaterializationStorage,
+  OntologySourceRecord,
   OntologyStorage,
 } from "../../storage/ontology"
 import type { MaterializerContext, MaterializerStorage } from "../context"
@@ -60,7 +63,8 @@ interface PreparedProjectionReplacement {
   readonly source: ProjectionSourceRef
   readonly datasetVersion: PinnedDatasetVersion
   readonly execution: ProjectionExecution
-  readonly entries: AsyncIterable<ProjectionSourceEntry>
+  readonly entries: AsyncIterable<ProjectionSourceEntry | ProjectionSourceDeletion>
+  readonly base?: ProjectionSourceBase
   readonly signal?: AbortSignal
   readonly resolved: ResolvedSourceProjection
   readonly projectionKind: "object" | "link"
@@ -128,6 +132,7 @@ function prepareProjectionReplacement(
     datasetVersion,
     execution,
     entries: raw.input.entries,
+    ...(raw.input.base ? { base: Object.freeze({ ...raw.input.base }) } : {}),
     resolved,
     projectionKind,
     runIdentity,
@@ -237,6 +242,7 @@ async function prepareProjectionCandidate(
     source: command.source,
   })
   validateProjectionWatermark(active, command.datasetVersion)
+  assertDeltaBase(active, command)
   return {
     materializationId: context.materializationId(),
     createdAt: context.clock().toISOString(),
@@ -263,6 +269,7 @@ async function stageProjectionCandidate(
     ownershipHash: command.resolved.ownershipHash,
     createdAt: candidate.createdAt,
     entries: command.entries,
+    ...(command.base ? { base: command.base } : {}),
     validateEntry: createProjectionEntryValidator(context.ontology, command.resolved),
   }
   const staged = await stageCandidateEntries(context, input, command.signal)
@@ -312,6 +319,14 @@ async function executeProjectionTransaction(
   )
   if (replay) return projectionReplayResult(replay, command)
 
+  if (command.base) {
+    const active = await storage.ontology.sources.getActive({
+      projectId: context.projectId,
+      source: command.source,
+    })
+    validateProjectionWatermark(active, command.datasetVersion)
+    assertDeltaBase(active, command)
+  }
   const origin = projectionOrigin(command)
   throwIfAborted(command.signal)
   const session = await storage.ontology.materializations.begin({
@@ -478,3 +493,23 @@ function validateProjectionWatermark(
   if (!active) return
   assertPinnedDatasetWatermark(active.datasetVersion, next, "Projection replacement")
 }
+
+function assertDeltaBase(
+  active: OntologySourceRecord | null,
+  command: PreparedProjectionReplacement
+): void {
+  if (
+    command.base &&
+    (!active ||
+      active.materializationId !== command.base.materializationId ||
+      active.lastCommitId !== command.base.lastCommitId ||
+      active.projectionRevision !== command.runIdentity.projectionRevision ||
+      active.ontologyRevision !== command.runIdentity.ontologyRevision ||
+      active.ownershipHash !== command.runIdentity.ownershipHash)
+  ) {
+    throw new MaterializationConflictError(
+      "source-materialization",
+      "Projection delta no longer matches the active source or its definition."
+    )
+  }
+}

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

@@ -1,16 +1,19 @@
+import { MaterializationValidationError } from "../../materialization/errors"
 import type {
   PinnedDatasetVersion,
   ProjectionExecution,
+  ProjectionSourceBase,
+  ProjectionSourceDeletion,
   ProjectionSourceEntry,
   ProjectionSourceRef,
 } from "../../materialization/model"
 import { utf8JsonByteLength } from "../../materialization/refs"
-import type { StageSourceAssertion } from "../../storage/ontology"
+import type { StageSourceAssertion, StageSourceRoot } from "../../storage/ontology"
 import type { MaterializerContext } from "../context"
 import { throwIfAborted } from "../shared/abort"
 import { chunkBySize } from "../shared/chunking"
-import { normalizeProjectionSourceEntry } from "../shared/normalize"
-import type { ProjectionEntryValidator } from "./entry-validator"
+import { normalizeProjectionEntity, normalizeProjectionSourceEntry } from "../shared/normalize"
+import { type ProjectionEntryValidator, validateProjectionRootRef } from "./entry-validator"
 
 export interface StagedProjectionMaterialization {
   readonly rootCount: number
@@ -37,7 +40,8 @@ export async function stageProjectionMaterialization(
     readonly projectionRevision: string
     readonly ownershipHash: string
     readonly createdAt: string
-    readonly entries: AsyncIterable<ProjectionSourceEntry>
+    readonly entries: AsyncIterable<ProjectionSourceEntry | ProjectionSourceDeletion>
+    readonly base?: ProjectionSourceBase
     readonly validateEntry: ProjectionEntryValidator
     readonly signal?: AbortSignal
   }
@@ -54,13 +58,28 @@ export async function stageProjectionMaterialization(
     ownershipHash: input.ownershipHash,
     ontologyRevision: context.projectionRegistry.ontologyRevision,
     createdAt: input.createdAt,
+    ...(input.base ? { base: input.base } : {}),
   })
 
   let rootCount = 0
   let assertionCount = 0
-  async function* assertions(): AsyncIterable<StageSourceAssertion> {
+  async function* assertions(): AsyncIterable<StageSourceAssertion | StageSourceRoot> {
     for await (const rawEntry of input.entries) {
       throwIfAborted(input.signal)
+      if ("deleted" in rawEntry) {
+        if (!input.base || rawEntry.deleted !== true) {
+          throw new MaterializationValidationError(
+            "Explicit root deletions require a pinned source base."
+          )
+        }
+        const root = normalizeProjectionEntity(rawEntry.root)
+        validateProjectionRootRef(
+          context.projectionRegistry.resolveSource(input.source.projectionId),
+          root
+        )
+        yield { root, stagingOrdinal: rootCount++ }
+        continue
+      }
       const entry = input.validateEntry(normalizeProjectionSourceEntry(rawEntry))
       const stagingOrdinal = rootCount
       for (const assertion of entry.assertions) {
@@ -82,7 +101,8 @@ export async function stageProjectionMaterialization(
       source: input.source,
       materializationId: input.materializationId,
       execution: input.execution,
-      rows,
+      rows: rows.filter((row): row is StageSourceAssertion => "assertion" in row),
+      deletions: rows.filter((row) => !("assertion" in row)),
     })
   }
 

package/src/materializer/shared/normalize.ts

@@ -344,7 +344,7 @@ export function normalizeProjectionExecution(input: ProjectionExecution): Projec
   })
 }
 
-function normalizeProjectionEntity(entity: ProjectionEntityRef): ProjectionEntityRef {
+export function normalizeProjectionEntity(entity: ProjectionEntityRef): ProjectionEntityRef {
   return entity.kind === "object"
     ? Object.freeze({ kind: "object", ref: normalizeObjectRef(entity.ref) })
     : Object.freeze({ kind: "link", ref: normalizeLinkRef(entity.ref) })

package/src/models/errors.ts

@@ -43,6 +43,18 @@ export class ModelStreamError extends Error {
 
 export class UnsupportedModelFeatureError extends Error {
   readonly name = "UnsupportedModelFeatureError"
+
+  constructor(
+    message?: string,
+    options?: ErrorOptions & {
+      readonly reason?: "unsupported-model" | "unsupported-schema"
+    }
+  ) {
+    super(message, options)
+    this.reason = options?.reason
+  }
+
+  readonly reason?: "unsupported-model" | "unsupported-schema"
 }
 
 export class StructuredOutputError extends Error {

package/src/models/execution/binding.ts

@@ -0,0 +1,29 @@
+import type { ModelsRuntime } from "../generation-types"
+
+export interface ModelExecutionAttempt {
+  readonly attempt: number
+  readonly signal: AbortSignal
+}
+
+const bindings = new WeakMap<ModelsRuntime, (input: ModelExecutionAttempt) => void>()
+
+export function registerModelExecutionBinding(
+  models: ModelsRuntime,
+  bind: (input: ModelExecutionAttempt) => void
+): void {
+  bindings.set(models, bind)
+}
+
+/** Called once on a fresh facade at the request or worker delivery boundary. */
+export function bindModelExecutionAttempt(
+  models: ModelsRuntime,
+  input: ModelExecutionAttempt
+): void {
+  const bind = bindings.get(models)
+  if (!bind) throw new Error("[SixbModels] Model runtime has no execution binding.")
+  if (!Number.isSafeInteger(input.attempt) || input.attempt < 1) {
+    throw new TypeError("[SixbModels] Execution attempt must be a positive safe integer.")
+  }
+  bind(input)
+  bindings.delete(models)
+}

package/src/models/execution/errors.ts

@@ -0,0 +1,18 @@
+/** A provider call was not recorded synchronously, so its execution must stop. */
+export class ModelUsageRecordingError extends Error {
+  readonly name = "ModelUsageRecordingError"
+
+  constructor(
+    readonly executionId: string,
+    readonly callId: string,
+    readonly recoveryScheduled: boolean,
+    options?: ErrorOptions
+  ) {
+    super(
+      recoveryScheduled
+        ? `[SixbModels] AI usage for call '${callId}' in execution '${executionId}' was deferred to durable recovery.`
+        : `[SixbModels] Could not preserve AI usage for call '${callId}' in execution '${executionId}'.`,
+      options
+    )
+  }
+}

package/src/models/execution/index.ts

@@ -0,0 +1,26 @@
+export { resolveLanguageModel } from "../resolve"
+export { ModelUsageRecordingError } from "./errors"
+export type {
+  AiModelCallAdmissionDecision,
+  AiModelCallAdmissionInput,
+  AiModelCallInputTokenEstimate,
+  BeforeAiModelCall,
+  MarkAiModelCallUnknown,
+} from "./model-call-admission"
+export type { AiModelCallLimitController } from "./model-call-limits"
+export { createAiModelCallLimitController } from "./model-call-limits"
+export type { AiModelCallRecorderInput } from "./model-call-recorder"
+export { AiModelCallRecorder } from "./model-call-recorder"
+export {
+  isPermanentAiUsageRecoveryError,
+  recordRecoveredAiModelCall,
+} from "./model-call-recovery"
+export { enqueueAiModelCallRecovery } from "./recovery-queue"
+export type {
+  AiModelCallAccountingPayload,
+  AiModelCallRecordPayload,
+  AiModelCallRecoveryRecord,
+  ModelCallAccountingStorage,
+  RecoverAiModelCall,
+  RecoverAiModelCallInput,
+} from "./types"

package/src/models/execution/model-call-accounting.ts

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto"
+import { assertJsonObject } from "../../json"
+import type {
+  AiBillableMeter,
+  AiCostStorage,
+  AiLimitStorage,
+  AiModelCallCostRecord,
+  AiModelCallUsageRecord,
+  AiPricingContext,
+  AiUsageStorage,
+  RecordAiModelCallResult,
+  Storage,
+} from "../../storage"
+import {
+  aiModelCallCostMatchesUsage,
+  normalizeAiModelCallCostRecord,
+} from "../../storage/ai-cost/provider"
+import { normalizeAiModelCallRecord } from "../../storage/ai-usage/record"
+import type { ModelCostEstimate } from "../pricing"
+import type { ModelCallAccountingStorage, RecoverAiModelCallInput } from "./types"
+
+interface RecordAiModelCallAccountingInput extends RecoverAiModelCallInput {
+  readonly storage: Pick<ModelCallAccountingStorage, "transaction">
+}
+
+interface AiAccountingCapabilities {
+  readonly aiUsage: AiUsageStorage
+  readonly aiCosts: AiCostStorage
+  readonly aiLimits: AiLimitStorage
+}
+
+/** Atomically append one provider call's usage and the valuation captured by the model runtime. */
+export async function recordAiModelCallAccounting(
+  input: RecordAiModelCallAccountingInput
+): Promise<RecordAiModelCallResult> {
+  return input.storage.transaction(async (tx) => {
+    const { aiUsage, aiCosts, aiLimits } = requireAccountingCapabilities(tx)
+    const usage = await aiUsage.recordModelCall(input.usage)
+    // Usage deduplicates provider lifecycle replays by execution/call identity. Always attach the
+    // valuation to the canonical row it returns, not the fresh candidate ID from a replay.
+    const canonical = normalizeModelCallAccounting({
+      ...input,
+      usage: usage.record,
+      ratedAt: usage.record.recordedAt,
+    })
+    const record = modelCostRecord(canonical, usage.record.id)
+    const estimate =
+      canonical.cost.status !== "reported" || canonical.estimate === undefined
+        ? undefined
+        : modelCostRecord({ ...canonical, cost: canonical.estimate }, usage.record.id)
+    await aiCosts.recordModelCallCost({
+      ...record,
+      ...(estimate === undefined
+        ? {}
+        : {
+            estimate:
+              estimate.status === "rated"
+                ? { status: "rated", money: estimate.money, components: estimate.components }
+                : {
+                    status: "unpriceable",
+                    reason: estimate.reason,
+                    ...(estimate.missingMeters === undefined
+                      ? {}
+                      : { missingMeters: estimate.missingMeters }),
+                  },
+          }),
+    })
+    if (usage.created) {
+      await aiLimits.recordModelCallActuals({
+        projectId: usage.record.projectId,
+        usageRecordId: usage.record.id,
+        recordedAt: input.ratedAt,
+      })
+    }
+    if (input.reconcileLimitReservation) {
+      await aiLimits.reconcileModelCall({
+        projectId: usage.record.projectId,
+        executionId: usage.record.executionId,
+        attempt: usage.record.attempt,
+        callId: usage.record.callId,
+        usageRecordId: usage.record.id,
+        reconciledAt: input.ratedAt,
+      })
+    }
+    return usage
+  })
+}
+
+/** Sanitize optional enrichment before either persistence or a JSON-safe recovery handoff. */
+export function normalizeModelCallAccounting(
+  input: RecoverAiModelCallInput
+): RecoverAiModelCallInput {
+  const usage = normalizeAiModelCallRecord(input.usage)
+  return {
+    ...input,
+    cost:
+      input.cost.status === "reported" ? input.cost : validatedEstimate(input.cost, input, usage),
+    ...(input.estimate === undefined
+      ? {}
+      : { estimate: validatedEstimate(input.estimate, input, usage) }),
+  }
+}
+
+function validatedEstimate(
+  cost: ModelCostEstimate,
+  input: RecoverAiModelCallInput,
+  usage: AiModelCallUsageRecord
+): ModelCostEstimate {
+  try {
+    assertJsonObject(cost, "model cost estimate")
+    const record = normalizeAiModelCallCostRecord(modelCostRecord({ ...input, cost }, usage.id))
+    if (!aiModelCallCostMatchesUsage(record, usage)) {
+      throw new TypeError("Estimate quantities do not match recorded usage.")
+    }
+    return structuredClone(cost)
+  } catch {
+    console.warn(
+      "[SixbModels] Invalid model cost estimate; preserving call usage and provider cost."
+    )
+    return { status: "unpriceable", reason: "inconsistent-usage" }
+  }
+}
+
+function modelCostRecord(
+  input: RecoverAiModelCallInput,
+  usageRecordId: string
+): AiModelCallCostRecord {
+  const billingIdentity = {
+    providerId: input.usage.providerId,
+    modelId: input.usage.requestedModelId,
+  }
+  const pricingContext: AiPricingContext = {
+    ...(input.route?.providerId === undefined ? {} : { routedProviderId: input.route.providerId }),
+    ...(input.route?.modelId === undefined ? {} : { routedModelId: input.route.modelId }),
+  }
+  if (input.cost.status === "reported" || input.cost.status === "rated") {
+    return {
+      projectId: input.usage.projectId,
+      usageRecordId,
+      status: "rated",
+      billingIdentity,
+      pricingContext,
+      priceSource: costPriceSource(input.usage, input.cost),
+      money: input.cost.money,
+      components: input.cost.status === "rated" ? input.cost.components : [],
+      ratedAt: new Date(input.ratedAt),
+    }
+  }
+
+  const reason =
+    input.cost.reason === "missing-rate-card"
+      ? "missingRateCard"
+      : input.cost.reason === "missing-usage"
+        ? "missingUsageMeter"
+        : "invalidUsageForFormula"
+  const missingMeters =
+    reason === "missingUsageMeter" ? normalizeMissingMeters(input.cost.missingMeters) : undefined
+  return {
+    projectId: input.usage.projectId,
+    usageRecordId,
+    status: "unpriceable",
+    billingIdentity,
+    pricingContext,
+    reason,
+    ...(missingMeters === undefined ? {} : { missingMeters }),
+    ratedAt: new Date(input.ratedAt),
+  }
+}
+
+function costPriceSource(
+  usage: RecoverAiModelCallInput["usage"],
+  cost: Extract<RecoverAiModelCallInput["cost"], { status: "reported" | "rated" }>
+) {
+  if (cost.status === "reported") {
+    return {
+      sourceId: "provider-reported",
+      sourceEntryId: `${usage.providerId}/${usage.responseId}`,
+      sourceVersion: "response-v1",
+      observedAt: new Date(usage.occurredAt),
+    }
+  }
+  const rates = cost.components.map(({ meter, rateAmountNanosPerMillion }) => ({
+    meter,
+    rateAmountNanosPerMillion,
+  }))
+  const version = createHash("sha256").update(JSON.stringify(rates)).digest("hex")
+  return {
+    sourceId: "model-rate-card",
+    sourceEntryId: `${usage.providerId}/${usage.requestedModelId}`,
+    sourceVersion: `sha256:${version}`,
+    observedAt: new Date(usage.occurredAt),
+  }
+}
+
+function normalizeMissingMeters(
+  meters: Extract<RecoverAiModelCallInput["cost"], { status: "unpriceable" }>["missingMeters"]
+): readonly AiBillableMeter[] {
+  const fallback: readonly AiBillableMeter[] = ["tokens.input.total", "tokens.output.total"]
+  return [...new Set<AiBillableMeter>(meters ?? fallback)]
+}
+
+export function requireAccountingCapabilities(
+  storage: Pick<Storage, "aiUsage" | "aiCosts" | "aiLimits">
+): AiAccountingCapabilities {
+  if (!storage.aiUsage || !storage.aiCosts || !storage.aiLimits) {
+    throw new Error(
+      "[SixbModels] AI model-call accounting requires storage.aiUsage, storage.aiCosts, and storage.aiLimits."
+    )
+  }
+  return { aiUsage: storage.aiUsage, aiCosts: storage.aiCosts, aiLimits: storage.aiLimits }
+}

package/src/models/execution/model-call-admission.ts

@@ -0,0 +1,127 @@
+import type { AiModelCallReservationIdentity } from "../../storage"
+import type { ModelCostEstimator } from "../pricing"
+
+/** Default output ceiling when a call and its resolved model supply no limit. */
+export const AI_MODEL_CALL_OUTPUT_TOKEN_ALLOWANCE = 4_096
+
+export type AiModelCallInputTokenEstimate =
+  | {
+      readonly status: "estimated"
+      readonly tokens: number
+      readonly method: "utf8BytesDividedByFour"
+    }
+  | {
+      readonly status: "unavailable"
+      readonly reason: "nonTextInput" | "unserializableInput"
+    }
+
+/** Provider-neutral snapshot passed to aggregate-budget admission before a provider request. */
+export interface AiModelCallAdmissionInput {
+  readonly projectId: string
+  readonly executionId: string
+  readonly attempt: number
+  readonly requesterGroupIds: readonly string[]
+  readonly callId: string
+  readonly providerId: string
+  readonly modelId: string
+  readonly costEstimator?: ModelCostEstimator
+  readonly inputTokens: AiModelCallInputTokenEstimate
+  readonly outputTokenAllowance: number
+  readonly estimatedTotalTokens?: number
+}
+
+export interface AiModelCallAdmissionDecision {
+  /** Active means accounting must reconcile the reservation for this provider attempt. */
+  readonly reservation: "active" | "none"
+}
+
+export type BeforeAiModelCall = (
+  input: AiModelCallAdmissionInput
+) => AiModelCallAdmissionDecision | Promise<AiModelCallAdmissionDecision>
+
+export type MarkAiModelCallUnknown = (input: AiModelCallReservationIdentity) => void | Promise<void>
+
+/**
+ * Estimate the exact, prepared provider request without requiring a provider-specific tokenizer.
+ *
+ * The heuristic is intentionally explicit so reservations are reproducible. Non-text inputs are
+ * reported as unavailable; an enforced token or cost policy can then fail closed instead of
+ * pretending that an image, file, or provider-defined payload has no token cost.
+ */
+export function estimateAiModelCallInputTokens(input: {
+  readonly prompt: unknown
+  readonly tools: unknown
+  readonly responseFormat: unknown
+}): AiModelCallInputTokenEstimate {
+  if (containsNonTextInput(input.prompt)) {
+    return { status: "unavailable", reason: "nonTextInput" }
+  }
+
+  let serialized: string | undefined
+  try {
+    serialized = JSON.stringify(input)
+  } catch {
+    return { status: "unavailable", reason: "unserializableInput" }
+  }
+  if (serialized === undefined) {
+    return { status: "unavailable", reason: "unserializableInput" }
+  }
+
+  const bytes = new TextEncoder().encode(serialized).byteLength
+  return {
+    status: "estimated",
+    tokens: Math.ceil(bytes / 4),
+    method: "utf8BytesDividedByFour",
+  }
+}
+
+export function aiModelCallOutputTokenAllowance(maxOutputTokens: number | undefined): number {
+  if (maxOutputTokens === undefined) return AI_MODEL_CALL_OUTPUT_TOKEN_ALLOWANCE
+  if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) {
+    throw new TypeError(
+      "[SixbModels] AI model-call maxOutputTokens must be a positive safe integer."
+    )
+  }
+  return maxOutputTokens
+}
+
+export function estimatedAiModelCallTotalTokens(
+  inputTokens: AiModelCallInputTokenEstimate,
+  outputTokenAllowance: number
+): number | undefined {
+  if (inputTokens.status !== "estimated") return undefined
+  const total = inputTokens.tokens + outputTokenAllowance
+  if (!Number.isSafeInteger(total)) {
+    throw new TypeError("[SixbModels] AI model-call token estimate exceeds the safe range.")
+  }
+  return total
+}
+
+function containsNonTextInput(value: unknown, seen = new WeakSet<object>()): boolean {
+  if (value === null || typeof value !== "object") return false
+  if (
+    value instanceof URL ||
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value) ||
+    (typeof Blob !== "undefined" && value instanceof Blob)
+  ) {
+    return true
+  }
+  if (seen.has(value)) return false
+  seen.add(value)
+
+  if (!Array.isArray(value)) {
+    const type = Reflect.get(value, "type")
+    if (
+      type === "image" ||
+      type === "file" ||
+      type === "reasoning-file" ||
+      type === "custom" ||
+      type === "provider-state"
+    ) {
+      return true
+    }
+  }
+
+  return Object.values(value).some((entry) => containsNonTextInput(entry, seen))
+}