@sixb/core 0.1.2 → 0.1.3

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

@@ -0,0 +1,337 @@
+import type { AiModelCallUsage, AiModelCallUsageRecord } from "../ai-usage"
+import { normalizeAiModelCallUsage } from "../ai-usage"
+import type {
+  AiBillableMeter,
+  AiBillingIdentity,
+  AiCostComponent,
+  AiModelCallCostRecord,
+  AiPriceSource,
+  AiPricingContext,
+  AiRatedModelCallCostRecord,
+  AiUnpriceableModelCallCostRecord,
+  AiUnpriceableReason,
+} from "./types"
+
+const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
+const TOKENS_PER_MILLION = 1_000_000n
+const HALF_MILLION = TOKENS_PER_MILLION / 2n
+const MAX_NUMERIC_TEXT_LENGTH = 128
+const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
+  "tokens.input.total": 0,
+  "tokens.input.uncached": 1,
+  "tokens.input.cacheRead": 2,
+  "tokens.input.cacheWrite": 3,
+  "tokens.output.total": 4,
+  "tokens.output.text": 5,
+  "tokens.output.reasoning": 6,
+}
+const METERS = new Set(Object.keys(METER_ORDER))
+const UNPRICEABLE_REASONS = new Set<AiUnpriceableReason>([
+  "missingBillingIdentity",
+  "missingCatalogEntry",
+  "missingUsageMeter",
+  "unsupportedPricingDimension",
+  "invalidUsageForFormula",
+])
+const CONTEXT_STRING_FIELDS = [
+  "serviceTier",
+  "region",
+  "inferenceGeo",
+  "routedProviderId",
+  "deploymentId",
+  "inferenceProfileId",
+  "mode",
+] as const
+
+export function normalizeAiPricingContext(input: AiPricingContext): AiPricingContext {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new TypeError("[Sixb] AI pricing context must be an object.")
+  }
+  const result: Record<string, string | boolean | number> = {}
+  for (const field of CONTEXT_STRING_FIELDS) {
+    const value = input[field]
+    if (value !== undefined) {
+      assertNonBlank(value, `pricingContext.${field}`)
+      result[field] = value
+    }
+  }
+  if (input.batch !== undefined) {
+    if (typeof input.batch !== "boolean") {
+      throw new TypeError("[Sixb] AI pricingContext.batch must be boolean.")
+    }
+    result.batch = input.batch
+  }
+  if (input.cacheWriteTtlSeconds !== undefined) {
+    if (!Number.isSafeInteger(input.cacheWriteTtlSeconds) || input.cacheWriteTtlSeconds <= 0) {
+      throw new TypeError(
+        "[Sixb] AI pricingContext.cacheWriteTtlSeconds must be a positive safe integer."
+      )
+    }
+    result.cacheWriteTtlSeconds = input.cacheWriteTtlSeconds
+  }
+  return result
+}
+
+export function normalizeAiModelCallCostRecord(
+  input: AiModelCallCostRecord
+): AiModelCallCostRecord {
+  assertNonBlank(input.projectId, "cost record projectId")
+  assertNonBlank(input.usageRecordId, "cost record usageRecordId")
+  const base = {
+    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)
+  throw new TypeError("[Sixb] AI cost status is invalid.")
+}
+
+/** Verify that a normalized valuation's billed quantities describe its usage record. */
+export function aiModelCallCostMatchesUsage(
+  record: AiModelCallCostRecord,
+  usageRecord: AiModelCallUsageRecord
+): boolean {
+  if (record.projectId !== usageRecord.projectId || record.usageRecordId !== usageRecord.id) {
+    return false
+  }
+  if (record.status === "unpriceable") return true
+
+  const usage = normalizeAiModelCallUsage(usageRecord.usage)
+  const components = new Map(record.components.map((component) => [component.meter, component]))
+  return (
+    inputComponentsMatchUsage(components, usage) && outputComponentsMatchUsage(components, usage)
+  )
+}
+
+function inputComponentsMatchUsage(
+  components: ReadonlyMap<AiBillableMeter, AiCostComponent>,
+  usage: AiModelCallUsage
+): boolean {
+  if (usage.inputTokens === undefined) return false
+  const total = components.get("tokens.input.total")
+  const partitions = [
+    ["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))
+
+  if (total) {
+    return presentPartitions.length === 0 && BigInt(total.quantity) === BigInt(usage.inputTokens)
+  }
+  if (presentPartitions.length === 0) return false
+
+  let quantity = 0n
+  for (const [meter, expected] of presentPartitions) {
+    if (expected === undefined) return false
+    const component = components.get(meter)!
+    if (BigInt(component.quantity) !== BigInt(expected)) return false
+    quantity += BigInt(component.quantity)
+  }
+  return quantity === BigInt(usage.inputTokens)
+}
+
+function outputComponentsMatchUsage(
+  components: ReadonlyMap<AiBillableMeter, AiCostComponent>,
+  usage: AiModelCallUsage
+): boolean {
+  if (usage.outputTokens === undefined) return false
+  const total = components.get("tokens.output.total")
+  const partitions = [
+    ["tokens.output.text", usage.textOutputTokens],
+    ["tokens.output.reasoning", usage.reasoningOutputTokens],
+  ] as const
+  const presentPartitions = partitions.filter(([meter]) => components.has(meter))
+
+  if (total) {
+    return presentPartitions.length === 0 && BigInt(total.quantity) === BigInt(usage.outputTokens)
+  }
+  if (presentPartitions.length === 0) return false
+
+  let quantity = 0n
+  for (const [meter, expected] of presentPartitions) {
+    if (expected === undefined) return false
+    const component = components.get(meter)!
+    if (BigInt(component.quantity) !== BigInt(expected)) return false
+    quantity += BigInt(component.quantity)
+  }
+  return quantity === BigInt(usage.outputTokens)
+}
+
+function normalizeRatedCost(
+  input: AiRatedModelCallCostRecord,
+  base: Pick<
+    AiRatedModelCallCostRecord,
+    "projectId" | "usageRecordId" | "pricingContext" | "priceSource" | "ratedAt"
+  >
+): 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 (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)) {
+    throw new TypeError("[Sixb] AI cost total does not equal its component charges.")
+  }
+  return {
+    ...base,
+    status: "rated",
+    billingIdentity,
+    money: { currency: normalizeCurrency(input.money.currency), amountNanos },
+    components,
+  }
+}
+
+function normalizeUnpriceableCost(
+  input: AiUnpriceableModelCallCostRecord,
+  base: Pick<
+    AiUnpriceableModelCallCostRecord,
+    "projectId" | "usageRecordId" | "pricingContext" | "priceSource" | "ratedAt"
+  >
+): AiUnpriceableModelCallCostRecord {
+  if (!UNPRICEABLE_REASONS.has(input.reason)) {
+    throw new TypeError(`[Sixb] AI unpriceable reason '${String(input.reason)}' is invalid.`)
+  }
+  const billingIdentity = input.billingIdentity
+    ? normalizeBillingIdentity(input.billingIdentity)
+    : undefined
+  if (input.reason === "missingBillingIdentity" && billingIdentity !== undefined) {
+    throw new TypeError("[Sixb] AI missingBillingIdentity cannot contain a billing identity.")
+  }
+  if (input.reason !== "missingBillingIdentity" && billingIdentity === undefined) {
+    throw new TypeError(`[Sixb] AI ${input.reason} requires a billing identity.`)
+  }
+  const missingMeters = normalizeMissingMeters(input.missingMeters)
+  if (input.reason === "missingUsageMeter" && !missingMeters) {
+    throw new TypeError("[Sixb] AI missingUsageMeter requires missingMeters.")
+  }
+  return {
+    ...base,
+    status: "unpriceable",
+    ...(billingIdentity ? { billingIdentity } : {}),
+    reason: input.reason,
+    ...(missingMeters ? { missingMeters } : {}),
+  }
+}
+
+function normalizeCostComponent(input: AiCostComponent): AiCostComponent {
+  if (!METERS.has(input.meter)) {
+    throw new TypeError(`[Sixb] AI cost meter '${String(input.meter)}' is invalid.`)
+  }
+  const expected = calculateComponent(input.meter, input.quantity, input.rateAmountNanosPerMillion)
+  if (expected.chargeAmountNanos !== input.chargeAmountNanos) {
+    throw new TypeError(`[Sixb] AI cost component '${input.meter}' charge is invalid.`)
+  }
+  return expected
+}
+
+function calculateComponent(
+  meter: AiBillableMeter,
+  quantity: number | string,
+  rateAmountNanosPerMillion: string
+): AiCostComponent {
+  const normalizedQuantity = parseQuantity(quantity, `${meter} quantity`)
+  const rate = parseNonnegativeInt64(rateAmountNanosPerMillion, `${meter} rate`)
+  const charge = (normalizedQuantity * rate + HALF_MILLION) / TOKENS_PER_MILLION
+  assertSignedInt64(charge, `${meter} charge`)
+  return {
+    meter,
+    quantity: normalizedQuantity.toString(),
+    rateAmountNanosPerMillion: rate.toString(),
+    chargeAmountNanos: charge.toString(),
+  }
+}
+
+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") }
+}
+
+function normalizeBillingIdentity(input: AiBillingIdentity): AiBillingIdentity {
+  assertNonBlank(input.providerId, "billingIdentity.providerId")
+  assertNonBlank(input.modelId, "billingIdentity.modelId")
+  return { providerId: input.providerId, modelId: input.modelId }
+}
+
+function normalizeMissingMeters(
+  input: readonly AiBillableMeter[] | undefined
+): readonly AiBillableMeter[] | undefined {
+  if (!input?.length) return undefined
+  const result = [...new Set(input)]
+  for (const meter of result) {
+    if (!METERS.has(meter)) throw new TypeError(`[Sixb] AI missing meter '${meter}' is invalid.`)
+  }
+  return result.sort((left, right) => METER_ORDER[left] - METER_ORDER[right])
+}
+
+function sumComponents(components: readonly AiCostComponent[]): string {
+  let total = 0n
+  for (const component of components) {
+    total += parseNonnegativeInt64(component.chargeAmountNanos, "component charge")
+    assertSignedInt64(total, "cost total")
+  }
+  return total.toString()
+}
+
+function parseQuantity(value: number | string, field: string): bigint {
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new TypeError(`[Sixb] AI ${field} must be a non-negative safe integer.`)
+    }
+    return BigInt(value)
+  }
+  return parseNonnegativeInt64(value, field)
+}
+
+function parseNonnegativeInt64(value: string, field: string): bigint {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > MAX_NUMERIC_TEXT_LENGTH ||
+    !/^\d+$/.test(value)
+  ) {
+    throw new TypeError(`[Sixb] AI ${field} must be a non-negative integer string.`)
+  }
+  const parsed = BigInt(value)
+  assertSignedInt64(parsed, field)
+  return parsed
+}
+
+function compareComponents(left: AiCostComponent, right: AiCostComponent): number {
+  return METER_ORDER[left.meter] - METER_ORDER[right.meter]
+}
+
+function normalizeCurrency(value: string): string {
+  if (!/^[A-Z]{3}$/.test(value)) {
+    throw new TypeError("[Sixb] AI currency must be a three-letter uppercase code.")
+  }
+  return value
+}
+
+function assertSignedInt64(value: bigint, field: string): void {
+  if (value < 0n || value > SIGNED_INT64_MAX) {
+    throw new TypeError(`[Sixb] AI ${field} exceeds the signed 64-bit range.`)
+  }
+}
+
+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 cloneDate(value: Date, field: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`[Sixb] AI ${field} must be a valid Date.`)
+  }
+  return new Date(value)
+}

