@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/task/store.ts

@@ -0,0 +1,287 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { ArtifactRef, FusionEvent, OutboxRow, OutboxState, TaskId } from '../contracts.js'
+import { ArtifactId } from '../contracts.js'
+import { digestOf, sha256Hex } from '../digest.js'
+import { CHECKSUM_MISMATCH, EVENT_CONFLICT, FLUSH_FAILED, FusionError, REVISION_CONFLICT, STORE_MIGRATION_REQUIRED } from '../errors.js'
+import { reduce, reduceAll } from './reducer.js'
+import type { PersistedTask, TaskState } from './state.js'
+
+export interface StoreIo {
+  existsSync(path: string): boolean
+  mkdirSync(path: string): void
+  readFileSync(path: string): string
+  writeFileSync(path: string, data: string | Uint8Array): void
+  renameSync(from: string, to: string): void
+  rmSync(path: string): void
+}
+
+export const nodeIo: StoreIo = {
+  existsSync,
+  mkdirSync: path => mkdirSync(path, { recursive: true }),
+  readFileSync: path => readFileSync(path, 'utf8'),
+  writeFileSync: (path, data) => writeFileSync(path, data),
+  renameSync,
+  rmSync: path => rmSync(path, { force: true }),
+}
+
+export interface ArtifactRecord extends ArtifactRef {
+  readonly storageRef: string
+}
+
+export const STORE_PROJECTION_VERSION = 2
+
+export interface DiskSnapshot {
+  readonly projectionVersion: typeof STORE_PROJECTION_VERSION
+  readonly checksum: string
+  readonly persisted: PersistedTask
+  readonly artifacts: readonly ArtifactRecord[]
+}
+
+/** The reducer and review producer share this port across file and transactional stores. */
+export type FusionStore = Pick<FileFusionStore,
+  'load' | 'replay' | 'create' | 'transact' | 'append' | 'putArtifact' |
+  'prepareOutbox' | 'advanceOutbox' | 'outbox' | 'artifacts'>
+
+export class FileFusionStore {
+  readonly #memory = new Map<TaskId, DiskSnapshot>()
+
+  constructor(
+    readonly root: string,
+    readonly io: StoreIo = nodeIo,
+  ) {}
+
+  load(taskId: TaskId): TaskState | undefined {
+    return this.#read(taskId)?.persisted.state
+  }
+
+  replay(taskId: TaskId): TaskState {
+    const snap = this.#require(taskId)
+    return reduceAll(snap.persisted.events)
+  }
+
+  create(event: Extract<FusionEvent, { type: 'task/created' }>): TaskState {
+    if (this.load(event.taskId)) throw new FusionError(EVENT_CONFLICT, 'task exists')
+    const state = reduce(undefined, event)
+    this.#persist(event.taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: { state, events: [event], outbox: [] },
+      artifacts: [],
+    })
+    return this.#require(event.taskId).persisted.state
+  }
+
+  transact(
+    taskId: TaskId,
+    expectedSeq: number,
+    mutate: (current: PersistedTask) => { events?: readonly FusionEvent[]; outbox?: readonly OutboxRow[] },
+  ): TaskState {
+    const current = this.#require(taskId)
+    if (current.persisted.state.seq !== expectedSeq) {
+      throw new FusionError(EVENT_CONFLICT, `expected seq ${expectedSeq}, have ${current.persisted.state.seq}`)
+    }
+    const patch = mutate(current.persisted)
+    let state = current.persisted.state
+    const nextEvents = [...current.persisted.events]
+    for (const event of patch.events ?? []) {
+      if (state.appliedEventIds.includes(event.id)) continue
+      state = reduce(state, event)
+      nextEvents.push(event)
+    }
+    this.#persist(taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: {
+        state,
+        events: nextEvents,
+        outbox: patch.outbox ?? current.persisted.outbox,
+      },
+      artifacts: current.artifacts,
+    })
+    return this.#require(taskId).persisted.state
+  }
+
+  append(taskId: TaskId, expectedRevision: number, events: readonly FusionEvent[]): TaskState {
+    const current = this.#require(taskId)
+    if (current.persisted.state.revision !== expectedRevision) {
+      throw new FusionError(REVISION_CONFLICT, `expected revision ${expectedRevision}, have ${current.persisted.state.revision}`)
+    }
+    let state = current.persisted.state
+    const nextEvents = [...current.persisted.events]
+    for (const event of events) {
+      if (state.appliedEventIds.includes(event.id)) continue
+      state = reduce(state, event)
+      nextEvents.push(event)
+    }
+    this.#persist(taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: { state, events: nextEvents, outbox: current.persisted.outbox },
+      artifacts: current.artifacts,
+    })
+    return this.#require(taskId).persisted.state
+  }
+
+  putArtifact(taskId: TaskId, bytes: Uint8Array, mediaType: string): ArtifactRef {
+    const current = this.#require(taskId)
+    const digest = sha256Hex(bytes)
+    const dir = this.#taskDir(taskId)
+    this.io.mkdirSync(join(dir, 'artifacts'))
+    const finalPath = join(dir, 'artifacts', digest)
+    const partPath = `${finalPath}.part`
+    this.io.writeFileSync(partPath, bytes)
+    this.io.renameSync(partPath, finalPath)
+    const record: ArtifactRecord = {
+      id: ArtifactId(digest),
+      digest,
+      ownerTaskId: taskId,
+      mediaType,
+      bytes: bytes.byteLength,
+      storageRef: finalPath,
+    }
+    this.#persist(taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: current.persisted,
+      artifacts: [...current.artifacts.filter(item => item.digest !== digest), record],
+    })
+    return record
+  }
+
+  prepareOutbox(row: OutboxRow): OutboxRow {
+    const current = this.#require(row.taskId)
+    const existing = current.persisted.outbox.find(item => item.operationId === row.operationId)
+    if (existing) return existing
+    this.#persist(row.taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: { ...current.persisted, outbox: [...current.persisted.outbox, { ...row, state: 'prepared' }] },
+      artifacts: current.artifacts,
+    })
+    return this.outbox(row.taskId).find(item => item.operationId === row.operationId)!
+  }
+
+  advanceOutbox(taskId: TaskId, operationId: string, from: OutboxState, to: OutboxState, patch: Partial<OutboxRow> = {}): OutboxRow {
+    const current = this.#require(taskId)
+    const next = current.persisted.outbox.map(row => {
+      if (row.operationId !== operationId) return row
+      if (row.state !== from) throw new FusionError(EVENT_CONFLICT, `outbox ${operationId} is ${row.state}, not ${from}`)
+      return { ...row, ...patch, state: to }
+    })
+    if (!next.some(row => row.operationId === operationId)) {
+      throw new FusionError(EVENT_CONFLICT, `outbox ${operationId} missing`)
+    }
+    this.#persist(taskId, {
+      projectionVersion: STORE_PROJECTION_VERSION,
+      checksum: '',
+      persisted: { ...current.persisted, outbox: next },
+      artifacts: current.artifacts,
+    })
+    return this.outbox(taskId).find(row => row.operationId === operationId)!
+  }
+
+  outbox(taskId: TaskId): readonly OutboxRow[] {
+    return this.#require(taskId).persisted.outbox
+  }
+
+  artifacts(taskId: TaskId): readonly ArtifactRecord[] {
+    return this.#require(taskId).artifacts
+  }
+
+  #taskDir(taskId: TaskId): string {
+    return join(this.root, 'tasks', taskId)
+  }
+
+  #read(taskId: TaskId): DiskSnapshot | undefined {
+    const cached = this.#memory.get(taskId)
+    if (cached) return cached
+    const path = join(this.#taskDir(taskId), 'snapshot.json')
+    if (!this.io.existsSync(path)) return undefined
+    const raw = this.io.readFileSync(path)
+    const parsed = decodeStoreSnapshot(raw, taskId)
+    this.#memory.set(taskId, parsed)
+    return parsed
+  }
+
+  #require(taskId: TaskId): DiskSnapshot {
+    const snap = this.#read(taskId)
+    if (!snap) throw new FusionError(EVENT_CONFLICT, `unknown task ${taskId}`)
+    return snap
+  }
+
+  #persist(taskId: TaskId, next: DiskSnapshot): void {
+    const checksum = digestOf({ persisted: next.persisted, artifacts: next.artifacts })
+    const snapshot: DiskSnapshot = { ...next, projectionVersion: STORE_PROJECTION_VERSION, checksum }
+    const dir = this.#taskDir(taskId)
+    this.io.mkdirSync(dir)
+    const finalPath = join(dir, 'snapshot.json')
+    const tmpPath = `${finalPath}.tmp`
+    try {
+      this.io.writeFileSync(tmpPath, `${JSON.stringify(snapshot, null, 2)}\n`)
+      this.io.renameSync(tmpPath, finalPath)
+    } catch (error) {
+      try {
+        this.io.rmSync(tmpPath)
+      } catch {
+        /* ignore */
+      }
+      throw new FusionError(FLUSH_FAILED, error instanceof Error ? error.message : 'flush failed')
+    }
+    this.#memory.set(taskId, snapshot)
+  }
+}
+
+/** Validate before either backend admits a persisted execution projection. */
+export function decodeStoreSnapshot(raw: string, taskId: TaskId): DiskSnapshot {
+  let parsed: DiskSnapshot
+  try { parsed = JSON.parse(raw) as DiskSnapshot } catch {
+    throw new FusionError(STORE_MIGRATION_REQUIRED, `snapshot for ${taskId} is not a JSON store document`)
+  }
+  if (!parsed || typeof parsed !== 'object' || !parsed.persisted) {
+    throw new FusionError(STORE_MIGRATION_REQUIRED, `snapshot for ${taskId} is not a store document`)
+  }
+  if (parsed.checksum !== digestOf({ persisted: parsed.persisted, artifacts: parsed.artifacts })) {
+    throw new FusionError(CHECKSUM_MISMATCH, `corrupt snapshot for ${taskId}`)
+  }
+  requireStorageProjectionVersion(parsed)
+  const state = parsed.persisted.state
+  const control = state?.control
+  if (!control || !['running', 'paused', 'stop-requested', 'cancelled', 'completed'].includes(control.mode)
+    || !Array.isArray(control.pendingApprovalIds) || !control.pendingApprovalIds.every(id => typeof id === 'string')
+    || typeof control.budgetBlocked !== 'boolean' || typeof control.recovering !== 'boolean'
+    || typeof control.outcomeUnknown !== 'boolean'
+    || !Array.isArray(state.pendingApprovalIds) || !state.pendingApprovals
+    || !Array.isArray(state.appliedEventIds) || !Array.isArray(state.ignoredReviewResults)
+    || !Array.isArray(state.staleValidations) || !Number.isSafeInteger(state.reviewGeneration)
+    || !Array.isArray(parsed.persisted.events) || !Array.isArray(parsed.persisted.outbox)
+    || !Array.isArray(parsed.artifacts) || state.taskId !== taskId) {
+    throw new FusionError(STORE_MIGRATION_REQUIRED, `snapshot for ${taskId} has an incomplete execution projection`)
+  }
+  return parsed
+}
+
+export function requireStorageProjectionVersion(raw: unknown): asserts raw is DiskSnapshot {
+  if (!raw || typeof raw !== 'object') throw new FusionError(STORE_MIGRATION_REQUIRED, 'INVALID_STORE_DOCUMENT')
+  if ((raw as { projectionVersion?: number }).projectionVersion !== STORE_PROJECTION_VERSION) {
+    throw new FusionError(STORE_MIGRATION_REQUIRED, 'STORE_MIGRATION_REQUIRED')
+  }
+}
+
+export function failingRenameIo(base: StoreIo, failOnce = true): StoreIo {
+  let failed = false
+  return {
+    ...base,
+    renameSync(from, to) {
+      if (dirname(to).endsWith('artifacts')) {
+        base.renameSync(from, to)
+        return
+      }
+      if (!failed || !failOnce) {
+        failed = true
+        throw new Error('injected flush failure')
+      }
+      base.renameSync(from, to)
+    },
+  }
+}

