@sixb/core 0.1.6 → 0.1.8

package/src/storage/ai-cost/validation.ts

@@ -1,9 +1,11 @@
+import { assertJsonObject } from "../../json"
 import type { AiModelCallUsage, AiModelCallUsageRecord } from "../ai-usage"
 import { normalizeAiModelCallUsage } from "../ai-usage"
 import type {
   AiBillableMeter,
   AiBillingIdentity,
   AiCostComponent,
+  AiCostEstimate,
   AiModelCallCostRecord,
   AiPriceSource,
   AiPricingContext,
@@ -21,14 +23,16 @@ const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.input.uncached": 1,
   "tokens.input.cacheRead": 2,
   "tokens.input.cacheWrite": 3,
-  "tokens.output.total": 4,
-  "tokens.output.text": 5,
-  "tokens.output.reasoning": 6,
+  "tokens.input.cacheWrite5m": 4,
+  "tokens.input.cacheWrite1h": 5,
+  "tokens.output.total": 6,
+  "tokens.output.text": 7,
+  "tokens.output.reasoning": 8,
 }
-const METERS = new Set(Object.keys(METER_ORDER))
+const METERS = new Set(Object.keys(METER_ORDER) as AiBillableMeter[])
 const UNPRICEABLE_REASONS = new Set<AiUnpriceableReason>([
   "missingBillingIdentity",
-  "missingCatalogEntry",
+  "missingRateCard",
   "missingUsageMeter",
   "unsupportedPricingDimension",
   "invalidUsageForFormula",
@@ -38,6 +42,7 @@ const CONTEXT_STRING_FIELDS = [
   "region",
   "inferenceGeo",
   "routedProviderId",
+  "routedModelId",
   "deploymentId",
   "inferenceProfileId",
   "mode",
@@ -78,15 +83,27 @@ export function normalizeAiModelCallCostRecord(
   assertNonBlank(input.projectId, "cost record projectId")
   assertNonBlank(input.usageRecordId, "cost record usageRecordId")
   const base = {
+    ...(input.estimate === undefined ? {} : { estimate: normalizeAiCostEstimate(input.estimate) }),
     projectId: input.projectId,
     usageRecordId: input.usageRecordId,
     pricingContext: normalizeAiPricingContext(input.pricingContext),
-    priceSource: normalizePriceSource(input.priceSource),
     ratedAt: cloneDate(input.ratedAt, "cost record ratedAt"),
   }
 
-  if (input.status === "rated") return normalizeRatedCost(input, base)
-  if (input.status === "unpriceable") return normalizeUnpriceableCost(input, base)
+  if (input.status === "rated") {
+    return normalizeRatedCost(input, {
+      ...base,
+      priceSource: normalizePriceSource(input.priceSource),
+    })
+  }
+  if (input.status === "unpriceable") {
+    return normalizeUnpriceableCost(input, {
+      ...base,
+      ...(input.priceSource === undefined
+        ? {}
+        : { priceSource: normalizePriceSource(input.priceSource) }),
+    })
+  }
   throw new TypeError("[Sixb] AI cost status is invalid.")
 }
 
@@ -98,7 +115,21 @@ export function aiModelCallCostMatchesUsage(
   if (record.projectId !== usageRecord.projectId || record.usageRecordId !== usageRecord.id) {
     return false
   }
+  if (record.estimate?.status === "rated") {
+    const usage = normalizeAiModelCallUsage(usageRecord.usage)
+    const components = new Map(
+      record.estimate.components.map((component) => [component.meter, component])
+    )
+    if (
+      !inputComponentsMatchUsage(components, usage) ||
+      !outputComponentsMatchUsage(components, usage)
+    )
+      return false
+  }
   if (record.status === "unpriceable") return true
+  if (record.components.length === 0 && isExternalValuationSource(record.priceSource.sourceId)) {
+    return true
+  }
 
   const usage = normalizeAiModelCallUsage(usageRecord.usage)
   const components = new Map(record.components.map((component) => [component.meter, component]))
@@ -113,25 +144,43 @@ function inputComponentsMatchUsage(
 ): boolean {
   if (usage.inputTokens === undefined) return false
   const total = components.get("tokens.input.total")
-  const partitions = [
+  const directPartitions = [
     ["tokens.input.uncached", usage.uncachedInputTokens],
     ["tokens.input.cacheRead", usage.cacheReadInputTokens],
     ["tokens.input.cacheWrite", usage.cacheWriteInputTokens],
   ] as const
-  const presentPartitions = partitions.filter(([meter]) => components.has(meter))
+  const presentDirect = directPartitions.filter(([meter]) => components.has(meter))
+  const specificWrites = [
+    components.get("tokens.input.cacheWrite5m"),
+    components.get("tokens.input.cacheWrite1h"),
+  ].filter((component): component is AiCostComponent => component !== undefined)
 
   if (total) {
-    return presentPartitions.length === 0 && BigInt(total.quantity) === BigInt(usage.inputTokens)
+    return (
+      presentDirect.length === 0 &&
+      specificWrites.length === 0 &&
+      BigInt(total.quantity) === BigInt(usage.inputTokens)
+    )
   }
-  if (presentPartitions.length === 0) return false
+  if (presentDirect.length === 0 && specificWrites.length === 0) return false
+  if (components.has("tokens.input.cacheWrite") && specificWrites.length > 0) return false
 
   let quantity = 0n
-  for (const [meter, expected] of presentPartitions) {
+  for (const [meter, expected] of presentDirect) {
     if (expected === undefined) return false
     const component = components.get(meter)!
     if (BigInt(component.quantity) !== BigInt(expected)) return false
     quantity += BigInt(component.quantity)
   }
+  if (specificWrites.length > 0) {
+    if (usage.cacheWriteInputTokens === undefined) return false
+    const specificWriteQuantity = specificWrites.reduce(
+      (sum, component) => sum + BigInt(component.quantity),
+      0n
+    )
+    if (specificWriteQuantity !== BigInt(usage.cacheWriteInputTokens)) return false
+    quantity += specificWriteQuantity
+  }
   return quantity === BigInt(usage.inputTokens)
 }
 
@@ -171,12 +220,14 @@ function normalizeRatedCost(
 ): AiRatedModelCallCostRecord {
   const billingIdentity = normalizeBillingIdentity(input.billingIdentity)
   const components = input.components.map(normalizeCostComponent).sort(compareComponents)
-  if (components.length === 0) throw new TypeError("[Sixb] AI rated cost requires components.")
+  if (components.length === 0 && !isExternalValuationSource(base.priceSource.sourceId)) {
+    throw new TypeError("[Sixb] AI rated cost requires components.")
+  }
   if (new Set(components.map((component) => component.meter)).size !== components.length) {
     throw new TypeError("[Sixb] AI rated cost cannot contain duplicate meters.")
   }
   const amountNanos = parseNonnegativeInt64(input.money.amountNanos, "money amountNanos").toString()
-  if (amountNanos !== sumComponents(components)) {
+  if (components.length > 0 && amountNanos !== sumComponents(components)) {
     throw new TypeError("[Sixb] AI cost total does not equal its component charges.")
   }
   return {
@@ -188,6 +239,79 @@ function normalizeRatedCost(
   }
 }
 
+export function normalizeAiCostEstimate(value: unknown): AiCostEstimate {
+  assertJsonObject(value, "AI cost estimate")
+  if (value.status === "rated") {
+    assertJsonObject(value.money, "estimate money")
+    const { currency, amountNanos } = value.money
+    if (
+      typeof currency !== "string" ||
+      typeof amountNanos !== "string" ||
+      !Array.isArray(value.components)
+    )
+      throw new TypeError("[Sixb] Invalid cost estimate money or components.")
+    const components = value.components
+      .map((component) => {
+        assertJsonObject(component, "estimate component")
+        const meter = [...METERS].find((meter) => meter === component.meter)
+        if (
+          !meter ||
+          typeof component.quantity !== "string" ||
+          typeof component.rateAmountNanosPerMillion !== "string" ||
+          typeof component.chargeAmountNanos !== "string"
+        )
+          throw new TypeError("[Sixb] Invalid cost estimate component.")
+        return normalizeCostComponent({
+          meter,
+          quantity: component.quantity,
+          rateAmountNanosPerMillion: component.rateAmountNanosPerMillion,
+          chargeAmountNanos: component.chargeAmountNanos,
+        })
+      })
+      .sort(compareComponents)
+    if (
+      !components.length ||
+      new Set(components.map((c) => c.meter)).size !== components.length ||
+      parseNonnegativeInt64(amountNanos, "estimate amountNanos").toString() !==
+        sumComponents(components)
+    )
+      throw new TypeError(
+        "[Sixb] Estimate must contain unique meters whose charges equal its total."
+      )
+    return {
+      status: "rated",
+      money: { currency: normalizeCurrency(currency), amountNanos },
+      components,
+    }
+  }
+  const reason = [...UNPRICEABLE_REASONS].find((reason) => reason === value.reason)
+  if (value.status !== "unpriceable" || !reason)
+    throw new TypeError("[Sixb] Invalid cost estimate status or reason.")
+  let missingMeters: readonly AiBillableMeter[] | undefined
+  if (value.missingMeters !== undefined) {
+    if (!Array.isArray(value.missingMeters))
+      throw new TypeError("[Sixb] Invalid estimate missing meters.")
+    missingMeters = normalizeMissingMeters(
+      value.missingMeters.map((input) => {
+        const meter = [...METERS].find((meter) => meter === input)
+        if (!meter) throw new TypeError("[Sixb] Invalid estimate missing meter.")
+        return meter
+      })
+    )
+  }
+  if (reason === "missingUsageMeter" && !missingMeters)
+    throw new TypeError("[Sixb] Missing usage estimate requires missingMeters.")
+  return {
+    status: "unpriceable",
+    reason,
+    ...(missingMeters === undefined ? {} : { missingMeters }),
+  }
+}
+
+function isExternalValuationSource(sourceId: string): boolean {
+  return sourceId === "provider-reported"
+}
+
 function normalizeUnpriceableCost(
   input: AiUnpriceableModelCallCostRecord,
   base: Pick<
@@ -252,8 +376,14 @@ function normalizePriceSource(input: AiPriceSource): AiPriceSource {
   assertNonBlank(input.sourceId, "price sourceId")
   assertNonBlank(input.sourceEntryId, "price sourceEntryId")
   assertNonBlank(input.sourceVersion, "price sourceVersion")
-  assertNonBlank(input.sourceUrl, "price sourceUrl")
-  return { ...input, observedAt: cloneDate(input.observedAt, "price source observedAt") }
+  if (input.sourceUrl !== undefined) assertNonBlank(input.sourceUrl, "price sourceUrl")
+  return {
+    sourceId: input.sourceId,
+    sourceEntryId: input.sourceEntryId,
+    sourceVersion: input.sourceVersion,
+    ...(input.sourceUrl === undefined ? {} : { sourceUrl: input.sourceUrl }),
+    observedAt: cloneDate(input.observedAt, "price source observedAt"),
+  }
 }
 
 function normalizeBillingIdentity(input: AiBillingIdentity): AiBillingIdentity {

package/src/storage/ai-limits/enforcement.ts

@@ -0,0 +1,68 @@
+import { createSixbError, type SixbCodedError } from "../../errors/internal"
+import type { AuthorizablePrincipal } from "../../execution/types"
+import type { ReadonlyJsonValue } from "../../json"
+import { aiLimitSubjectKey } from "./provider"
+import type { AiLimitPolicy, AiLimitPolicyStatus, AiLimitSubject } from "./types"
+
+/** @internal Resolve the immutable attribution dimensions enforced for one model call. */
+export function aiLimitSubjectsFromAttribution(
+  requestedBy: AuthorizablePrincipal | undefined,
+  requesterGroupIds: readonly string[]
+): readonly AiLimitSubject[] {
+  const subjects: AiLimitSubject[] = [
+    { type: "project" },
+    ...requesterGroupIds.map((id): AiLimitSubject => ({ type: "group", id })),
+  ]
+  if (requestedBy) subjects.push(requestedBy)
+
+  const byKey = new Map(subjects.map((subject) => [aiLimitSubjectKey(subject), subject]))
+  return [...byKey.values()].sort((left, right) =>
+    aiLimitSubjectKey(left).localeCompare(aiLimitSubjectKey(right))
+  )
+}
+
+/** @internal Select every policy that applies to the call's immutable attribution snapshot. */
+export function applicableAiLimitPolicyStatuses(
+  statuses: readonly AiLimitPolicyStatus[],
+  subjects: readonly AiLimitSubject[]
+): readonly AiLimitPolicyStatus[] {
+  const keys = new Set(subjects.map(aiLimitSubjectKey))
+  return statuses.filter((status) => keys.has(aiLimitSubjectKey(status.policy.subject)))
+}
+
+/** @internal Cheap policy-only counterpart used before the authoritative atomic reservation. */
+export function applicableAiLimitPolicies(
+  policies: readonly AiLimitPolicy[],
+  subjects: readonly AiLimitSubject[]
+): readonly AiLimitPolicy[] {
+  const keys = new Set(subjects.map(aiLimitSubjectKey))
+  return policies.filter((policy) => keys.has(aiLimitSubjectKey(policy.subject)))
+}
+
+/** @internal Stable failure safe for callers that may only hold run authority. */
+export function aiUsageLimitExceededError(resetAt: Date): SixbCodedError {
+  return createSixbError(
+    "ai.usage_limit_exceeded",
+    "[Sixb] An applicable AI usage limit has no capacity for this model call.",
+    { details: aiLimitFailureDetails({ resetAt }) }
+  )
+}
+
+/** @internal Fail closed when an applicable policy cannot be measured or reserved safely. */
+export function aiUsageLimitUnavailableError(reasons: readonly string[]): SixbCodedError {
+  return createSixbError(
+    "ai.usage_limit_unavailable",
+    "[Sixb] An applicable AI usage limit could not be evaluated safely.",
+    { details: aiLimitFailureDetails({ reasons }) }
+  )
+}
+
+function aiLimitFailureDetails(input: {
+  readonly resetAt?: Date
+  readonly reasons?: readonly string[]
+}): ReadonlyJsonValue {
+  return {
+    ...(input.resetAt === undefined ? {} : { resetAt: input.resetAt.toISOString() }),
+    ...(input.reasons === undefined ? {} : { reasons: [...input.reasons] }),
+  }
+}

package/src/storage/ai-limits/errors.ts

@@ -0,0 +1,23 @@
+export type AiLimitStorageErrorCode =
+  | "duplicate_policy"
+  | "missing_policy"
+  | "missing_execution"
+  | "missing_reservation"
+  | "missing_usage_record"
+  | "usage_mismatch"
+  | "unavailable_actuals"
+  | "reservation_conflict"
+  | "reconciliation_conflict"
+  | "invalid_reservation_state"
+
+/** Stable storage failure for AI limit policies and reservations. */
+export class AiLimitStorageError extends Error {
+  readonly name = "AiLimitStorageError"
+
+  constructor(
+    readonly code: AiLimitStorageErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}