@sixb/core 0.1.1 → 0.1.3

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

@@ -0,0 +1,136 @@
+import type { AiBillableMeter, AiModelCallCostRecord, AiPricingContext } from "./types"
+import { normalizeAiPricingContext } from "./validation"
+
+export interface AiModelCallCostDetails {
+  readonly pricingContext: AiPricingContext
+  readonly priceSource: Omit<AiModelCallCostRecord["priceSource"], "observedAt"> & {
+    readonly observedAt: string
+  }
+  readonly components?: Extract<AiModelCallCostRecord, { status: "rated" }>["components"]
+  readonly missingMeters?: readonly AiBillableMeter[]
+}
+
+export function aiModelCallCostDetails(record: AiModelCallCostRecord): AiModelCallCostDetails {
+  return {
+    pricingContext: record.pricingContext,
+    priceSource: { ...record.priceSource, observedAt: record.priceSource.observedAt.toISOString() },
+    ...(record.status === "rated" ? { components: record.components } : {}),
+    ...(record.status === "unpriceable" && record.missingMeters
+      ? { missingMeters: record.missingMeters }
+      : {}),
+  }
+}
+
+export function parseAiModelCallCostDetails(value: unknown): AiModelCallCostDetails {
+  const parsed: unknown = typeof value === "string" ? JSON.parse(value) : value
+  if (!isRecord(parsed)) throw invalidDetails()
+  const priceSource = parsed.priceSource
+  if (!isRecord(priceSource)) throw invalidDetails()
+  const components = parsed.components
+  const missingMeters = parsed.missingMeters
+  return {
+    pricingContext: pricingContextFromUnknown(parsed.pricingContext),
+    priceSource: {
+      sourceId: requiredString(priceSource.sourceId),
+      sourceEntryId: requiredString(priceSource.sourceEntryId),
+      sourceVersion: requiredString(priceSource.sourceVersion),
+      sourceUrl: requiredString(priceSource.sourceUrl),
+      observedAt: requiredString(priceSource.observedAt),
+    },
+    ...(components === undefined ? {} : { components: costComponentsFromUnknown(components) }),
+    ...(missingMeters === undefined ? {} : { missingMeters: metersFromUnknown(missingMeters) }),
+  }
+}
+
+function pricingContextFromUnknown(value: unknown): AiPricingContext {
+  if (!isRecord(value)) throw invalidDetails()
+  return normalizeAiPricingContext({
+    ...optionalStringProperty(value, "serviceTier"),
+    ...optionalBooleanProperty(value, "batch"),
+    ...optionalStringProperty(value, "region"),
+    ...optionalStringProperty(value, "inferenceGeo"),
+    ...optionalStringProperty(value, "routedProviderId"),
+    ...optionalStringProperty(value, "deploymentId"),
+    ...optionalStringProperty(value, "inferenceProfileId"),
+    ...optionalNumberProperty(value, "cacheWriteTtlSeconds"),
+    ...optionalStringProperty(value, "mode"),
+  })
+}
+
+function costComponentsFromUnknown(
+  value: unknown
+): Extract<AiModelCallCostRecord, { status: "rated" }>["components"] {
+  if (!Array.isArray(value)) throw invalidDetails()
+  return value.map((component) => {
+    if (!isRecord(component)) throw invalidDetails()
+    return {
+      meter: billableMeter(component.meter),
+      quantity: requiredString(component.quantity),
+      rateAmountNanosPerMillion: requiredString(component.rateAmountNanosPerMillion),
+      chargeAmountNanos: requiredString(component.chargeAmountNanos),
+    }
+  })
+}
+
+function metersFromUnknown(value: unknown): readonly AiBillableMeter[] {
+  if (!Array.isArray(value)) throw invalidDetails()
+  return value.map(billableMeter)
+}
+
+function billableMeter(value: unknown): AiBillableMeter {
+  if (
+    value !== "tokens.input.total" &&
+    value !== "tokens.input.uncached" &&
+    value !== "tokens.input.cacheRead" &&
+    value !== "tokens.input.cacheWrite" &&
+    value !== "tokens.output.total" &&
+    value !== "tokens.output.text" &&
+    value !== "tokens.output.reasoning"
+  ) {
+    throw invalidDetails()
+  }
+  return value
+}
+
+function optionalStringProperty(
+  value: Record<string, unknown>,
+  name: string
+): Record<string, string> {
+  const property = value[name]
+  if (property === undefined) return {}
+  if (typeof property !== "string") throw invalidDetails()
+  return { [name]: property }
+}
+
+function optionalBooleanProperty(
+  value: Record<string, unknown>,
+  name: string
+): Record<string, boolean> {
+  const property = value[name]
+  if (property === undefined) return {}
+  if (typeof property !== "boolean") throw invalidDetails()
+  return { [name]: property }
+}
+
+function optionalNumberProperty(
+  value: Record<string, unknown>,
+  name: string
+): Record<string, number> {
+  const property = value[name]
+  if (property === undefined) return {}
+  if (typeof property !== "number") throw invalidDetails()
+  return { [name]: property }
+}
+
+function requiredString(value: unknown): string {
+  if (typeof value !== "string") throw invalidDetails()
+  return value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function invalidDetails(): Error {
+  return new Error("[Sixb] AI valuation details are invalid.")
+}

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

@@ -0,0 +1,12 @@
+export type AiCostStorageErrorCode = "missing_usage" | "cost_mismatch"
+
+export class AiCostStorageError extends Error {
+  readonly name = "AiCostStorageError"
+
+  constructor(
+    readonly code: AiCostStorageErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

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

@@ -0,0 +1,164 @@
+import type { AiModelCallUsageRecord, InMemoryAiUsageStorageSnapshot } from "../ai-usage"
+import type { AiAccountingRecordSetItem } from "./analytics"
+import { buildAiAccountingOverview, buildAiModelCallAccountingList } from "./analytics"
+import { AiCostStorageError } from "./errors"
+import type {
+  AiAccountingAttribution,
+  AiAccountingOverview,
+  AiCostStorage,
+  AiCostSummary,
+  AiModelCallCostRecord,
+  AiMoney,
+  ListAiModelCallAccountingInput,
+  ListAiModelCallAccountingResult,
+  QueryAiAccountingOverviewInput,
+  SummarizeAiCostExecutionsInput,
+} from "./types"
+import { aiModelCallCostMatchesUsage, normalizeAiModelCallCostRecord } from "./validation"
+
+export interface InMemoryAiCostStorageSnapshot {
+  readonly recordsByUsage: Map<string, AiModelCallCostRecord>
+}
+
+interface InMemoryAiCostUsageSource {
+  snapshot(): InMemoryAiUsageStorageSnapshot
+}
+
+export interface InMemoryAiAccountingAttributionSource {
+  resolve(input: {
+    readonly projectId: string
+    readonly executionId: string
+  }): Promise<AiAccountingAttribution | undefined>
+}
+
+/** In-memory immutable model-call costs and accounting reads. */
+export class InMemoryAiCostStorage implements AiCostStorage {
+  private readonly recordsByUsage = new Map<string, AiModelCallCostRecord>()
+
+  constructor(
+    private readonly usage: InMemoryAiCostUsageSource,
+    private readonly attribution?: InMemoryAiAccountingAttributionSource
+  ) {}
+
+  async recordModelCallCost(input: AiModelCallCostRecord): Promise<void> {
+    const record = normalizeAiModelCallCostRecord(input)
+    const usage = this.usageRecord(record.projectId, record.usageRecordId)
+    if (!usage) throw missingUsage(record)
+    if (!aiModelCallCostMatchesUsage(record, usage)) {
+      throw new AiCostStorageError(
+        "cost_mismatch",
+        `[Sixb] AI valuation for usage '${record.usageRecordId}' does not match its usage record.`
+      )
+    }
+    const key = usageRecordKey(record.projectId, record.usageRecordId)
+    if (!this.recordsByUsage.has(key)) this.recordsByUsage.set(key, structuredClone(record))
+  }
+
+  async summarizeExecutions(
+    input: SummarizeAiCostExecutionsInput
+  ): Promise<readonly AiCostSummary[]> {
+    assertNonBlank(input.projectId, "cost summary projectId")
+    for (const id of input.executionIds) assertNonBlank(id, "cost summary executionId")
+    const requested = new Set(input.executionIds)
+    const usageByExecution = new Map(input.executionIds.map((id) => [id, [] as string[]]))
+    for (const usage of this.usage.snapshot().records.values()) {
+      if (usage.projectId === input.projectId && requested.has(usage.executionId)) {
+        usageByExecution.get(usage.executionId)!.push(usage.id)
+      }
+    }
+    return input.executionIds.map((id) =>
+      this.summarizeUsageIds(input.projectId, usageByExecution.get(id) ?? [])
+    )
+  }
+
+  async queryProjectOverview(input: QueryAiAccountingOverviewInput): Promise<AiAccountingOverview> {
+    return buildAiAccountingOverview(input, await this.accountingItems())
+  }
+
+  async listModelCalls(
+    input: ListAiModelCallAccountingInput
+  ): Promise<ListAiModelCallAccountingResult> {
+    return buildAiModelCallAccountingList(input, await this.accountingItems())
+  }
+
+  snapshot(): InMemoryAiCostStorageSnapshot {
+    return structuredClone({ recordsByUsage: this.recordsByUsage })
+  }
+
+  restore(snapshot: InMemoryAiCostStorageSnapshot): void {
+    replaceMap(this.recordsByUsage, snapshot.recordsByUsage)
+  }
+
+  private usageRecord(projectId: string, id: string): AiModelCallUsageRecord | undefined {
+    return [...this.usage.snapshot().records.values()].find(
+      (record) => record.projectId === projectId && record.id === id
+    )
+  }
+
+  private async accountingItems(): Promise<readonly AiAccountingRecordSetItem[]> {
+    return Promise.all(
+      [...this.usage.snapshot().records.values()].map(async (usage) => {
+        const cost = this.recordsByUsage.get(usageRecordKey(usage.projectId, usage.id))
+        const attribution = await this.attribution?.resolve({
+          projectId: usage.projectId,
+          executionId: usage.executionId,
+        })
+        return {
+          usage,
+          ...(attribution ? { attribution } : {}),
+          ...(cost ? { cost } : {}),
+        }
+      })
+    )
+  }
+
+  private summarizeUsageIds(projectId: string, ids: readonly string[]): AiCostSummary {
+    const amounts = new Map<string, bigint>()
+    let ratedCallCount = 0
+    let unpriceableCallCount = 0
+    let unvaluedCallCount = 0
+    for (const id of ids) {
+      const cost = this.recordsByUsage.get(usageRecordKey(projectId, id))
+      if (!cost) unvaluedCallCount += 1
+      else if (cost.status === "unpriceable") unpriceableCallCount += 1
+      else {
+        ratedCallCount += 1
+        addMoney(amounts, cost.money)
+      }
+    }
+    return {
+      amounts: [...amounts]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([currency, amount]) => ({ currency, amountNanos: amount.toString() })),
+      ratedCallCount,
+      unpriceableCallCount,
+      unvaluedCallCount,
+    }
+  }
+}
+
+function missingUsage(record: { readonly projectId: string; readonly usageRecordId: string }) {
+  return new AiCostStorageError(
+    "missing_usage",
+    `[Sixb] AI usage '${record.usageRecordId}' does not exist in project '${record.projectId}'.`
+  )
+}
+
+function addMoney(amounts: Map<string, bigint>, money: AiMoney): void {
+  amounts.set(money.currency, (amounts.get(money.currency) ?? 0n) + BigInt(money.amountNanos))
+}
+
+function usageRecordKey(projectId: string, id: string): string {
+  return JSON.stringify([projectId, id])
+}
+
+function assertNonBlank(value: string, field: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`[Sixb] AI ${field} must be nonblank.`)
+  }
+}
+
+function replaceMap<TKey, TValue>(target: Map<TKey, TValue>, source: Map<TKey, TValue>): void {
+  target.clear()
+  for (const [key, value] of structuredClone(source)) target.set(key, value)
+}

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

