@goodandready/dsh-model-sync 0.2.7 → 0.2.10

package/lib/models.js

@@ -1,16 +1,170 @@
 const FIELD_ALIASES = Object.freeze({
-  contextWindow: ['contextWindow', 'context_window', 'contextLength', 'context_length'],
-  maxTokens: ['maxTokens', 'max_tokens', 'max_output_tokens', 'maxOutputTokens'],
+  contextWindow: [
+    'contextWindow', 'context_window', 'contextLength', 'context_length',
+    'maxContextTokens', 'max_context_tokens', 'maxContextLength', 'max_context_length',
+    'inputTokenLimit', 'input_token_limit',
+  ],
+  maxTokens: [
+    'maxTokens', 'max_tokens', 'max_output_tokens', 'maxOutputTokens',
+    'outputTokenLimit', 'output_token_limit',
+  ],
 })
 
-function firstNumber(row, fields) {
+const CAPABILITY_ALIASES = Object.freeze({
+  vision: ['vision', 'supportsVision', 'supports_vision', 'imageInput', 'image_input'],
+  tools: ['tools', 'toolUse', 'tool_use', 'functionCalling', 'function_calling', 'supportsTools', 'supports_tools'],
+  reasoning: ['reasoning', 'supportsReasoning', 'supports_reasoning', 'thinking', 'extendedThinking', 'extended_thinking'],
+  embeddings: ['embeddings', 'embedding', 'supportsEmbeddings', 'supports_embeddings'],
+})
+
+const CAPABILITY_TOKENS = Object.freeze({
+  vision: new Set(['vision', 'image', 'imageinput', 'multimodal']),
+  tools: new Set(['tools', 'tooluse', 'toolchoice', 'functioncalling', 'functioncall']),
+  reasoning: new Set(['reasoning', 'reasoningeffort', 'thinking', 'extendedthinking']),
+  embeddings: new Set(['embedding', 'embeddings']),
+})
+
+const ID_ALIASES = Object.freeze(['aliases', 'alias', 'previousIds', 'previous_ids', 'previousId', 'previous_id'])
+
+const PRICING_ALIASES = Object.freeze({
+  inputPerToken: ['inputPerToken', 'input_per_token', 'inputPricePerToken', 'input_price_per_token'],
+  outputPerToken: ['outputPerToken', 'output_per_token', 'outputPricePerToken', 'output_price_per_token'],
+})
+
+function numericValue(value, { allowZero = false } = {}) {
+  if (typeof value !== 'number' && typeof value !== 'string') return undefined
+  if (typeof value === 'string' && value.trim() === '') return undefined
+  const number = Number(value)
+  if (!Number.isFinite(number) || (allowZero ? number < 0 : number <= 0)) return undefined
+  return number
+}
+
+function firstNumber(row, fields, options) {
   for (const field of fields) {
-    const value = Number(row?.[field])
-    if (Number.isFinite(value) && value > 0) return value
+    const value = numericValue(row?.[field], options)
+    if (value !== undefined) return value
   }
   return undefined
 }
 
+function booleanValue(value) {
+  if (value === true || value === false) return value
+  if (typeof value !== 'string') return undefined
+  if (value.trim().toLowerCase() === 'true') return true
+  if (value.trim().toLowerCase() === 'false') return false
+  return undefined
+}
+
+function capabilityToken(value) {
+  if (typeof value !== 'string') return undefined
+  const token = value.trim().toLowerCase().replaceAll(/[_-]/g, '')
+  return Object.entries(CAPABILITY_TOKENS).find(([, tokens]) => tokens.has(token))?.[0]
+}
+
+function normalizeCapabilities(row) {
+  const result = {}
+  const assign = (key, value) => {
+    const normalized = booleanValue(value)
+    if (normalized !== undefined) result[key] = normalized
+  }
+
+  for (const [key, fields] of Object.entries(CAPABILITY_ALIASES)) {
+    for (const field of fields) {
+      if (row?.[field] !== undefined) assign(key, row[field])
+    }
+  }
+
+  const sources = [row?.capabilities, row?.supportedCapabilities, row?.supported_capabilities]
+  for (const source of sources) {
+    if (Array.isArray(source)) {
+      for (const token of source) {
+        const key = capabilityToken(token)
+        if (key) result[key] = true
+      }
+    } else if (source && typeof source === 'object') {
+      for (const [key, fields] of Object.entries(CAPABILITY_ALIASES)) {
+        for (const field of fields) {
+          if (source[field] !== undefined) assign(key, source[field])
+        }
+      }
+      for (const [token, value] of Object.entries(source)) {
+        const key = capabilityToken(token)
+        if (key) assign(key, value)
+      }
+    }
+  }
+
+  const modalitySources = [row?.modalities, row?.inputModalities, row?.input_modalities]
+  for (const source of modalitySources) {
+    if (!Array.isArray(source)) continue
+    for (const token of source) {
+      const key = capabilityToken(token)
+      if (key) result[key] = true
+    }
+  }
+
+  const parameterSources = [row?.supportedParameters, row?.supported_parameters]
+  for (const source of parameterSources) {
+    if (!Array.isArray(source)) continue
+    for (const token of source) {
+      const key = capabilityToken(token)
+      if (key) result[key] = true
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined
+}
+
+function normalizeTags(row) {
+  const source = row?.tags ?? row?.labels
+  if (!Array.isArray(source)) return undefined
+  const tags = [...new Set(source
+    .filter((tag) => typeof tag === 'string' && tag.trim())
+    .map((tag) => tag.trim())
+    .slice(0, 50))]
+  return tags.length > 0 ? tags : undefined
+}
+
+function normalizeAliases(row, id) {
+  const aliases = []
+  for (const field of ID_ALIASES) {
+    const source = row?.[field]
+    const values = Array.isArray(source) ? source : source === undefined || source === null ? [] : [source]
+    for (const value of values) {
+      if (typeof value !== 'string') continue
+      const alias = value.trim()
+      if (alias && alias !== id && !aliases.includes(alias)) aliases.push(alias)
+    }
+  }
+  return aliases.slice(0, 20)
+}
+
+function normalizeLifecycle(row) {
+  const source = row?.lifecycle && typeof row.lifecycle === 'object' ? row.lifecycle : {}
+  const deprecated = booleanValue(source.deprecated ?? row?.deprecated ?? row?.isDeprecated)
+  const date = source.deprecationDate ?? source.deprecation_date ?? source.expirationDate ?? source.expiration_date ?? source.expiresAt ?? source.expires_at ?? row?.deprecationDate ?? row?.deprecation_date ?? row?.expirationDate ?? row?.expiration_date ?? row?.expiresAt ?? row?.expires_at
+  const deprecationDate = typeof date === 'string' && date.trim() ? date.trim() : undefined
+  if (deprecated === undefined && deprecationDate === undefined) return undefined
+  return {
+    ...(deprecated === undefined ? {} : { deprecated }),
+    ...(deprecationDate === undefined ? {} : { deprecationDate }),
+  }
+}
+
+function normalizePricing(row) {
+  const source = row?.pricing ?? row?.price ?? row?.cost
+  if (!source || typeof source !== 'object') return undefined
+  const inputPerToken = firstNumber(source, PRICING_ALIASES.inputPerToken, { allowZero: true })
+  const outputPerToken = firstNumber(source, PRICING_ALIASES.outputPerToken, { allowZero: true })
+  if (inputPerToken === undefined && outputPerToken === undefined) return undefined
+  const pricing = {
+    ...(inputPerToken === undefined ? {} : { inputPerToken }),
+    ...(outputPerToken === undefined ? {} : { outputPerToken }),
+  }
+  if (typeof source.currency === 'string' && source.currency.trim()) pricing.currency = source.currency.trim()
+  if (typeof source.unit === 'string' && source.unit.trim()) pricing.unit = source.unit.trim()
+  return pricing
+}
+
 export function normalizeModel(provider, row) {
   if (typeof row === 'string') {
     row = { id: row }
@@ -21,6 +175,11 @@ export function normalizeModel(provider, row) {
   const name = String(row.name ?? row.displayName ?? row.display_name ?? id).trim() || id
   const contextWindow = firstNumber(row, FIELD_ALIASES.contextWindow)
   const maxTokens = firstNumber(row, FIELD_ALIASES.maxTokens)
+  const capabilities = normalizeCapabilities(row)
+  const pricing = normalizePricing(row)
+  const tags = normalizeTags(row)
+  const aliases = normalizeAliases(row, id)
+  const lifecycle = normalizeLifecycle(row)
   return {
     provider,
     id,
@@ -28,6 +187,11 @@ export function normalizeModel(provider, row) {
     ...(contextWindow === undefined ? {} : { contextWindow }),
     ...(maxTokens === undefined ? {} : { maxTokens }),
     ...(row.description ? { description: String(row.description) } : {}),
+    ...(capabilities === undefined ? {} : { capabilities }),
+    ...(pricing === undefined ? {} : { pricing }),
+    ...(tags === undefined ? {} : { tags }),
+    ...(aliases.length === 0 ? {} : { aliases }),
+    ...(lifecycle === undefined ? {} : { lifecycle }),
   }
 }
 
@@ -44,19 +208,47 @@ export function normalizeModels(provider, rows) {
 }
 
 export function diffModels(previous, next) {
-  const before = new Map(normalizeModels('', previous).map((row) => [row.id, row]))
-  const after = new Map(normalizeModels('', next).map((row) => [row.id, row]))
+  const sortModels = (rows) => normalizeModels('', rows).sort((left, right) => left.id.localeCompare(right.id))
+  const beforeRows = sortModels(previous)
+  const afterRows = sortModels(next)
+  const before = new Map(beforeRows.map((row) => [row.id, row]))
+  const after = new Map(afterRows.map((row) => [row.id, row]))
   const added = []
   const removed = []
+  const renamed = []
   const changed = []
+  const renamedBefore = new Set()
   for (const [id, model] of after) {
-    if (!before.has(id)) added.push(model)
-    else if (JSON.stringify(before.get(id)) !== JSON.stringify(model)) {
+    if (!before.has(id)) continue
+    if (JSON.stringify(before.get(id)) !== JSON.stringify(model)) {
       changed.push({ before: before.get(id), after: model })
     }
   }
+  for (const [id, model] of after) {
+    if (before.has(id)) continue
+    const match = beforeRows.find((candidate) => {
+      if (renamedBefore.has(candidate.id)) return false
+      return model.aliases?.includes(candidate.id) || candidate.aliases?.includes(model.id)
+    })
+    if (match) {
+      renamed.push({ before: match, after: model })
+      renamedBefore.add(match.id)
+    } else {
+      added.push(model)
+    }
+  }
   for (const [id, model] of before) {
-    if (!after.has(id)) removed.push(model)
+    if (!after.has(id) && !renamedBefore.has(id)) removed.push(model)
+  }
+  added.sort((left, right) => left.id.localeCompare(right.id))
+  removed.sort((left, right) => left.id.localeCompare(right.id))
+  renamed.sort((left, right) => left.before.id.localeCompare(right.before.id))
+  changed.sort((left, right) => left.before.id.localeCompare(right.before.id))
+  return {
+    added,
+    removed,
+    renamed,
+    changed,
+    hasChanges: added.length > 0 || removed.length > 0 || renamed.length > 0 || changed.length > 0,
   }
-  return { added, removed, changed, hasChanges: added.length > 0 || removed.length > 0 || changed.length > 0 }
 }

package/lib/policy.js

@@ -0,0 +1,71 @@
+const CAPABILITY_KEYS = new Set(['vision', 'tools', 'reasoning', 'embeddings'])
+const MAX_PATTERNS = 100
+const MAX_PATTERN_LENGTH = 256
+
+function list(value) {
+  if (!Array.isArray(value)) return []
+  return [...new Set(value.filter((item) => typeof item === 'string' && item.trim()).map((item) => item.trim()).slice(0, MAX_PATTERNS))]
+}
+
+function capabilities(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key, val]) => CAPABILITY_KEYS.has(key) && typeof val === 'boolean')
+    .slice(0, CAPABILITY_KEYS.size))
+}
+
+export function normalizePolicy(policy) {
+  const value = policy && typeof policy === 'object' && !Array.isArray(policy) ? policy : {}
+  return {
+    include: list(value.include),
+    exclude: list(value.exclude),
+    requireCapabilities: capabilities(value.requireCapabilities),
+    denyCapabilities: capabilities(value.denyCapabilities),
+  }
+}
+
+function compilePatterns(patterns, field) {
+  return patterns.map((pattern) => {
+    if (pattern.length > MAX_PATTERN_LENGTH) throw Object.assign(new Error(`${field} pattern is too long`), { code: 'INVALID_POLICY' })
+    try {
+      return new RegExp(pattern, 'i')
+    } catch {
+      throw Object.assign(new Error(`invalid ${field} pattern: ${pattern}`), { code: 'INVALID_POLICY' })
+    }
+  })
+}
+
+export function validatePolicy(policy) {
+  const normalized = normalizePolicy(policy)
+  compilePatterns(normalized.include, 'include')
+  compilePatterns(normalized.exclude, 'exclude')
+  return normalized
+}
+
+export function hasPolicy(policy) {
+  const normalized = normalizePolicy(policy)
+  return normalized.include.length > 0
+    || normalized.exclude.length > 0
+    || Object.keys(normalized.requireCapabilities).length > 0
+    || Object.keys(normalized.denyCapabilities).length > 0
+}
+
+export function filterModels(models, policy) {
+  const normalized = validatePolicy(policy)
+  const include = compilePatterns(normalized.include, 'include')
+  const exclude = compilePatterns(normalized.exclude, 'exclude')
+  return (models ?? []).filter((model) => {
+    const haystack = [model?.id, model?.name, ...(Array.isArray(model?.tags) ? model.tags : [])]
+      .filter((value) => typeof value === 'string').join('\n')
+    if (include.length > 0 && !include.some((pattern) => pattern.test(haystack))) return false
+    if (exclude.some((pattern) => pattern.test(haystack))) return false
+    const modelCapabilities = model?.capabilities ?? {}
+    for (const [key, expected] of Object.entries(normalized.requireCapabilities)) {
+      if (modelCapabilities[key] !== expected) return false
+    }
+    for (const [key, denied] of Object.entries(normalized.denyCapabilities)) {
+      if (modelCapabilities[key] === denied) return false
+    }
+    return true
+  })
+}

package/lib/reconcile.js

@@ -6,18 +6,24 @@ function sameModel(left, right) {
 
 export function reconcileModels(provider, current, discovered, {
   removeMissing = false,
+  removeIds = [],
 } = {}) {
   const before = normalizeModels(provider, current)
   const advertised = normalizeModels(provider, discovered)
   const advertisedById = new Map(advertised.map((row) => [row.id, row]))
+  const explicitRemoveIds = new Set(removeIds)
+  const discoveryDiff = diffModels(before, advertised)
+  const renamedBefore = new Set(discoveryDiff.renamed.map((row) => row.before.id))
   const next = []
   const stale = []
   for (const row of before) {
     const fresh = advertisedById.get(row.id)
     if (fresh) next.push(fresh)
-    else {
+    else if (renamedBefore.has(row.id)) {
+      // An explicit provider alias is safe evidence that the old id was renamed.
+    } else {
       stale.push(row)
-      if (!removeMissing) next.push(row)
+      if (!removeMissing && !explicitRemoveIds.has(row.id)) next.push(row)
     }
   }
   const known = new Set(before.map((row) => row.id))

package/lib/reliability.js

@@ -0,0 +1,112 @@
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504, 522, 524])
+const RETRYABLE_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT'])
+
+export function statusOfError(error) {
+  const direct = Number(error?.status ?? error?.statusCode)
+  if (Number.isInteger(direct) && direct > 0) return direct
+  const match = String(error?.message ?? '').match(/HTTP\s+(\d{3})/i)
+  return match ? Number(match[1]) : undefined
+}
+
+export function isRetryableError(error) {
+  if (!error) return false
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') return true
+  if (RETRYABLE_CODES.has(error.code)) return true
+  const status = statusOfError(error)
+  return status !== undefined && RETRYABLE_STATUSES.has(status)
+}
+
+export function catalogRequestError(status) {
+  const error = new Error(`model catalog request failed with HTTP ${status}`)
+  error.status = Number(status)
+  return error
+}
+
+function abortError() {
+  const error = new Error('operation aborted')
+  error.name = 'AbortError'
+  return error
+}
+
+function delay(ms, signal) {
+  if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    let timer
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+      reject(signal.reason ?? abortError())
+    }
+    timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    if (signal) {
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+    }
+  })
+}
+
+export function createTimeoutSignal(parent, timeoutMs) {
+  const controller = new AbortController()
+  let timer = null
+  const onParentAbort = () => controller.abort(parent.reason ?? abortError())
+  if (parent) {
+    if (parent.aborted) onParentAbort()
+    else parent.addEventListener('abort', onParentAbort, { once: true })
+  }
+  const timeout = Number(timeoutMs)
+  if (Number.isFinite(timeout) && timeout > 0) {
+    timer = setTimeout(() => {
+      const error = new Error(`request timed out after ${timeout}ms`)
+      error.name = 'TimeoutError'
+      controller.abort(error)
+    }, timeout)
+  }
+  return {
+    signal: controller.signal,
+    cleanup() {
+      if (timer !== null) clearTimeout(timer)
+      if (parent) parent.removeEventListener('abort', onParentAbort)
+    },
+  }
+}
+
+export async function retryWithBackoff(operation, {
+  attempts = 3,
+  baseDelayMs = 250,
+  maxDelayMs = 4000,
+  signal,
+  onRetry,
+} = {}) {
+  const total = Math.max(1, Math.floor(Number(attempts) || 1))
+  let lastError
+  for (let attempt = 1; attempt <= total; attempt += 1) {
+    if (signal?.aborted) throw signal.reason ?? abortError()
+    try {
+      return await operation({ attempt })
+    } catch (error) {
+      lastError = error
+      if (attempt >= total || !isRetryableError(error)) throw error
+      const delayMs = Math.min(Math.max(0, Number(maxDelayMs) || 0), Math.max(0, Number(baseDelayMs) || 0) * (2 ** (attempt - 1)))
+      onRetry?.({ attempt, nextAttempt: attempt + 1, delayMs, error })
+      await delay(delayMs, signal)
+    }
+  }
+  throw lastError
+}
+
+export async function mapWithConcurrency(items, worker, concurrency = 4) {
+  const values = new Array(items.length)
+  const limit = Math.max(1, Math.min(items.length || 1, Math.floor(Number(concurrency) || 1)))
+  let cursor = 0
+  await Promise.all(Array.from({ length: limit }, async () => {
+    while (true) {
+      const index = cursor++
+      if (index >= items.length) return
+      values[index] = await worker(items[index], index)
+    }
+  }))
+  return values
+}

package/lib/reporting.js

@@ -0,0 +1,155 @@
+import { createHash } from 'node:crypto'
+
+export const DEFAULT_NOTIFICATION_LIMIT = 50
+export const MAX_NOTIFICATION_LIMIT = 200
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(maximum, Math.max(minimum, Math.floor(number)))
+}
+
+export function notificationLimit(value) {
+  return boundedInteger(value, DEFAULT_NOTIFICATION_LIMIT, 1, MAX_NOTIFICATION_LIMIT)
+}
+
+function safeMessage(value) {
+  return String(value ?? '')
+    .replace(/(api[_-]?key|token|secret|authorization|password)\s*[:=]\s*[^\s,;]+/gi, '$1=[redacted]')
+    .replace(/([?&](?:key|token|api[_-]?key|access[_-]?token)=)[^&#\s]+/gi, '$1[redacted]')
+    .slice(0, 240)
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
+}
+
+function statusClass(status) {
+  if (status === 'ok') return 'success'
+  if (status === 'error' || status === 'circuit-open') return 'failure'
+  return 'skipped'
+}
+
+function countsFor(rows) {
+  return rows.reduce((counts, row) => {
+    const diff = row?.diff ?? {}
+    counts.added += Array.isArray(diff.added) ? diff.added.length : 0
+    counts.removed += Array.isArray(diff.removed) ? diff.removed.length : 0
+    counts.renamed += Array.isArray(diff.renamed) ? diff.renamed.length : 0
+    counts.changed += Array.isArray(diff.changed) ? diff.changed.length : 0
+    counts.stale += Array.isArray(row?.stale) ? row.stale.length : 0
+    return counts
+  }, { added: 0, removed: 0, renamed: 0, changed: 0, stale: 0 })
+}
+
+export function createSyncReport(result, { source = 'manual' } = {}) {
+  const rows = Array.isArray(result?.results) ? result.results : []
+  const statuses = rows.map((row) => statusClass(row?.status))
+  const succeeded = statuses.filter((status) => status === 'success').length
+  const failed = statuses.filter((status) => status === 'failure').length
+  const skipped = statuses.filter((status) => status === 'skipped').length
+  const outcome = failed > 0 && succeeded > 0
+    ? 'partial'
+    : failed > 0 ? 'failure'
+      : succeeded > 0 ? 'success'
+        : 'empty'
+  const severity = outcome === 'failure' ? 'error' : outcome === 'partial' ? 'warning' : outcome === 'success' ? 'success' : 'info'
+  const providers = rows.map((row) => ({
+    provider: String(row?.provider ?? ''),
+    status: String(row?.status ?? 'unknown'),
+    class: statusClass(row?.status),
+    changed: Boolean(row?.changed),
+    ...(Number.isFinite(row?.retries) ? { retries: row.retries } : {}),
+    ...(row?.message ? { message: safeMessage(row.message) } : {}),
+    counts: {
+      added: Array.isArray(row?.diff?.added) ? row.diff.added.length : 0,
+      removed: Array.isArray(row?.diff?.removed) ? row.diff.removed.length : 0,
+      renamed: Array.isArray(row?.diff?.renamed) ? row.diff.renamed.length : 0,
+      changed: Array.isArray(row?.diff?.changed) ? row.diff.changed.length : 0,
+      stale: Array.isArray(row?.stale) ? row.stale.length : 0,
+    },
+  })).sort((left, right) => left.provider.localeCompare(right.provider))
+  const report = {
+    version: 1,
+    source: source === 'schedule' ? 'schedule' : 'manual',
+    startedAt: Number.isFinite(result?.startedAt) ? result.startedAt : Date.now(),
+    finishedAt: Number.isFinite(result?.finishedAt) ? result.finishedAt : Date.now(),
+    dryRun: result?.dryRun !== false,
+    outcome,
+    severity,
+    counts: {
+      providers: rows.length,
+      succeeded,
+      failed,
+      skipped,
+      changed: providers.filter((row) => row.changed).length,
+      models: countsFor(rows),
+    },
+    providers,
+  }
+  const fingerprintPayload = { outcome, severity, dryRun: report.dryRun, counts: report.counts, providers }
+  report.fingerprint = createHash('sha256').update(JSON.stringify(stable(fingerprintPayload))).digest('hex').slice(0, 24)
+  return report
+}
+
+export function notificationForReport(report, { now = Date.now() } = {}) {
+  if (!report || (report.outcome !== 'failure' && report.outcome !== 'partial')) return null
+  const failed = report.providers.filter((row) => row.class === 'failure')
+  const title = report.outcome === 'partial' ? 'Model sync partially completed' : 'Model sync failed'
+  const message = report.outcome === 'partial'
+    ? report.counts.succeeded + ' providers succeeded; ' + report.counts.failed + ' failed'
+    : report.counts.failed + ' providers failed'
+  return {
+    id: 'sync-notice-' + report.fingerprint,
+    fingerprint: report.fingerprint,
+    createdAt: now,
+    updatedAt: now,
+    occurrences: 1,
+    readAt: null,
+    acknowledgedAt: null,
+    severity: report.severity,
+    title,
+    message,
+    providers: failed.map((row) => ({ provider: row.provider, status: row.status, ...(row.message ? { message: row.message } : {}) })),
+  }
+}
+
+export function appendNotification(existing, report, { limit = DEFAULT_NOTIFICATION_LIMIT, now = Date.now() } = {}) {
+  const notification = notificationForReport(report, { now })
+  const rows = Array.isArray(existing) ? existing.filter((row) => row && typeof row === 'object') : []
+  if (!notification) return rows.slice(-notificationLimit(limit))
+  const index = rows.findIndex((row) => row.fingerprint === notification.fingerprint)
+  if (index >= 0) {
+    const current = structuredClone(rows[index])
+    rows.splice(index, 1)
+    rows.push({
+      ...current,
+      updatedAt: now,
+      occurrences: boundedInteger(current.occurrences, 1, 1, 1000000) + 1,
+    })
+  } else {
+    rows.push(notification)
+  }
+  return rows.slice(-notificationLimit(limit))
+}
+
+export function updateNotification(existing, id, field, { now = Date.now() } = {}) {
+  if (field !== 'read' && field !== 'acknowledged') throw Object.assign(new Error('notification field is invalid'), { code: 'INVALID_NOTIFICATION' })
+  if (typeof id !== 'string' || !id || id.length > 128) throw Object.assign(new Error('notification id is invalid'), { code: 'INVALID_NOTIFICATION' })
+  const rows = Array.isArray(existing) ? existing.map((row) => structuredClone(row)) : []
+  const row = rows.find((item) => item?.id === id)
+  if (!row) throw Object.assign(new Error('notification not found'), { code: 'NOTIFICATION_NOT_FOUND' })
+  row[field === 'read' ? 'readAt' : 'acknowledgedAt'] = now
+  return rows
+}
+
+export function listNotifications(existing, { includeAcknowledged = true } = {}) {
+  const rows = Array.isArray(existing) ? existing : []
+  return rows
+    .filter((row) => includeAcknowledged || !row?.acknowledgedAt)
+    .slice()
+    .sort((left, right) => Number(right.updatedAt ?? right.createdAt ?? 0) - Number(left.updatedAt ?? left.createdAt ?? 0))
+    .map((row) => structuredClone(row))
+}