@sixb/core 0.1.1 → 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/ai-usage/errors.ts

@@ -0,0 +1,13 @@
+export type AiUsageStorageErrorCode = "duplicate_id" | "missing_execution"
+
+/** Storage failure specific to the AI model-call usage ledger. */
+export class AiUsageStorageError extends Error {
+  readonly name = "AiUsageStorageError"
+
+  constructor(
+    readonly code: AiUsageStorageErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

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

@@ -0,0 +1,162 @@
+import type { ExecutionStorage } from "../executions"
+import { AiUsageStorageError } from "./errors"
+import { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+import type {
+  AiModelCallUsageRecord,
+  AiUsageExecutionSummary,
+  AiUsageStorage,
+  RecordAiModelCallInput,
+  RecordAiModelCallResult,
+  SummarizeAiUsageExecutionInput,
+  SummarizeAiUsageExecutionsInput,
+} from "./types"
+import { aggregateAiModelCallUsage } from "./usage"
+
+export interface InMemoryAiUsageGroupRow {
+  readonly projectId: string
+  readonly usageRecordId: string
+  readonly groupId: string
+  readonly occurredAt: Date
+}
+
+export interface InMemoryAiUsageStorageSnapshot {
+  readonly records: Map<string, AiModelCallUsageRecord>
+  readonly recordKeysByIdempotencyKey: Map<string, string>
+  readonly groupRows: Map<string, InMemoryAiUsageGroupRow>
+}
+
+/** In-memory model-call ledger used by development runtimes and storage contract tests. */
+export class InMemoryAiUsageStorage implements AiUsageStorage {
+  private readonly records = new Map<string, AiModelCallUsageRecord>()
+  private readonly recordKeysByIdempotencyKey = new Map<string, string>()
+  private readonly groupRows = new Map<string, InMemoryAiUsageGroupRow>()
+
+  constructor(private readonly executions: Pick<ExecutionStorage, "getById">) {}
+
+  async recordModelCall(input: RecordAiModelCallInput): Promise<RecordAiModelCallResult> {
+    const record = normalizeAiModelCallRecord(input)
+    await this.assertExecutionExists(record.projectId, record.executionId)
+    const idempotencyKey = modelCallIdempotencyKey(record)
+    const existingRecordKey = this.recordKeysByIdempotencyKey.get(idempotencyKey)
+    if (existingRecordKey !== undefined) {
+      const existing = this.records.get(existingRecordKey)
+      if (!existing) {
+        throw new Error("[Sixb] In-memory AI usage idempotency index is inconsistent.")
+      }
+      return { record: structuredClone(existing), created: false }
+    }
+
+    const recordKey = modelCallRecordKey(record.projectId, record.id)
+    if (this.records.has(recordKey)) {
+      throw new AiUsageStorageError(
+        "duplicate_id",
+        `[Sixb] AI usage record '${record.id}' already exists for project '${record.projectId}'.`
+      )
+    }
+
+    this.records.set(recordKey, structuredClone(record))
+    this.recordKeysByIdempotencyKey.set(idempotencyKey, recordKey)
+    for (const groupId of record.requesterGroupIds) {
+      const row: InMemoryAiUsageGroupRow = {
+        projectId: record.projectId,
+        usageRecordId: record.id,
+        groupId,
+        occurredAt: record.occurredAt,
+      }
+      this.groupRows.set(groupRowKey(row), row)
+    }
+
+    return { record: structuredClone(record), created: true }
+  }
+
+  async summarizeExecution(
+    input: SummarizeAiUsageExecutionInput
+  ): Promise<AiUsageExecutionSummary> {
+    const [summary] = await this.summarizeExecutions({
+      projectId: input.projectId,
+      executionIds: [input.executionId],
+    })
+    return summary!
+  }
+
+  async summarizeExecutions(
+    input: SummarizeAiUsageExecutionsInput
+  ): Promise<readonly AiUsageExecutionSummary[]> {
+    if (typeof input.projectId !== "string" || input.projectId.trim().length === 0) {
+      throw new TypeError("[Sixb] AI usage projectId must be nonblank.")
+    }
+
+    const usageByExecutionId = new Map<string, AiModelCallUsageRecord["usage"][]>()
+    for (const executionId of input.executionIds) {
+      assertAiUsageExecutionId(executionId)
+      usageByExecutionId.set(executionId, [])
+    }
+    if (usageByExecutionId.size === 0) return []
+
+    for (const record of this.records.values()) {
+      if (record.projectId !== input.projectId) continue
+      usageByExecutionId.get(record.executionId)?.push(record.usage)
+    }
+
+    return input.executionIds.map((executionId) => {
+      const usages = usageByExecutionId.get(executionId) ?? []
+      return {
+        modelCallCount: usages.length,
+        usage: aggregateAiModelCallUsage(usages),
+      }
+    })
+  }
+
+  snapshot(): InMemoryAiUsageStorageSnapshot {
+    return structuredClone({
+      records: this.records,
+      recordKeysByIdempotencyKey: this.recordKeysByIdempotencyKey,
+      groupRows: this.groupRows,
+    })
+  }
+
+  restore(snapshot: InMemoryAiUsageStorageSnapshot): void {
+    replaceMap(this.records, snapshot.records)
+    replaceMap(this.recordKeysByIdempotencyKey, snapshot.recordKeysByIdempotencyKey)
+    replaceMap(this.groupRows, snapshot.groupRows)
+  }
+
+  private async assertExecutionExists(projectId: string, executionId: string): Promise<void> {
+    const execution = await this.executions.getById({ projectId, id: executionId })
+    if (execution) return
+    throw new AiUsageStorageError(
+      "missing_execution",
+      `[Sixb] AI usage execution '${executionId}' does not exist in project '${projectId}'.`
+    )
+  }
+}
+
+function modelCallRecordKey(projectId: string, id: string): string {
+  return JSON.stringify([projectId, id])
+}
+
+function modelCallIdempotencyKey(
+  record: Pick<
+    AiModelCallUsageRecord,
+    "projectId" | "executionId" | "attempt" | "callId" | "responseId"
+  >
+): string {
+  return JSON.stringify([
+    record.projectId,
+    record.executionId,
+    record.attempt,
+    record.callId,
+    record.responseId,
+  ])
+}
+
+function groupRowKey(row: InMemoryAiUsageGroupRow): string {
+  return JSON.stringify([row.projectId, row.usageRecordId, row.groupId])
+}
+
+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-usage/index.ts

@@ -0,0 +1,21 @@
+export type { AiUsageStorageErrorCode } from "./errors"
+export { AiUsageStorageError } from "./errors"
+export type {
+  InMemoryAiUsageGroupRow,
+  InMemoryAiUsageStorageSnapshot,
+} from "./in-memory"
+export { InMemoryAiUsageStorage } from "./in-memory"
+export { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+export type {
+  AiModelCallUsage,
+  AiModelCallUsageInput,
+  AiModelCallUsageRecord,
+  AiUsageExecutionSummary,
+  AiUsageReportingStatus,
+  AiUsageStorage,
+  RecordAiModelCallInput,
+  RecordAiModelCallResult,
+  SummarizeAiUsageExecutionInput,
+  SummarizeAiUsageExecutionsInput,
+} from "./types"
+export { aggregateAiModelCallUsage, normalizeAiModelCallUsage } from "./usage"

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

@@ -0,0 +1,74 @@
+import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { assertJsonValue, isPlainRecord } from "../../json"
+import type { AiModelCallUsageRecord, RecordAiModelCallInput } from "./types"
+import { normalizeAiModelCallUsage } from "./usage"
+
+/** Validate and defensively snapshot one provider-neutral model-call ledger input. */
+export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiModelCallUsageRecord {
+  assertNonBlank(input.id, "id")
+  assertNonBlank(input.projectId, "projectId")
+  assertAiUsageExecutionId(input.executionId)
+  assertPositiveSafeInteger(input.attempt, "attempt")
+  assertNonBlank(input.callId, "callId")
+  assertNonBlank(input.providerId, "providerId")
+  assertNonBlank(input.requestedModelId, "requestedModelId")
+  if (input.responseModelId !== undefined) {
+    assertNonBlank(input.responseModelId, "responseModelId")
+  }
+  assertNonBlank(input.responseId, "responseId")
+
+  const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
+  const recordedAt = cloneValidDate(input.recordedAt ?? new Date(), "recordedAt")
+  const requesterGroupIds = normalizeRequesterGroupIds(input.requesterGroupIds)
+  const rawUsage = cloneRawUsage(input.rawUsage)
+
+  return {
+    id: input.id,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    attempt: input.attempt,
+    callId: input.callId,
+    requesterGroupIds,
+    providerId: input.providerId,
+    requestedModelId: input.requestedModelId,
+    ...(input.responseModelId === undefined ? {} : { responseModelId: input.responseModelId }),
+    responseId: input.responseId,
+    usage: normalizeAiModelCallUsage(input.usage),
+    ...(rawUsage === undefined ? {} : { rawUsage }),
+    occurredAt,
+    recordedAt,
+  }
+}
+
+/** Validate a durable execution reference at storage and query boundaries. */
+export function assertAiUsageExecutionId(executionId: string): void {
+  assertNonBlank(executionId, "executionId")
+}
+
+function cloneRawUsage(rawUsage: RecordAiModelCallInput["rawUsage"]) {
+  if (rawUsage === undefined) return undefined
+  if (!isPlainRecord(rawUsage)) {
+    throw new TypeError("[Sixb] AI usage rawUsage must be a JSON object.")
+  }
+  assertJsonValue(rawUsage, "AI usage rawUsage")
+  return structuredClone(rawUsage)
+}
+
+function assertNonBlank(value: string, field: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be nonblank.`)
+  }
+}
+
+function assertPositiveSafeInteger(value: number, field: string): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be a positive safe integer.`)
+  }
+}
+
+function cloneValidDate(value: Date, field: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`[Sixb] AI usage ${field} must be a valid Date.`)
+  }
+  return new Date(value)
+}