@sixb/core 0.1.6 → 0.1.8

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

@@ -0,0 +1,11 @@
+import type { AiLimitPeriod } from "./types"
+
+/** Return the UTC calendar month containing `at`, with an inclusive start and exclusive end. */
+export function aiLimitCalendarMonth(at: Date): AiLimitPeriod {
+  if (!(at instanceof Date) || !Number.isFinite(at.getTime())) {
+    throw new TypeError("[Sixb] AI limit period date must be a valid Date.")
+  }
+  const start = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), 1))
+  const end = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth() + 1, 1))
+  return { kind: "calendarMonth", start, end, resetAt: new Date(end) }
+}

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

@@ -0,0 +1,430 @@
+import type { AiMoney } from "../ai-cost"
+import { AiLimitStorageError } from "./errors"
+import { aiLimitCalendarMonth } from "./period"
+import type {
+  AiLimitPeriod,
+  AiLimitPolicy,
+  AiLimitQuantity,
+  AiLimitReservationBucket,
+  AiLimitSubject,
+  AiModelCallReservation,
+  AiModelCallReservationIdentity,
+  CreateAiLimitPolicyInput,
+  ReserveAiModelCallInput,
+  UpdateAiLimitPolicyInput,
+} from "./types"
+
+const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
+
+/** @internal Serialize compound limit operations, including within an existing transaction. */
+export class AiLimitOperationLock {
+  private tail: Promise<void> = Promise.resolve()
+
+  /** Wait for already queued operations before the owning transaction commits or rolls back. */
+  settle(): Promise<void> {
+    return this.tail
+  }
+
+  async run<T>(operation: () => Promise<T> | T): Promise<T> {
+    const previous = this.tail
+    let release!: () => void
+    this.tail = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    await previous
+    try {
+      return await operation()
+    } finally {
+      release()
+    }
+  }
+}
+
+/** @internal Canonical integer quantity used by storage providers. */
+export interface NormalizedAiLimitAmount {
+  readonly meter: AiLimitQuantity["meter"]
+  readonly currency: string
+  readonly amount: bigint
+}
+
+/** @internal Minimal immutable accounting facts consumed by limit providers. */
+export interface AiLimitAccountingEntry {
+  readonly projectId: string
+  readonly usageRecordId: string
+  readonly executionId: string
+  readonly attempt: number
+  readonly callId: string
+  readonly occurredAt: Date
+  readonly totalTokens?: number
+  readonly requesterGroupIds: readonly string[]
+  readonly requester?:
+    | { readonly type: "user"; readonly id: string }
+    | { readonly type: "serviceAccount"; readonly id: string }
+  readonly valuation?:
+    | { readonly status: "rated"; readonly money: AiMoney }
+    | { readonly status: "unavailable" }
+}
+
+export interface ResolvedAiLimitActual {
+  readonly amount: bigint
+  readonly accountingStatus: "complete" | "unavailable"
+}
+
+export function normalizeAiLimitSubject(subject: AiLimitSubject): AiLimitSubject {
+  if (!subject || typeof subject !== "object") {
+    throw new TypeError("[Sixb] AI limit subject must be an object.")
+  }
+  if (subject.type === "project") return { type: "project" }
+  if (subject.type === "group" || subject.type === "user" || subject.type === "serviceAccount") {
+    assertNonBlank(subject.id, "subject id")
+    return { type: subject.type, id: subject.id }
+  }
+  throw new TypeError("[Sixb] AI limit subject type is unsupported.")
+}
+
+export function normalizeAiLimitSubjects(
+  subjects: readonly AiLimitSubject[]
+): readonly AiLimitSubject[] {
+  if (!Array.isArray(subjects)) {
+    throw new TypeError("[Sixb] AI limit subjects must be an array.")
+  }
+  const normalized = [
+    normalizeAiLimitSubject({ type: "project" }),
+    ...subjects.map(normalizeAiLimitSubject),
+  ]
+  const byKey = new Map(normalized.map((subject) => [aiLimitSubjectKey(subject), subject]))
+  return [...byKey.values()].sort((left, right) =>
+    aiLimitSubjectKey(left).localeCompare(aiLimitSubjectKey(right))
+  )
+}
+
+export function aiLimitSubjectKey(subject: AiLimitSubject): string {
+  return subject.type === "project" ? "project:" : `${subject.type}:${subject.id}`
+}
+
+export function aiLimitSubjectParts(subject: AiLimitSubject): {
+  readonly type: AiLimitSubject["type"]
+  readonly id: string
+} {
+  return { type: subject.type, id: subject.type === "project" ? "" : subject.id }
+}
+
+export function aiLimitSubjectFromParts(type: AiLimitSubject["type"], id: string): AiLimitSubject {
+  return normalizeAiLimitSubject(type === "project" ? { type } : { type, id })
+}
+
+export function normalizeAiLimitQuantity(quantity: AiLimitQuantity): AiLimitQuantity {
+  const normalized = normalizeAiLimitAmount(quantity)
+  return aiLimitQuantityFromAmount(normalized)
+}
+
+export function normalizeAiLimitQuantities(
+  quantities: readonly AiLimitQuantity[],
+  label: string
+): readonly AiLimitQuantity[] {
+  if (!Array.isArray(quantities) || quantities.length === 0) {
+    throw new TypeError(`[Sixb] AI limit ${label} must contain at least one quantity.`)
+  }
+  const byKey = new Map<string, AiLimitQuantity>()
+  for (const quantity of quantities) {
+    const normalized = normalizeAiLimitQuantity(quantity)
+    const key = aiLimitAmountKey(normalizeAiLimitAmount(normalized))
+    if (byKey.has(key)) {
+      throw new TypeError(`[Sixb] AI limit ${label} contains duplicate meter '${key}'.`)
+    }
+    byKey.set(key, normalized)
+  }
+  return [...byKey.values()].sort((left, right) =>
+    aiLimitAmountKey(normalizeAiLimitAmount(left)).localeCompare(
+      aiLimitAmountKey(normalizeAiLimitAmount(right))
+    )
+  )
+}
+
+export function normalizeAiLimitAmount(quantity: AiLimitQuantity): NormalizedAiLimitAmount {
+  if (!quantity || typeof quantity !== "object") {
+    throw new TypeError("[Sixb] AI limit quantity must be an object.")
+  }
+  if (quantity.meter === "tokens.total") {
+    if (!Number.isSafeInteger(quantity.amount) || quantity.amount < 0) {
+      throw new TypeError("[Sixb] AI limit token amount must be a non-negative safe integer.")
+    }
+    return { meter: quantity.meter, currency: "", amount: BigInt(quantity.amount) }
+  }
+  if (quantity.meter === "cost.catalogEstimated") {
+    const money = normalizeAiMoney(quantity.amount)
+    return { meter: quantity.meter, currency: money.currency, amount: BigInt(money.amountNanos) }
+  }
+  throw new TypeError("[Sixb] AI limit meter is unsupported.")
+}
+
+export function aiLimitQuantityFromAmount(amount: NormalizedAiLimitAmount): AiLimitQuantity {
+  if (amount.amount < 0n) {
+    throw new TypeError("[Sixb] AI limit amount cannot be negative.")
+  }
+  if (amount.meter === "tokens.total") {
+    const tokens = Number(amount.amount)
+    if (!Number.isSafeInteger(tokens)) {
+      throw new RangeError("[Sixb] AI limit token amount exceeds JavaScript's safe integer range.")
+    }
+    return { meter: amount.meter, amount: tokens }
+  }
+  if (amount.currency !== "USD") {
+    throw new TypeError("[Sixb] AI limit catalog-estimated cost currency must be 'USD'.")
+  }
+  return {
+    meter: amount.meter,
+    amount: { currency: "USD", amountNanos: amount.amount.toString() },
+  }
+}
+
+export function aiLimitAmountKey(
+  amount: Pick<NormalizedAiLimitAmount, "meter" | "currency">
+): string {
+  return `${amount.meter}:${amount.currency}`
+}
+
+export function normalizeCreateAiLimitPolicy(input: CreateAiLimitPolicyInput): AiLimitPolicy {
+  assertNonBlank(input.id, "policy id")
+  assertNonBlank(input.projectId, "projectId")
+  const createdAt = cloneValidDate(input.createdAt ?? new Date(), "createdAt")
+  return {
+    id: input.id,
+    projectId: input.projectId,
+    subject: normalizeAiLimitSubject(input.subject),
+    limit: normalizeAiLimitQuantity(input.limit),
+    period: "calendarMonth",
+    enabled: input.enabled ?? true,
+    createdAt,
+    updatedAt: new Date(createdAt),
+  }
+}
+
+export function normalizeUpdateAiLimitPolicy(input: UpdateAiLimitPolicyInput): {
+  readonly projectId: string
+  readonly id: string
+  readonly limit?: AiLimitQuantity
+  readonly enabled?: boolean
+  readonly updatedAt: Date
+} {
+  assertNonBlank(input.projectId, "projectId")
+  assertNonBlank(input.id, "policy id")
+  if (input.limit === undefined && input.enabled === undefined) {
+    throw new TypeError("[Sixb] AI limit policy update must change limit or enabled.")
+  }
+  if (input.enabled !== undefined && typeof input.enabled !== "boolean") {
+    throw new TypeError("[Sixb] AI limit enabled must be a boolean.")
+  }
+  return {
+    projectId: input.projectId,
+    id: input.id,
+    ...(input.limit === undefined ? {} : { limit: normalizeAiLimitQuantity(input.limit) }),
+    ...(input.enabled === undefined ? {} : { enabled: input.enabled }),
+    updatedAt: cloneValidDate(input.updatedAt ?? new Date(), "updatedAt"),
+  }
+}
+
+export function normalizeReserveAiModelCall(input: ReserveAiModelCallInput): {
+  readonly identity: AiModelCallReservationIdentity
+  readonly subjects: readonly AiLimitSubject[]
+  readonly estimates: readonly AiLimitQuantity[]
+  readonly period: AiLimitPeriod
+  readonly reservedAt: Date
+} {
+  const identity = normalizeAiModelCallReservationIdentity(input)
+  const reservedAt = cloneValidDate(input.reservedAt ?? new Date(), "reservedAt")
+  return {
+    identity,
+    subjects: normalizeAiLimitSubjects(input.subjects),
+    estimates: normalizeAiLimitQuantities(input.estimates, "estimates"),
+    period: aiLimitCalendarMonth(reservedAt),
+    reservedAt,
+  }
+}
+
+export function normalizeAiModelCallReservationIdentity(
+  input: AiModelCallReservationIdentity
+): AiModelCallReservationIdentity {
+  assertNonBlank(input.projectId, "projectId")
+  assertNonBlank(input.executionId, "executionId")
+  if (!Number.isSafeInteger(input.attempt) || input.attempt <= 0) {
+    throw new TypeError("[Sixb] AI limit reservation attempt must be a positive safe integer.")
+  }
+  assertNonBlank(input.callId, "callId")
+  return {
+    projectId: input.projectId,
+    executionId: input.executionId,
+    attempt: input.attempt,
+    callId: input.callId,
+  }
+}
+
+export function aiModelCallReservationKey(identity: AiModelCallReservationIdentity): string {
+  return JSON.stringify([
+    identity.projectId,
+    identity.executionId,
+    identity.attempt,
+    identity.callId,
+  ])
+}
+
+export function aiLimitPolicyDimensionKey(
+  policy: Pick<AiLimitPolicy, "projectId" | "subject" | "limit">
+): string {
+  const amount = normalizeAiLimitAmount(policy.limit)
+  return JSON.stringify([
+    policy.projectId,
+    aiLimitSubjectKey(policy.subject),
+    amount.meter,
+    amount.currency,
+  ])
+}
+
+export function aiLimitReservationRequestMatches(
+  reservation: AiModelCallReservation,
+  request: ReturnType<typeof normalizeReserveAiModelCall>
+): boolean {
+  return reservation.requestKey === aiLimitReservationRequestKey(request)
+}
+
+export function aiLimitReservationRequestKey(
+  request: ReturnType<typeof normalizeReserveAiModelCall>
+): string {
+  return JSON.stringify([
+    request.period.start.toISOString(),
+    request.subjects.map(aiLimitSubjectKey),
+    request.estimates.map((quantity) => {
+      const amount = normalizeAiLimitAmount(quantity)
+      return [amount.meter, amount.currency, amount.amount.toString()]
+    }),
+  ])
+}
+
+export function aiLimitReservationBuckets(
+  policies: readonly AiLimitPolicy[],
+  subjects: readonly AiLimitSubject[],
+  estimates: readonly AiLimitQuantity[]
+): readonly AiLimitReservationBucket[] {
+  const subjectKeys = new Set(subjects.map(aiLimitSubjectKey))
+  const estimatesByDimension = new Map(
+    estimates.map((estimate) => {
+      const amount = normalizeAiLimitAmount(estimate)
+      return [aiLimitAmountKey(amount), estimate] as const
+    })
+  )
+  return policies
+    .filter((policy) => subjectKeys.has(aiLimitSubjectKey(policy.subject)))
+    .flatMap((policy) => {
+      const estimate = estimatesByDimension.get(
+        aiLimitAmountKey(normalizeAiLimitAmount(policy.limit))
+      )
+      return estimate ? [{ subject: policy.subject, estimate }] : []
+    })
+    .sort((left, right) => {
+      const subject = aiLimitSubjectKey(left.subject).localeCompare(
+        aiLimitSubjectKey(right.subject)
+      )
+      if (subject !== 0) return subject
+      return aiLimitAmountKey(normalizeAiLimitAmount(left.estimate)).localeCompare(
+        aiLimitAmountKey(normalizeAiLimitAmount(right.estimate))
+      )
+    })
+}
+
+export function aiLimitAccountingEntryAppliesToSubject(
+  entry: AiLimitAccountingEntry,
+  subject: AiLimitSubject
+): boolean {
+  if (subject.type === "project") return true
+  if (subject.type === "group") return entry.requesterGroupIds.includes(subject.id)
+  return entry.requester?.type === subject.type && entry.requester.id === subject.id
+}
+
+export function aiLimitSubjectsFromAccountingEntry(
+  entry: AiLimitAccountingEntry
+): readonly AiLimitSubject[] {
+  return normalizeAiLimitSubjects([
+    ...entry.requesterGroupIds.map((id) => ({ type: "group" as const, id })),
+    ...(entry.requester ? [entry.requester] : []),
+  ])
+}
+
+export function resolveAiLimitActual(
+  entries: readonly AiLimitAccountingEntry[],
+  dimension: Pick<NormalizedAiLimitAmount, "meter" | "currency">
+): ResolvedAiLimitActual {
+  let amount = 0n
+  let accountingStatus: ResolvedAiLimitActual["accountingStatus"] = "complete"
+  for (const entry of entries) {
+    if (dimension.meter === "tokens.total") {
+      if (entry.totalTokens === undefined) {
+        accountingStatus = "unavailable"
+      } else {
+        amount += BigInt(entry.totalTokens)
+      }
+      continue
+    }
+    if (
+      entry.valuation?.status !== "rated" ||
+      entry.valuation.money.currency !== dimension.currency
+    ) {
+      accountingStatus = "unavailable"
+      continue
+    }
+    amount += BigInt(entry.valuation.money.amountNanos)
+  }
+  return { amount, accountingStatus }
+}
+
+export function assertAiLimitAccountingMatchesReservation(
+  reservation: AiModelCallReservation,
+  entry: AiLimitAccountingEntry
+): void {
+  if (
+    entry.projectId !== reservation.projectId ||
+    entry.executionId !== reservation.executionId ||
+    entry.attempt !== reservation.attempt ||
+    entry.callId !== reservation.callId
+  ) {
+    throw new AiLimitStorageError(
+      "usage_mismatch",
+      `[Sixb] AI usage record '${entry.usageRecordId}' does not belong to reservation '${reservation.callId}'.`
+    )
+  }
+}
+
+export function cloneAiLimitPolicy(policy: AiLimitPolicy): AiLimitPolicy {
+  return structuredClone(policy)
+}
+
+function normalizeAiMoney(money: AiMoney): AiMoney & { readonly currency: "USD" } {
+  if (!money || typeof money !== "object") {
+    throw new TypeError("[Sixb] AI limit cost amount must be AiMoney.")
+  }
+  assertNonBlank(money.currency, "cost currency")
+  if (money.currency !== "USD") {
+    throw new TypeError("[Sixb] AI limit catalog-estimated cost currency must be 'USD'.")
+  }
+  if (!/^(0|[1-9][0-9]*)$/.test(money.amountNanos)) {
+    throw new TypeError(
+      "[Sixb] AI limit cost amountNanos must be a canonical non-negative integer string."
+    )
+  }
+  if (BigInt(money.amountNanos) > SIGNED_INT64_MAX) {
+    throw new RangeError("[Sixb] AI limit cost amountNanos exceeds the supported range.")
+  }
+  return { currency: "USD", amountNanos: money.amountNanos }
+}
+
+export function assertNonBlank(value: string, label: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`[Sixb] AI limit ${label} must be nonblank.`)
+  }
+}
+
+export function cloneValidDate(value: Date, label: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`[Sixb] AI limit ${label} must be a valid Date.`)
+  }
+  return new Date(value)
+}

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

