Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
4.7 KB
Raw Blame
import { createHash } from 'node:crypto'

export const REGISTRY_OPERATION_ID_ANNOTATION = 'clerum.io/registry-operation-id'
export const REGISTRY_SPEC_DIGEST_ANNOTATION = 'clerum.io/registry-spec-sha256'

export type RegistryMutationOutcome = 'committed' | 'not-committed' | 'ambiguous'
export type RegistryMutationReadbackOutcome = 'committed' | 'ambiguous'

export type RegistryResourceSnapshot = {
  metadata?: {
    name?: string
    namespace?: string
    uid?: string
    resourceVersion?: string
    labels?: Record<string, string>
    annotations?: Record<string, string>
  }
  spec?: Record<string, unknown>
}

export type RegistryMutationDesired = {
  spec: Record<string, unknown>
  metadata: {
    labels?: Record<string, string>
    annotations?: Record<string, string>
  }
  specDigest: string
}

/** Canonicalize only JSON-like values; object key order is not semantic, array order is. */
export function canonicalRegistryValue(value: unknown): unknown {
  if (Array.isArray(value)) {
    return value.filter(entry => entry !== undefined).map(canonicalRegistryValue)
  }
  if (!value || typeof value !== 'object') return value
  return Object.fromEntries(
    Object.entries(value as Record<string, unknown>)
      .filter(([, entry]) => entry !== undefined)
      // Code-unit ordering, not localeCompare: this canonical form feeds a
      // SHA-256 digest that is persisted as an annotation, and collation
      // differs across ICU builds and default locales. A locale-dependent sort
      // would let two runtimes derive different digests for the same spec.
      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
      .map(([key, entry]) => [key, canonicalRegistryValue(entry)])
  )
}

export function canonicalRegistryJson(value: unknown): string {
  return JSON.stringify(canonicalRegistryValue(value))
}

export function registrySpecDigest(spec: Record<string, unknown>): string {
  return createHash('sha256').update(canonicalRegistryJson(spec)).digest('hex')
}

function metadataSubsetMatches(
  current: RegistryResourceSnapshot['metadata'],
  expected: RegistryResourceSnapshot['metadata']
): boolean {
  for (const [key, value] of Object.entries(expected?.labels ?? {})) {
    if (current?.labels?.[key] !== value) return false
  }
  for (const [key, value] of Object.entries(expected?.annotations ?? {})) {
    if (current?.annotations?.[key] !== value) return false
  }
  return true
}

/**
 * Classify a readback after a Registry mutation returned an ambiguous error.
 * resourceVersion is intentionally treated as opaque: only equality matters.
 * An unchanged prior object is `not-committed` only when the caller has
 * established that exact state through its bounded repeated-read policy; a
 * single stale read must remain ambiguous at the route boundary.
 */
export function classifyRegistryMutationReadback(input: {
  before: RegistryResourceSnapshot
  desired: RegistryMutationDesired
  current: RegistryResourceSnapshot
  operationId: string
}): RegistryMutationReadbackOutcome {
  const beforeMeta = input.before.metadata
  const currentMeta = input.current.metadata
  if (!beforeMeta?.uid || !beforeMeta.resourceVersion || !currentMeta?.uid) return 'ambiguous'

  const sameUid = currentMeta.uid === beforeMeta.uid
  const currentOperationId = currentMeta.annotations?.[REGISTRY_OPERATION_ID_ANNOTATION]
  const desiredMetadataMatches = metadataSubsetMatches(currentMeta, input.desired.metadata)
  const currentSpecDigest = registrySpecDigest(input.current.spec ?? {})

  if (
    sameUid &&
    typeof currentMeta.resourceVersion === 'string' &&
    currentMeta.resourceVersion !== beforeMeta.resourceVersion &&
    currentOperationId === input.operationId &&
    currentSpecDigest === input.desired.specDigest &&
    desiredMetadataMatches
  ) {
    return 'committed'
  }

  // A readback alone cannot prove that a failed write is no longer in flight.
  // Only the caller's successful identity fence may produce `not-committed`.
  return 'ambiguous'
}

export function classifyRegistryAssociationReadback(input: {
  before: RegistryResourceSnapshot
  current: RegistryResourceSnapshot | null
  isCommitted: (spec: Record<string, unknown>) => boolean
}): RegistryMutationReadbackOutcome {
  const beforeMeta = input.before.metadata
  const currentMeta = input.current?.metadata
  if (
    !beforeMeta?.uid ||
    !beforeMeta.resourceVersion ||
    !currentMeta?.uid ||
    typeof currentMeta.resourceVersion !== 'string'
  ) {
    return 'ambiguous'
  }
  if (currentMeta.uid !== beforeMeta.uid) return 'ambiguous'
  if (
    currentMeta.resourceVersion !== beforeMeta.resourceVersion &&
    input.isCommitted(input.current?.spec ?? {})
  ) {
    return 'committed'
  }
  return 'ambiguous'
}