@@ -0,0 +1,35 @@
+export type { AiCostStorageErrorCode } from "./errors"
+export { AiCostStorageError } from "./errors"
+export type {
+  InMemoryAiAccountingAttributionSource,
+  InMemoryAiCostStorageSnapshot,
+} from "./in-memory"
+export { InMemoryAiCostStorage } from "./in-memory"
+export type {
+  AiAccountingAgentBreakdown,
+  AiAccountingAggregate,
+  AiAccountingAttribution,
+  AiAccountingBucket,
+  AiAccountingModelBreakdown,
+  AiAccountingOverview,
+  AiAccountingRange,
+  AiAccountingTimeBucket,
+  AiAccountingWorkflowBreakdown,
+  AiBillableMeter,
+  AiBillingIdentity,
+  AiCostComponent,
+  AiCostStorage,
+  AiCostSummary,
+  AiModelCallAccountingItem,
+  AiModelCallCostRecord,
+  AiMoney,
+  AiPriceSource,
+  AiPricingContext,
+  AiRatedModelCallCostRecord,
+  AiUnpriceableModelCallCostRecord,
+  AiUnpriceableReason,
+  ListAiModelCallAccountingInput,
+  ListAiModelCallAccountingResult,
+  QueryAiAccountingOverviewInput,
+  SummarizeAiCostExecutionsInput,
+} from "./types"

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

