@sixb/core 0.1.5 → 0.1.7

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

@@ -2,6 +2,7 @@ import type { AiModelCallUsageRecord, InMemoryAiUsageStorageSnapshot } from "../
 import type { AiAccountingRecordSetItem } from "./analytics"
 import { buildAiAccountingOverview, buildAiModelCallAccountingList } from "./analytics"
 import { AiCostStorageError } from "./errors"
+import { type AiAccountingGroupIdentity, buildAiModelCallGroups } from "./groups"
 import type {
   AiAccountingAttribution,
   AiAccountingOverview,
@@ -11,6 +12,8 @@ import type {
   AiMoney,
   ListAiModelCallAccountingInput,
   ListAiModelCallAccountingResult,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
   QueryAiAccountingOverviewInput,
   SummarizeAiCostExecutionsInput,
 } from "./types"
@@ -25,6 +28,10 @@ interface InMemoryAiCostUsageSource {
 }
 
 export interface InMemoryAiAccountingAttributionSource {
+  resolveGroup?(input: {
+    readonly projectId: string
+    readonly executionId: string
+  }): Promise<{ readonly executionId: string; readonly attribution?: AiAccountingAttribution }>
   resolve(input: {
     readonly projectId: string
     readonly executionId: string
@@ -85,10 +92,45 @@ export class InMemoryAiCostStorage implements AiCostStorage {
     return structuredClone({ recordsByUsage: this.recordsByUsage })
   }
 
+  async listModelCallGroups(
+    input: ListAiModelCallGroupsInput
+  ): Promise<ListAiModelCallGroupsResult> {
+    const items = await this.accountingItems()
+    const roots = new Map<string, Promise<AiAccountingGroupIdentity>>()
+    return buildAiModelCallGroups(
+      input,
+      await Promise.all(
+        items.map(async (item) => {
+          const key = usageRecordKey(item.usage.projectId, item.usage.executionId)
+          let root = roots.get(key)
+          if (!root) {
+            root =
+              this.attribution?.resolveGroup?.({
+                projectId: item.usage.projectId,
+                executionId: item.usage.executionId,
+              }) ??
+              Promise.resolve({
+                executionId: item.usage.executionId,
+                attribution: item.attribution,
+              })
+            roots.set(key, root)
+          }
+          return { ...item, root: await root }
+        })
+      )
+    )
+  }
+
   restore(snapshot: InMemoryAiCostStorageSnapshot): void {
     replaceMap(this.recordsByUsage, snapshot.recordsByUsage)
   }
 
+  /** @internal Immutable accounting source used by in-memory AI limit enforcement. */
+  getRecord(projectId: string, usageRecordId: string): AiModelCallCostRecord | null {
+    const record = this.recordsByUsage.get(usageRecordKey(projectId, usageRecordId))
+    return record ? structuredClone(record) : null
+  }
+
   private usageRecord(projectId: string, id: string): AiModelCallUsageRecord | undefined {
     return [...this.usage.snapshot().records.values()].find(
       (record) => record.projectId === projectId && record.id === id

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

@@ -18,10 +18,14 @@ export type {
   AiBillableMeter,
   AiBillingIdentity,
   AiCostComponent,
+  AiCostEstimate,
   AiCostStorage,
   AiCostSummary,
   AiModelCallAccountingItem,
   AiModelCallCostRecord,
+  AiModelCallExecutionSummary,
+  AiModelCallGroup,
+  AiModelCallGroupSummary,
   AiMoney,
   AiPriceSource,
   AiPricingContext,
@@ -30,6 +34,8 @@ export type {
   AiUnpriceableReason,
   ListAiModelCallAccountingInput,
   ListAiModelCallAccountingResult,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
   QueryAiAccountingOverviewInput,
   SummarizeAiCostExecutionsInput,
 } from "./types"

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

@@ -1,4 +1,5 @@
 /** @internal Storage-provider helpers; not part of the app-author API. */
+
 export type {
   AiAccountingAggregateFragment,
   AiAccountingRecordSetItem,
@@ -13,6 +14,12 @@ export {
 } from "./analytics"
 export type { AiModelCallCostDetails } from "./codec"
 export { aiModelCallCostDetails, parseAiModelCallCostDetails } from "./codec"
+export type {
+  AiAccountingGroupIdentity,
+  AiModelCallGroupFragment,
+  AiModelCallGroupRow,
+} from "./groups"
+export { aiModelCallGroupFragmentFromRow, buildAiModelCallGroupsFromFragments } from "./groups"
 export {
   aiModelCallCostMatchesUsage,
   normalizeAiModelCallCostRecord,

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

@@ -1,11 +1,13 @@
 import type { AiModelCallUsageRecord } from "../ai-usage"
 
-/** Token meters supported by the deterministic local catalog rater. */
+/** Token meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
   | "tokens.input.total"
   | "tokens.input.uncached"
   | "tokens.input.cacheRead"
   | "tokens.input.cacheWrite"
+  | "tokens.input.cacheWrite5m"
+  | "tokens.input.cacheWrite1h"
   | "tokens.output.total"
   | "tokens.output.text"
   | "tokens.output.reasoning"
@@ -17,7 +19,7 @@ export interface AiMoney {
   readonly amountNanos: string
 }
 
-/** Provider and model key in a pricing catalog. */
+/** Provider and model identity used for billing. */
 export interface AiBillingIdentity {
   readonly providerId: string
   readonly modelId: string
@@ -30,18 +32,19 @@ export interface AiPricingContext {
   readonly region?: string
   readonly inferenceGeo?: string
   readonly routedProviderId?: string
+  readonly routedModelId?: string
   readonly deploymentId?: string
   readonly inferenceProfileId?: string
   readonly cacheWriteTtlSeconds?: number
   readonly mode?: string
 }
 
-/** Immutable provenance of the compact catalog entry applied to a valuation. */
+/** Immutable provenance of the provider report or rate card applied to a valuation. */
 export interface AiPriceSource {
   readonly sourceId: string
   readonly sourceEntryId: string
   readonly sourceVersion: string
-  readonly sourceUrl: string
+  readonly sourceUrl?: string
   readonly observedAt: Date
 }
 
@@ -54,31 +57,46 @@ export interface AiCostComponent {
 
 export type AiUnpriceableReason =
   | "missingBillingIdentity"
-  | "missingCatalogEntry"
+  | "missingRateCard"
   | "missingUsageMeter"
   | "unsupportedPricingDimension"
   | "invalidUsageForFormula"
 
 interface AiModelCallCostRecordBase {
+  /** Local estimate retained independently when an inline provider cost is selected. */
+  readonly estimate?: AiCostEstimate
   readonly projectId: string
   readonly usageRecordId: string
   readonly pricingContext: AiPricingContext
-  readonly priceSource: AiPriceSource
   readonly ratedAt: Date
 }
 
-/** Exact arithmetic under one immutable catalog snapshot; not a provider-settled charge. */
+export type AiCostEstimate =
+  | {
+      readonly status: "rated"
+      readonly money: AiMoney
+      readonly components: readonly AiCostComponent[]
+    }
+  | {
+      readonly status: "unpriceable"
+      readonly reason: AiUnpriceableReason
+      readonly missingMeters?: readonly AiBillableMeter[]
+    }
+
+/** Selected monetary valuation; its observation/provenance distinguishes estimates from reports. */
 export interface AiRatedModelCallCostRecord extends AiModelCallCostRecordBase {
   readonly status: "rated"
   readonly billingIdentity: AiBillingIdentity
+  readonly priceSource: AiPriceSource
   readonly money: AiMoney
   readonly components: readonly AiCostComponent[]
 }
 
-/** Explicit result when the compact catalog cannot completely and safely value a call. */
+/** Explicit result when a call cannot be completely and safely valued. */
 export interface AiUnpriceableModelCallCostRecord extends AiModelCallCostRecordBase {
   readonly status: "unpriceable"
   readonly billingIdentity?: AiBillingIdentity
+  readonly priceSource?: AiPriceSource
   readonly reason: AiUnpriceableReason
   readonly missingMeters?: readonly AiBillableMeter[]
 }
@@ -91,6 +109,7 @@ export interface SummarizeAiCostExecutionsInput {
 }
 
 export interface AiCostSummary {
+  /** Selected request valuations, never the sum of competing observations or period reports. */
   readonly amounts: readonly AiMoney[]
   readonly ratedCallCount: number
   readonly unpriceableCallCount: number
@@ -133,9 +152,15 @@ export interface AiAccountingTimeBucket extends AiAccountingAggregate {
   readonly end: Date
 }
 
-export interface AiAccountingAgentBreakdown extends AiAccountingAggregate {
-  readonly agentId: string
-}
+export type AiAccountingAgentBreakdown = AiAccountingAggregate &
+  (
+    | { readonly kind: "agent" }
+    | {
+        readonly kind: "workflowAgent"
+        readonly workflowId: string
+        readonly agentStepId: string
+      }
+  )
 
 export interface AiAccountingWorkflowBreakdown extends AiAccountingAggregate {
   readonly workflowId: string
@@ -159,17 +184,21 @@ export interface AiAccountingOverview {
 export type AiAccountingAttribution =
   | {
       readonly kind: "agent"
-      readonly agentId: string
       readonly agentRunId: string
       readonly threadId: string
     }
   | {
       readonly kind: "workflowAgent"
-      readonly agentId: string
+      readonly agentStepId: string
       readonly nodeRunId: string
       readonly workflowId: string
       readonly workflowRunId: string
     }
+  | {
+      readonly kind: "subagent"
+      readonly subagentRunId: string
+      readonly parentRunId: string
+    }
 
 export interface AiModelCallAccountingItem {
   readonly usage: AiModelCallUsageRecord
@@ -184,10 +213,43 @@ export interface ListAiModelCallAccountingResult {
   readonly total: number
 }
 
-/** Immutable model-call costs plus execution and project accounting reads. */
+export type ListAiModelCallGroupsInput = Omit<ListAiModelCallAccountingInput, "executionId">
+
+/** Filtered usage; an absent token total means at least one call did not report it. */
+export interface AiModelCallGroupSummary {
+  readonly modelCallCount: number
+  readonly totalTokens?: number
+  readonly costs: AiCostSummary
+}
+
+export interface AiModelCallExecutionSummary extends AiModelCallGroupSummary {
+  readonly executionId: string
+  readonly attribution?: AiAccountingAttribution
+  readonly firstCallAt: Date
+  readonly lastCallAt: Date
+  readonly models: readonly AiBillingIdentity[]
+}
+
+/** One initiating execution, including only calls matching the accounting filters. */
+export interface AiModelCallGroup extends AiModelCallGroupSummary {
+  readonly executionId: string
+  readonly attribution?: AiAccountingAttribution
+  readonly firstCallAt: Date
+  readonly lastCallAt: Date
+  readonly executions: readonly AiModelCallExecutionSummary[]
+}
+
+export interface ListAiModelCallGroupsResult {
+  readonly items: readonly AiModelCallGroup[]
+  readonly total: number
+  readonly hasMore: boolean
+}
+
+/** Immutable call-time costs. Inline provider costs take precedence over local estimates. */
 export interface AiCostStorage {
   recordModelCallCost(input: AiModelCallCostRecord): Promise<void>
   summarizeExecutions(input: SummarizeAiCostExecutionsInput): Promise<readonly AiCostSummary[]>
   queryProjectOverview(input: QueryAiAccountingOverviewInput): Promise<AiAccountingOverview>
   listModelCalls(input: ListAiModelCallAccountingInput): Promise<ListAiModelCallAccountingResult>
+  listModelCallGroups(input: ListAiModelCallGroupsInput): Promise<ListAiModelCallGroupsResult>
 }

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)
+  }
+}