package/src/storage/in-memory/index.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks"
 import { InMemoryActionRunStorage } from "../action-runs"
 import { type AgentStorage, InMemoryAgentStorage } from "../agents"
+import { type AiAccountingAttribution, type AiCostStorage, InMemoryAiCostStorage } from "../ai-cost"
 import { type AiUsageStorage, InMemoryAiUsageStorage } from "../ai-usage"
 import { type AuthStorage, InMemoryAuthStorage } from "../auth"
 import {
@@ -67,6 +68,9 @@ export class InMemoryStorage implements Storage {
   private readonly executionStorage = new InMemoryExecutionStorage(this.authStorage)
   private readonly agentStorage = new InMemoryAgentStorage(this.executionStorage)
   private readonly aiUsageStorage = new InMemoryAiUsageStorage(this.executionStorage)
+  private readonly aiCostStorage = new InMemoryAiCostStorage(this.aiUsageStorage, {
+    resolve: (input) => this.resolveAiAccountingAttribution(input),
+  })
   private readonly actionRunStorage = new InMemoryActionRunStorage(this.executionStorage)
   private readonly syncRunStorage = new InMemorySyncRunStorage(this.executionStorage)
   private readonly pipelineRunStorage = new InMemoryPipelineRunStorage(this.executionStorage)
@@ -83,6 +87,7 @@ export class InMemoryStorage implements Storage {
   readonly executions: ExecutionStorage
   readonly agents: AgentStorage
   readonly aiUsage: AiUsageStorage
+  readonly aiCosts: AiCostStorage
   readonly actionRuns: InMemoryActionRunStorage
   readonly syncRuns: SyncRunStorage
   readonly pipelineRuns: PipelineRunStorage
@@ -108,6 +113,7 @@ export class InMemoryStorage implements Storage {
     this.executions = createOperationScopedFacade(this.executionStorage, scope)
     this.agents = createAgentOperationScope(this.agentStorage, scope)
     this.aiUsage = createOperationScopedFacade(this.aiUsageStorage, scope)
+    this.aiCosts = createOperationScopedFacade(this.aiCostStorage, scope)
     this.actionRuns = createOperationScopedFacade(this.actionRunStorage, scope)
     this.syncRuns = createOperationScopedFacade(this.syncRunStorage, scope)
     this.pipelineRuns = createOperationScopedFacade(this.pipelineRunStorage, scope)
@@ -135,6 +141,46 @@ export class InMemoryStorage implements Storage {
     registerInMemoryStorageTestingAdapter(this, { snapshot: () => this.snapshot() })
   }
 
+  private async resolveAiAccountingAttribution(input: {
+    readonly projectId: string
+    readonly executionId: string
+  }): Promise<AiAccountingAttribution | undefined> {
+    const execution = await this.executionStorage.getById({
+      projectId: input.projectId,
+      id: input.executionId,
+    })
+    if (!execution || execution.executor.type !== "agent") return undefined
+    const directRun = await this.agentStorage.runs.getById({
+      projectId: input.projectId,
+      id: execution.executor.runId,
+    })
+    if (directRun) {
+      return {
+        kind: "agent",
+        agentId: directRun.agentId,
+        agentRunId: directRun.id,
+        threadId: directRun.threadId,
+      }
+    }
+    const agentRun = await this.workflowRunStorage.agentNodes.getByNodeRunId({
+      projectId: input.projectId,
+      nodeRunId: execution.executor.runId,
+    })
+    if (!agentRun) return undefined
+    const node = await this.workflowRunStorage.nodes.getById({
+      projectId: input.projectId,
+      id: agentRun.nodeRunId,
+    })
+    if (!node) return undefined
+    return {
+      kind: "workflowAgent",
+      agentId: agentRun.agentId,
+      nodeRunId: agentRun.nodeRunId,
+      workflowId: node.workflowId,
+      workflowRunId: node.workflowRunId,
+    }
+  }
+
   private readonly transactionScope = new AsyncLocalStorage<object>()
   private readonly activeTransactionTokens = new WeakSet<object>()
   private readonly materializationLifecycles = new WeakMap<
@@ -250,6 +296,7 @@ export class InMemoryStorage implements Storage {
       executions: this.executionStorage,
       agents: this.agentStorage,
       aiUsage: this.aiUsageStorage,
+      aiCosts: this.aiCostStorage,
       actionRuns: this.actionRunStorage,
       syncRuns: this.syncRunStorage,
       pipelineRuns: this.pipelineRunStorage,
@@ -276,6 +323,7 @@ export class InMemoryStorage implements Storage {
       executions: this.executionStorage.snapshot(),
       agents: this.agentStorage.snapshot(),
       aiUsage: this.aiUsageStorage.snapshot(),
+      aiCosts: this.aiCostStorage.snapshot(),
       actionRuns: this.actionRunStorage.snapshot(),
       syncRuns: this.syncRunStorage.snapshot(),
       pipelineRuns: this.pipelineRunStorage.snapshot(),
@@ -297,6 +345,7 @@ export class InMemoryStorage implements Storage {
     this.executionStorage.restore(snapshot.executions)
     this.agentStorage.restore(snapshot.agents)
     this.aiUsageStorage.restore(snapshot.aiUsage)
+    this.aiCostStorage.restore(snapshot.aiCosts)
     this.actionRunStorage.restore(snapshot.actionRuns)
     this.syncRunStorage.restore(snapshot.syncRuns)
     this.pipelineRunStorage.restore(snapshot.pipelineRuns)
@@ -318,6 +367,7 @@ export interface InMemoryStorageSnapshot {
   readonly executions: ReturnType<InMemoryExecutionStorage["snapshot"]>
   readonly agents: ReturnType<InMemoryAgentStorage["snapshot"]>
   readonly aiUsage: ReturnType<InMemoryAiUsageStorage["snapshot"]>
+  readonly aiCosts: ReturnType<InMemoryAiCostStorage["snapshot"]>
   readonly actionRuns: ReturnType<InMemoryActionRunStorage["snapshot"]>
   readonly syncRuns: ReturnType<InMemorySyncRunStorage["snapshot"]>
   readonly pipelineRuns: ReturnType<InMemoryPipelineRunStorage["snapshot"]>

package/src/storage/index.ts

@@ -52,6 +52,9 @@ export {
   isTerminalActionRun,
 } from "./action-runs"
 export type {
+  AgentContextCheckpointReason,
+  AgentContextCheckpointRecord,
+  AgentContextCheckpointStore,
   AgentExecutionStatus,
   AgentMessageRecord,
   AgentMessageRole,
@@ -72,8 +75,10 @@ export type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
   ListAgentMessagesInput,
@@ -93,6 +98,38 @@ export {
   coerceAgentRunFinishReason,
   InMemoryAgentStorage,
 } from "./agents"
+export type {
+  AiAccountingAgentBreakdown,
+  AiAccountingAggregate,
+  AiAccountingAttribution,
+  AiAccountingBucket,
+  AiAccountingModelBreakdown,
+  AiAccountingOverview,
+  AiAccountingRange,
+  AiAccountingTimeBucket,
+  AiAccountingWorkflowBreakdown,
+  AiBillableMeter,
+  AiBillingIdentity,
+  AiCostComponent,
+  AiCostStorage,
+  AiCostStorageErrorCode,
+  AiCostSummary,
+  AiModelCallAccountingItem,
+  AiModelCallCostRecord,
+  AiMoney,
+  AiPriceSource,
+  AiPricingContext,
+  AiRatedModelCallCostRecord,
+  AiUnpriceableModelCallCostRecord,
+  AiUnpriceableReason,
+  InMemoryAiAccountingAttributionSource,
+  InMemoryAiCostStorageSnapshot,
+  ListAiModelCallAccountingInput,
+  ListAiModelCallAccountingResult,
+  QueryAiAccountingOverviewInput,
+  SummarizeAiCostExecutionsInput,
+} from "./ai-cost"
+export { AiCostStorageError, InMemoryAiCostStorage } from "./ai-cost"
 export type {
   AiModelCallUsage,
   AiModelCallUsageInput,

package/src/storage/ontology/in-memory/materializations.ts

@@ -588,6 +588,7 @@ export class InMemoryOntologyMaterializationStorage implements OntologyMateriali
             projectId,
             ref: item.ref,
             value: item.value,
+            editedAt: { ...item.editedAt },
             lastCommitId: item.lastCommitId,
             updatedAt: item.updatedAt,
           })

package/src/storage/ontology/materializations.ts

@@ -26,6 +26,8 @@ import type { StoredSourceLinkAssertion, StoredSourceObjectAssertion } from "./s
 export interface StoredObjectOverride {
   readonly ref: OntologyObjectRef
   readonly value: ObjectOverride
+  /** Per-property Action/runtime edit time. Legacy rows fall back to `updatedAt`. */
+  readonly editedAt?: Readonly<Record<string, string>>
   readonly lastCommitId: string
   readonly updatedAt: string
 }
@@ -160,6 +162,7 @@ export interface MaterializationPlanHeader {
 export interface ExactObjectOverrideWrite {
   readonly ref: OntologyObjectRef
   readonly value: ObjectOverride
+  readonly editedAt: Readonly<Record<string, string>>
   readonly expectedLastCommitId: string | null
   readonly lastCommitId: string
   readonly updatedAt: string

package/src/storage/operation-scope.ts

@@ -215,6 +215,7 @@ export function createAgentOperationScope<T extends AgentStorage>(
     threads: createOperationScopedFacade(target.threads, scope),
     runs: createOperationScopedFacade(target.runs, scope),
     messages: createOperationScopedFacade(target.messages, scope),
+    checkpoints: createOperationScopedFacade(target.checkpoints, scope),
   }) as T
 }
 

package/src/storage/types.ts

@@ -1,5 +1,6 @@
 import type { ActionRunStorage } from "./action-runs"
 import type { AgentStorage } from "./agents"
+import type { AiCostStorage } from "./ai-cost"
 import type { AiUsageStorage } from "./ai-usage"
 import type { AuthStorage } from "./auth"
 import type { ConnectorConnectionStorage } from "./connector-connections"
@@ -293,6 +294,7 @@ export interface Storage {
   auth?: AuthStorage
   agents?: AgentStorage
   aiUsage?: AiUsageStorage
+  aiCosts?: AiCostStorage
   actionRuns?: ActionRunStorage
   syncRuns?: SyncRunStorage
   pipelineRuns?: PipelineRunStorage