@@ -0,0 +1,20 @@
+/** @internal Storage-provider helpers; not part of the app-author API. */
+export type {
+  AiAccountingAggregateFragment,
+  AiAccountingRecordSetItem,
+  NormalizedAiAccountingQuery,
+  NormalizedAiModelCallAccountingQuery,
+} from "./analytics"
+export {
+  buildAiAccountingOverviewFromFragments,
+  normalizeAiAccountingQuery,
+  normalizeAiModelCallAccountingQuery,
+  toAccountingItem,
+} from "./analytics"
+export type { AiModelCallCostDetails } from "./codec"
+export { aiModelCallCostDetails, parseAiModelCallCostDetails } from "./codec"
+export {
+  aiModelCallCostMatchesUsage,
+  normalizeAiModelCallCostRecord,
+  normalizeAiPricingContext,
+} from "./validation"

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

@@ -0,0 +1,193 @@
+import type { AiModelCallUsageRecord } from "../ai-usage"
+
+/** Token meters supported by the deterministic local catalog rater. */
+export type AiBillableMeter =
+  | "tokens.input.total"
+  | "tokens.input.uncached"
+  | "tokens.input.cacheRead"
+  | "tokens.input.cacheWrite"
+  | "tokens.output.total"
+  | "tokens.output.text"
+  | "tokens.output.reasoning"
+
+/** Exact money in nanounits of a currency's major unit. */
+export interface AiMoney {
+  readonly currency: string
+  /** Canonical non-negative integer string. One USD is 1,000,000,000 nanounits. */
+  readonly amountNanos: string
+}
+
+/** Provider and model key in a pricing catalog. */
+export interface AiBillingIdentity {
+  readonly providerId: string
+  readonly modelId: string
+}
+
+/** Allowlisted response/request dimensions retained for audit and strict fail-closed pricing. */
+export interface AiPricingContext {
+  readonly serviceTier?: string
+  readonly batch?: boolean
+  readonly region?: string
+  readonly inferenceGeo?: string
+  readonly routedProviderId?: string
+  readonly deploymentId?: string
+  readonly inferenceProfileId?: string
+  readonly cacheWriteTtlSeconds?: number
+  readonly mode?: string
+}
+
+/** Immutable provenance of the compact catalog entry applied to a valuation. */
+export interface AiPriceSource {
+  readonly sourceId: string
+  readonly sourceEntryId: string
+  readonly sourceVersion: string
+  readonly sourceUrl: string
+  readonly observedAt: Date
+}
+
+export interface AiCostComponent {
+  readonly meter: AiBillableMeter
+  readonly quantity: string
+  readonly rateAmountNanosPerMillion: string
+  readonly chargeAmountNanos: string
+}
+
+export type AiUnpriceableReason =
+  | "missingBillingIdentity"
+  | "missingCatalogEntry"
+  | "missingUsageMeter"
+  | "unsupportedPricingDimension"
+  | "invalidUsageForFormula"
+
+interface AiModelCallCostRecordBase {
+  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 interface AiRatedModelCallCostRecord extends AiModelCallCostRecordBase {
+  readonly status: "rated"
+  readonly billingIdentity: AiBillingIdentity
+  readonly money: AiMoney
+  readonly components: readonly AiCostComponent[]
+}
+
+/** Explicit result when the compact catalog cannot completely and safely value a call. */
+export interface AiUnpriceableModelCallCostRecord extends AiModelCallCostRecordBase {
+  readonly status: "unpriceable"
+  readonly billingIdentity?: AiBillingIdentity
+  readonly reason: AiUnpriceableReason
+  readonly missingMeters?: readonly AiBillableMeter[]
+}
+
+export type AiModelCallCostRecord = AiRatedModelCallCostRecord | AiUnpriceableModelCallCostRecord
+
+export interface SummarizeAiCostExecutionsInput {
+  readonly projectId: string
+  readonly executionIds: readonly string[]
+}
+
+export interface AiCostSummary {
+  readonly amounts: readonly AiMoney[]
+  readonly ratedCallCount: number
+  readonly unpriceableCallCount: number
+  readonly unvaluedCallCount: number
+}
+
+export type AiAccountingBucket = "hour" | "day" | "week"
+
+/** Inclusive start and exclusive end for project accounting reads. */
+export interface AiAccountingRange {
+  readonly from: Date
+  readonly to: Date
+}
+
+export interface QueryAiAccountingOverviewInput extends AiAccountingRange {
+  readonly projectId: string
+  readonly bucket: AiAccountingBucket
+  readonly providerId?: string
+  readonly modelId?: string
+}
+
+export interface ListAiModelCallAccountingInput extends AiAccountingRange {
+  readonly projectId: string
+  readonly providerId?: string
+  readonly modelId?: string
+  readonly executionId?: string
+  readonly valuationStatus?: "rated" | "unpriceable" | "unvalued"
+  readonly limit?: number
+  readonly offset?: number
+}
+
+export interface AiAccountingAggregate {
+  readonly modelCallCount: number
+  readonly usage: AiModelCallUsageRecord["usage"]
+  readonly costs: AiCostSummary
+}
+
+export interface AiAccountingTimeBucket extends AiAccountingAggregate {
+  readonly start: Date
+  readonly end: Date
+}
+
+export interface AiAccountingAgentBreakdown extends AiAccountingAggregate {
+  readonly agentId: string
+}
+
+export interface AiAccountingWorkflowBreakdown extends AiAccountingAggregate {
+  readonly workflowId: string
+}
+
+export interface AiAccountingModelBreakdown extends AiAccountingAggregate {
+  readonly providerId: string
+  readonly modelId: string
+}
+
+export interface AiAccountingOverview {
+  readonly range: AiAccountingRange
+  readonly bucket: AiAccountingBucket
+  readonly totals: AiAccountingAggregate
+  readonly series: readonly AiAccountingTimeBucket[]
+  readonly models: readonly AiAccountingModelBreakdown[]
+  readonly agents: readonly AiAccountingAgentBreakdown[]
+  readonly workflows: readonly AiAccountingWorkflowBreakdown[]
+}
+
+export type AiAccountingAttribution =
+  | {
+      readonly kind: "agent"
+      readonly agentId: string
+      readonly agentRunId: string
+      readonly threadId: string
+    }
+  | {
+      readonly kind: "workflowAgent"
+      readonly agentId: string
+      readonly nodeRunId: string
+      readonly workflowId: string
+      readonly workflowRunId: string
+    }
+
+export interface AiModelCallAccountingItem {
+  readonly usage: AiModelCallUsageRecord
+  readonly attribution?: AiAccountingAttribution
+  readonly cost?: AiModelCallCostRecord
+  readonly valuationStatus: "rated" | "unpriceable" | "unvalued"
+}
+
+export interface ListAiModelCallAccountingResult {
+  readonly items: readonly AiModelCallAccountingItem[]
+  readonly hasMore: boolean
+  readonly total: number
+}
+
+/** Immutable model-call costs plus execution and project accounting reads. */
+export interface AiCostStorage {
+  recordModelCallCost(input: AiModelCallCostRecord): Promise<void>
+  summarizeExecutions(input: SummarizeAiCostExecutionsInput): Promise<readonly AiCostSummary[]>
+  queryProjectOverview(input: QueryAiAccountingOverviewInput): Promise<AiAccountingOverview>
+  listModelCalls(input: ListAiModelCallAccountingInput): Promise<ListAiModelCallAccountingResult>
+}