@@ -0,0 +1,195 @@
+import type { AiMoney } from "../ai-cost"
+
+/** A project-wide, group, or durable requester identity charged for AI model calls. */
+export type AiLimitSubject =
+  | { readonly type: "project" }
+  | { readonly type: "group"; readonly id: string }
+  | { readonly type: "user"; readonly id: string }
+  | { readonly type: "serviceAccount"; readonly id: string }
+
+/** Aggregate meters supported by the first AI usage-limit release. */
+export type AiLimitMeter = "tokens.total" | "cost.catalogEstimated"
+
+/** An exact quantity for one supported meter. */
+export type AiLimitQuantity =
+  | { readonly meter: "tokens.total"; readonly amount: number }
+  | {
+      readonly meter: "cost.catalogEstimated"
+      readonly amount: AiMoney & { readonly currency: "USD" }
+    }
+
+export type AiLimitPeriodKind = "calendarMonth"
+
+/** Inclusive start and exclusive end of one UTC accounting period. */
+export interface AiLimitPeriod {
+  readonly kind: AiLimitPeriodKind
+  readonly start: Date
+  readonly end: Date
+  /** The first instant at which a denied call may be admitted in the next period. */
+  readonly resetAt: Date
+}
+
+/** Editable policy. Consumption is intentionally stored independently from this record. */
+export interface AiLimitPolicy {
+  readonly id: string
+  readonly projectId: string
+  readonly subject: AiLimitSubject
+  readonly limit: AiLimitQuantity
+  readonly period: AiLimitPeriodKind
+  readonly enabled: boolean
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+export interface CreateAiLimitPolicyInput {
+  readonly id: string
+  readonly projectId: string
+  readonly subject: AiLimitSubject
+  readonly limit: AiLimitQuantity
+  readonly enabled?: boolean
+  readonly createdAt?: Date
+}
+
+export interface UpdateAiLimitPolicyInput {
+  readonly projectId: string
+  readonly id: string
+  /** The meter and cost currency are immutable; only the amount may change. */
+  readonly limit?: AiLimitQuantity
+  readonly enabled?: boolean
+  readonly updatedAt?: Date
+}
+
+export interface GetAiLimitPolicyInput {
+  readonly projectId: string
+  readonly id: string
+}
+
+export interface DeleteAiLimitPolicyInput extends GetAiLimitPolicyInput {}
+
+export interface ListAiLimitPoliciesInput {
+  readonly projectId: string
+  readonly includeDisabled?: boolean
+}
+
+/** Current-period consumption for one policy, all expressed in the policy's meter. */
+export interface AiLimitConsumption {
+  readonly actual: AiLimitQuantity
+  readonly reserved: AiLimitQuantity
+  readonly unknown: AiLimitQuantity
+  readonly remaining: AiLimitQuantity
+}
+
+export interface AiLimitPolicyStatus {
+  readonly policy: AiLimitPolicy
+  readonly period: AiLimitPeriod
+  readonly consumption: AiLimitConsumption
+  /** Whether every applicable immutable ledger record could be measured for this policy. */
+  readonly accountingStatus: "complete" | "unavailable"
+  readonly exhausted: boolean
+  /** True only when the caller supplied the current group set and this group is absent. */
+  readonly orphaned: boolean
+}
+
+export interface ListAiLimitPolicyStatusesInput {
+  readonly projectId: string
+  readonly at?: Date
+  readonly includeDisabled?: boolean
+  /** Optional current group IDs used to report policies whose snapshotted group disappeared. */
+  readonly existingGroupIds?: readonly string[]
+}
+
+export interface AiModelCallReservationIdentity {
+  readonly projectId: string
+  readonly executionId: string
+  readonly attempt: number
+  readonly callId: string
+}
+
+export interface AiLimitReservationBucket {
+  readonly subject: AiLimitSubject
+  readonly estimate: AiLimitQuantity
+}
+
+export type AiModelCallReservationState = "active" | "reconciled" | "unknown"
+
+/** Durable reservation for one Sixb-owned provider attempt. */
+export interface AiModelCallReservation extends AiModelCallReservationIdentity {
+  /** Only policy dimensions that were applicable at admission time. */
+  readonly buckets: readonly AiLimitReservationBucket[]
+  /** Canonical admission request used to reject conflicting idempotent replays. */
+  readonly requestKey: string
+  readonly period: AiLimitPeriod
+  readonly state: AiModelCallReservationState
+  readonly usageRecordId?: string
+  readonly reservedAt: Date
+  readonly updatedAt: Date
+}
+
+export interface ReserveAiModelCallInput extends AiModelCallReservationIdentity {
+  /** The project subject is always added, even when omitted here. */
+  readonly subjects: readonly AiLimitSubject[]
+  readonly estimates: readonly AiLimitQuantity[]
+  readonly reservedAt?: Date
+}
+
+export type ReserveAiModelCallResult =
+  | {
+      readonly status: "reserved"
+      readonly reservation: AiModelCallReservation
+      /** False when the exact reservation identity and request were replayed. */
+      readonly created: boolean
+    }
+  | {
+      /** No enabled policy matched a supplied subject and estimate. */
+      readonly status: "notRequired"
+    }
+  | {
+      /** Exact replay of a reservation that can no longer authorize a provider call. */
+      readonly status: "terminal"
+      readonly reservation: AiModelCallReservation
+      readonly created: false
+    }
+  | {
+      readonly status: "denied"
+      /** Every applicable policy that the proposed reservation would exceed. */
+      readonly exhaustedPolicies: readonly AiLimitPolicyStatus[]
+      readonly resetAt: Date
+    }
+  | {
+      /** Admission failed closed because an applicable policy could not be measured safely. */
+      readonly status: "unavailable"
+      readonly unavailablePolicies: readonly AiLimitPolicyStatus[]
+      readonly reasons: readonly ("missingEstimate" | "incompleteAccounting")[]
+    }
+
+export interface ReconcileAiModelCallInput extends AiModelCallReservationIdentity {
+  readonly usageRecordId: string
+  readonly reconciledAt?: Date
+}
+
+export interface MarkAiModelCallReservationUnknownInput extends AiModelCallReservationIdentity {
+  readonly markedAt?: Date
+}
+
+export interface RecordAiModelCallLimitActualsInput {
+  readonly projectId: string
+  readonly usageRecordId: string
+  readonly recordedAt?: Date
+}
+
+export interface AiLimitStorage {
+  createPolicy(input: CreateAiLimitPolicyInput): Promise<AiLimitPolicy>
+  updatePolicy(input: UpdateAiLimitPolicyInput): Promise<AiLimitPolicy>
+  deletePolicy(input: DeleteAiLimitPolicyInput): Promise<boolean>
+  getPolicy(input: GetAiLimitPolicyInput): Promise<AiLimitPolicy | null>
+  listPolicies(input: ListAiLimitPoliciesInput): Promise<readonly AiLimitPolicy[]>
+  listPolicyStatuses(input: ListAiLimitPolicyStatusesInput): Promise<readonly AiLimitPolicyStatus[]>
+
+  reserveModelCall(input: ReserveAiModelCallInput): Promise<ReserveAiModelCallResult>
+  /** Applies a newly-created immutable usage record to initialized period counters. */
+  recordModelCallActuals(input: RecordAiModelCallLimitActualsInput): Promise<void>
+  reconcileModelCall(input: ReconcileAiModelCallInput): Promise<AiModelCallReservation>
+  markReservationUnknown(
+    input: MarkAiModelCallReservationUnknownInput
+  ): Promise<AiModelCallReservation>
+}

package/src/storage/ai-usage/in-memory.ts

@@ -144,6 +144,19 @@ export class InMemoryAiUsageStorage implements AiUsageStorage {
     replaceMap(this.groupRows, snapshot.groupRows)
   }
 
+  /** @internal Immutable accounting source used by in-memory AI limit enforcement. */
+  getRecord(projectId: string, id: string): AiModelCallUsageRecord | null {
+    const record = this.records.get(modelCallRecordKey(projectId, id))
+    return record ? structuredClone(record) : null
+  }
+
+  /** @internal Immutable accounting source used by in-memory AI limit status reads. */
+  listRecords(projectId: string): readonly AiModelCallUsageRecord[] {
+    return [...this.records.values()]
+      .filter((record) => record.projectId === projectId)
+      .map((record) => structuredClone(record))
+  }
+
   private async assertExecutionExists(projectId: string, executionId: string): Promise<void> {
     const execution = await this.executions.getById({ projectId, id: executionId })
     if (execution) return

package/src/storage/ai-usage/record.ts

@@ -1,5 +1,7 @@
 import { normalizeRequesterGroupIds } from "../../auth/attribution"
 import { assertJsonValue, isPlainRecord } from "../../json"
+import { normalizeModelProviderIds } from "../../models/events"
+import { isModelReasoning } from "../../models/language-model"
 import type { AiModelCallUsageRecord, RecordAiModelCallInput } from "./types"
 import { normalizeAiModelCallUsage } from "./usage"
 
@@ -20,6 +22,7 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
   const recordedAt = cloneValidDate(input.recordedAt ?? new Date(), "recordedAt")
   const requesterGroupIds = normalizeRequesterGroupIds(input.requesterGroupIds)
+  const requestedReasoning = cloneRequestedReasoning(input.requestedReasoning)
   const rawUsage = cloneRawUsage(input.rawUsage)
 
   return {
@@ -30,7 +33,11 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
     callId: input.callId,
     requesterGroupIds,
     providerId: input.providerId,
+    ...(input.providerIds === undefined
+      ? {}
+      : { providerIds: normalizeModelProviderIds(input.providerIds) }),
     requestedModelId: input.requestedModelId,
+    ...(requestedReasoning === undefined ? {} : { requestedReasoning }),
     ...(input.responseModelId === undefined ? {} : { responseModelId: input.responseModelId }),
     responseId: input.responseId,
     usage: normalizeAiModelCallUsage(input.usage),
@@ -40,6 +47,16 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   }
 }
 
+function cloneRequestedReasoning(
+  reasoning: RecordAiModelCallInput["requestedReasoning"]
+): RecordAiModelCallInput["requestedReasoning"] {
+  if (reasoning === undefined) return undefined
+  if (!isModelReasoning(reasoning)) {
+    throw new TypeError("[Sixb] AI usage requestedReasoning is invalid.")
+  }
+  return typeof reasoning === "string" ? reasoning : { budgetTokens: reasoning.budgetTokens }
+}
+
 /** Validate a durable execution reference at storage and query boundaries. */
 export function assertAiUsageExecutionId(executionId: string): void {
   assertNonBlank(executionId, "executionId")