package/src/usage/budget.ts

@@ -0,0 +1,88 @@
+import { FusionError, SPEND_UNAUTHORIZED } from '../errors.js'
+import type { UsdDecimal } from '../contracts.js'
+
+export interface SpendingAuthorization {
+  schemaVersion: 1
+  approved: boolean
+  authorizationId: string | null
+  currency: string
+  maximumTotal: string | null
+  allowedModels: readonly string[]
+  expiresAt: string | null
+  approvedBy: string | null
+}
+
+export interface Reservation {
+  readonly authorizationId: string
+  readonly reserved: UsdDecimal
+  readonly remaining: UsdDecimal | null
+}
+
+export class BudgetLedger {
+  #spent = 0
+  #reserved = 0
+
+  constructor(readonly authorization: SpendingAuthorization) {}
+
+  assertAuthorized(model?: string): void {
+    if (!this.authorization.approved || !this.authorization.authorizationId) {
+      throw new FusionError(SPEND_UNAUTHORIZED, 'no approved spending authorization')
+    }
+    if (model && this.authorization.allowedModels.length && !this.authorization.allowedModels.includes(model)) {
+      throw new FusionError(SPEND_UNAUTHORIZED, `model ${model} is not on the authorization allowlist`)
+    }
+  }
+
+  reserve(estimatedUsd: number, model?: string): Reservation {
+    this.assertAuthorized(model)
+    if (!Number.isFinite(estimatedUsd) || estimatedUsd < 0) throw new TypeError('estimatedUsd must be finite and nonnegative')
+    const cap = this.authorization.maximumTotal === null ? null : Number(this.authorization.maximumTotal)
+    if (cap !== null && this.#spent + this.#reserved + estimatedUsd > cap) {
+      throw new FusionError(SPEND_UNAUTHORIZED, 'budget reservation would exceed maximumTotal')
+    }
+    this.#reserved += estimatedUsd
+    const remaining = cap === null ? null : (cap - this.#spent - this.#reserved).toString()
+    return {
+      authorizationId: this.authorization.authorizationId!,
+      reserved: estimatedUsd.toString() as UsdDecimal,
+      remaining: remaining as UsdDecimal | null,
+    }
+  }
+
+  settle(reserved: Reservation, actualUsd: number | null): void {
+    const reservedN = Number(reserved.reserved)
+    if (actualUsd === null) {
+      return
+    }
+    this.#reserved = Math.max(0, this.#reserved - reservedN)
+    if (!Number.isFinite(actualUsd) || actualUsd < 0) throw new TypeError('actualUsd must be finite and nonnegative')
+    const cap = this.authorization.maximumTotal === null ? null : Number(this.authorization.maximumTotal)
+    if (cap !== null && this.#spent + actualUsd > cap) {
+      throw new FusionError(SPEND_UNAUTHORIZED, 'actual spend would exceed maximumTotal')
+    }
+    this.#spent += actualUsd
+  }
+
+  get reserved(): number {
+    return this.#reserved
+  }
+
+  get spent(): number {
+    return this.#spent
+  }
+}
+
+export function loadSpendingAuthorization(raw: unknown): SpendingAuthorization {
+  const value = raw as SpendingAuthorization
+  if (!value || value.schemaVersion !== 1) throw new TypeError('unsupported spending authorization schema')
+  return {
+    schemaVersion: 1,
+    approved: value.approved === true,
+    authorizationId: value.authorizationId ?? null,
+    currency: value.currency ?? 'USD',
+    maximumTotal: value.maximumTotal ?? null,
+    allowedModels: Array.isArray(value.allowedModels) ? value.allowedModels : [],
+    expiresAt: value.expiresAt ?? null,
+    approvedBy: value.approvedBy ?? null,
+  }
+}

package/src/usage/ledger.ts

@@ -0,0 +1,218 @@
+import { digestOf } from '../digest.js'
+import { FusionError, USAGE_MERGE_CONFLICT } from '../errors.js'
+
+export type Count =
+  | { state: 'known'; tokens: number }
+  | { state: 'unknown' }
+  | { state: 'not_applicable' }
+
+export const known = (tokens: number): Count => ({ state: 'known', tokens: safeTokens(tokens) })
+export const unknown = (): Count => ({ state: 'unknown' })
+export const na = (): Count => ({ state: 'not_applicable' })
+
+export type CacheWrites =
+  | { kind: 'not_applicable' }
+  | { kind: 'unknown' }
+  | { kind: 'aggregate'; tokens: Count; rateKey: string }
+  | { kind: 'details'; buckets: Readonly<Record<string, { tokens: Count; rateKey: string }>> }
+
+export interface CanonicalBill {
+  uncachedInput: Count
+  cacheRead: Count
+  output: Count
+  cacheWrite: CacheWrites
+  reasoning: { kind: 'included' | 'separate' | 'unknown' | 'not_applicable'; tokens: Count }
+}
+
+export interface UsageRequestKey {
+  provider: string
+  model: string
+  requestId: string
+  attemptId: string
+  contractDigest: string
+}
+
+export interface UsageObservation {
+  id: string
+  key: UsageRequestKey
+  sequence: number
+  mode: 'snapshot' | 'delta' | 'final'
+  bill: CanonicalBill
+}
+
+export interface UsageLedgerV2 {
+  schemaVersion: 2
+  key: UsageRequestKey
+  observations: readonly UsageObservation[]
+}
+
+export interface UsageProjection {
+  bill?: CanonicalBill
+  authority: 'none' | 'provisional' | 'final'
+}
+
+function requireThat(condition: unknown, code: string, message = code): asserts condition {
+  if (!condition) throw new FusionError(USAGE_MERGE_CONFLICT, message)
+}
+
+function safeTokens(n: number): number {
+  requireThat(Number.isSafeInteger(n) && n >= 0, 'INVALID_TOKEN_COUNT')
+  return n
+}
+
+function same(a: unknown, b: unknown): boolean {
+  return digestOf(a) === digestOf(b)
+}
+
+function freezeDeep<T>(value: T): Readonly<T> {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value as Record<string, unknown>)) freezeDeep(child)
+    Object.freeze(value)
+  }
+  return value as Readonly<T>
+}
+
+export function newLedger(key: UsageRequestKey): UsageLedgerV2 {
+  requireThat(Object.values(key).every(value => typeof value === 'string' && value.length > 0), 'INVALID_REQUEST_KEY')
+  return freezeDeep({ schemaVersion: 2, key: structuredClone(key), observations: [] })
+}
+
+function validCount(value: Count): void {
+  requireThat(value && ['known', 'unknown', 'not_applicable'].includes(value.state), 'INVALID_COUNT')
+  if (value.state === 'known') safeTokens(value.tokens)
+}
+
+function validateBill(bill: CanonicalBill): void {
+  validCount(bill.uncachedInput)
+  validCount(bill.cacheRead)
+  validCount(bill.output)
+  validCount(bill.reasoning.tokens)
+  requireThat(['included', 'separate', 'unknown', 'not_applicable'].includes(bill.reasoning.kind), 'INVALID_REASONING_CONTRACT')
+  if (bill.reasoning.kind === 'included' && bill.reasoning.tokens.state === 'known' && bill.output.state === 'known') {
+    requireThat(bill.reasoning.tokens.tokens <= bill.output.tokens, 'REASONING_EXCEEDS_OUTPUT')
+  }
+  if (bill.reasoning.kind === 'not_applicable') {
+    requireThat(bill.reasoning.tokens.state === 'not_applicable', 'REASONING_NOT_APPLICABLE_CONFLICT')
+  }
+  const write = bill.cacheWrite
+  requireThat(['aggregate', 'details', 'unknown', 'not_applicable'].includes(write.kind), 'INVALID_CACHE_LAYOUT')
+  if (write.kind === 'aggregate') {
+    validCount(write.tokens)
+    requireThat(write.rateKey.length > 0, 'RATE_KEY_REQUIRED')
+  }
+  if (write.kind === 'details') {
+    requireThat(Object.keys(write.buckets).length > 0, 'EMPTY_CACHE_DETAIL')
+    for (const bucket of Object.values(write.buckets)) {
+      validCount(bucket.tokens)
+      requireThat(bucket.rateKey.length > 0, 'RATE_KEY_REQUIRED')
+    }
+  }
+}
+
+function addCount(first: Count, second: Count): Count {
+  if (first.state === 'unknown' || second.state === 'unknown') return unknown()
+  if (first.state === 'not_applicable') return second
+  if (second.state === 'not_applicable') return first
+  return known(first.tokens + second.tokens)
+}
+
+function addWrites(first: CacheWrites, second: CacheWrites): CacheWrites {
+  if (first.kind === 'unknown' || second.kind === 'unknown') return { kind: 'unknown' }
+  if (first.kind === 'not_applicable') return second
+  if (second.kind === 'not_applicable') return first
+  requireThat(first.kind === second.kind, 'CACHE_LAYOUT_MIX_REQUIRES_EXPLICIT_CONVERSION')
+  if (first.kind === 'aggregate' && second.kind === 'aggregate') {
+    requireThat(first.rateKey === second.rateKey, 'CACHE_RATE_CONFLICT')
+    return { kind: 'aggregate', rateKey: first.rateKey, tokens: addCount(first.tokens, second.tokens) }
+  }
+  requireThat(first.kind === 'details' && second.kind === 'details', 'CACHE_LAYOUT_CONFLICT')
+  const keys = [...new Set([...Object.keys(first.buckets), ...Object.keys(second.buckets)])].sort()
+  const buckets = Object.fromEntries(keys.map(key => {
+    const left = first.buckets[key]
+    const right = second.buckets[key]
+    if (!left) return [key, right] as const
+    if (!right) return [key, left] as const
+    requireThat(left.rateKey === right.rateKey, 'CACHE_RATE_CONFLICT')
+    return [key, { rateKey: left.rateKey, tokens: addCount(left.tokens, right.tokens) }] as const
+  }))
+  return { kind: 'details', buckets }
+}
+
+function addBill(first: CanonicalBill, second: CanonicalBill): CanonicalBill {
+  requireThat(first.reasoning.kind === second.reasoning.kind, 'DELTA_REASONING_CONTRACT_CONFLICT')
+  return {
+    uncachedInput: addCount(first.uncachedInput, second.uncachedInput),
+    cacheRead: addCount(first.cacheRead, second.cacheRead),
+    output: addCount(first.output, second.output),
+    cacheWrite: addWrites(first.cacheWrite, second.cacheWrite),
+    reasoning: { kind: first.reasoning.kind, tokens: addCount(first.reasoning.tokens, second.reasoning.tokens) },
+  }
+}
+
+export function projectLedger(ledger: UsageLedgerV2): UsageProjection {
+  const finals = ledger.observations.filter(item => item.mode === 'final')
+  if (finals.length) {
+    for (const item of finals) requireThat(same(item.bill, finals[0]!.bill), 'CONFLICTING_FINAL_BILLS')
+    return { authority: 'final', bill: finals[0]!.bill }
+  }
+  const snapshots = ledger.observations.filter(item => item.mode === 'snapshot').sort((a, b) => a.sequence - b.sequence)
+  const base = snapshots.at(-1)
+  const deltas = ledger.observations
+    .filter(item => item.mode === 'delta' && (!base || item.sequence > base.sequence))
+    .sort((a, b) => a.sequence - b.sequence)
+  let bill = base?.bill
+  for (const delta of deltas) bill = bill ? addBill(bill, delta.bill) : delta.bill
+  return { authority: bill ? 'provisional' : 'none', bill }
+}
+
+export function ingestObservation(ledger: UsageLedgerV2, observation: UsageObservation): UsageLedgerV2 {
+  requireThat(ledger.schemaVersion === 2 && same(ledger.key, observation.key), 'REQUEST_SCOPE_MISMATCH')
+  requireThat(observation.id.length > 0 && Number.isSafeInteger(observation.sequence) && observation.sequence >= 0, 'INVALID_OBSERVATION_ID_OR_SEQUENCE')
+  requireThat(['snapshot', 'delta', 'final'].includes(observation.mode), 'INVALID_OBSERVATION_MODE')
+  validateBill(observation.bill)
+  const existing = ledger.observations.find(item => item.id === observation.id)
+  if (existing) {
+    requireThat(digestOf(existing) === digestOf(observation), 'OBSERVATION_ID_CONFLICT')
+    return ledger
+  }
+  const sameSlot = ledger.observations.find(item => item.sequence === observation.sequence)
+  if (sameSlot) {
+    requireThat(sameSlot.mode === observation.mode && same(sameSlot.bill, observation.bill), 'OBSERVATION_SEQUENCE_CONFLICT')
+    requireThat(observation.mode !== 'delta', 'DELTA_REQUIRES_STABLE_EVENT_ID')
+  }
+  const next = freezeDeep({
+    ...ledger,
+    observations: [...ledger.observations, structuredClone(observation)],
+  })
+  projectLedger(next)
+  return next
+}
+
+export function ingestDurable(ledger: UsageLedgerV2, observation: UsageObservation): UsageLedgerV2 {
+  return ingestObservation(structuredClone(ledger), structuredClone(observation))
+}
+
+export function restoreLedger(raw: unknown): UsageLedgerV2 {
+  requireThat(raw && typeof raw === 'object', 'INVALID_LEDGER')
+  const value = raw as Partial<UsageLedgerV2>
+  requireThat(value.schemaVersion === 2 && value.key && Array.isArray(value.observations), 'UNSUPPORTED_LEDGER_FORMAT')
+  for (const field of ['provider', 'model', 'requestId', 'attemptId', 'contractDigest'] as const) {
+    requireThat(typeof value.key[field] === 'string' && value.key[field].length, 'INVALID_REQUEST_KEY')
+  }
+  let state = newLedger(structuredClone(value.key as UsageRequestKey))
+  for (const item of value.observations ?? []) state = ingestDurable(state, item)
+  return state
+}
+
+export function splitInput(total: Count, cached: Count, includesCache: boolean | null): Count {
+  if (includesCache === false) return total
+  if (includesCache === null) {
+    if (cached.state === 'not_applicable' || (cached.state === 'known' && cached.tokens === 0)) return total
+    return unknown()
+  }
+  if (total.state !== 'known' || cached.state !== 'known') return unknown()
+  requireThat(cached.tokens <= total.tokens, 'CACHE_EXCEEDS_INPUT')
+  return known(total.tokens - cached.tokens)
+}
+
+export const observationDigest = (observation: UsageObservation): string => digestOf(observation)