@goodandready/dsh-model-sync 0.2.7 → 0.2.9

package/lib/history.js

@@ -0,0 +1,138 @@
+import { normalizeModels } from './models.js'
+
+export const DEFAULT_HISTORY_LIMIT = 50
+export const MAX_HISTORY_LIMIT = 200
+export const MAX_HISTORY_MODELS = 5000
+const MAX_MESSAGE_LENGTH = 512
+
+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 historyLimit(value) {
+  return boundedInteger(value, DEFAULT_HISTORY_LIMIT, 1, MAX_HISTORY_LIMIT)
+}
+
+function cloneModel(provider, model) {
+  return structuredClone(normalizeModels(provider, [model])[0] ?? null)
+}
+
+function catalog(provider, models) {
+  return normalizeModels(provider, models).slice(0, MAX_HISTORY_MODELS)
+}
+
+function message(value) {
+  if (value === undefined || value === null) return undefined
+  return String(value).replace(/(api[_-]?key|token|secret|authorization|password)\s*[:=]\s*[^\s,;]+/gi, '$1=[redacted]').slice(0, MAX_MESSAGE_LENGTH)
+}
+
+function diffFor(provider, diff) {
+  const source = diff && typeof diff === 'object' ? diff : {}
+  return {
+    added: (source.added ?? []).map((row) => cloneModel(provider, row)).filter(Boolean),
+    removed: (source.removed ?? []).map((row) => cloneModel(provider, row)).filter(Boolean),
+    renamed: (source.renamed ?? []).map((row) => ({
+      before: cloneModel(provider, row?.before),
+      after: cloneModel(provider, row?.after),
+    })).filter((row) => row.before && row.after),
+    changed: (source.changed ?? []).map((row) => ({
+      before: cloneModel(provider, row?.before),
+      after: cloneModel(provider, row?.after),
+    })).filter((row) => row.before && row.after),
+  }
+}
+
+export function createHistoryEntry(result, { version = 1, maxModels = MAX_HISTORY_MODELS } = {}) {
+  const rows = Array.isArray(result?.results) ? result.results : []
+  const providers = rows.map((row) => {
+    const provider = String(row?.provider ?? '')
+    const diff = diffFor(provider, row?.diff)
+    const before = catalog(provider, row?.before).slice(0, maxModels)
+    const after = catalog(provider, row?.next).slice(0, maxModels)
+    return {
+      provider,
+      status: String(row?.status ?? 'unknown'),
+      changed: Boolean(row?.changed),
+      ...(Number.isFinite(row?.retries) ? { retries: row.retries } : {}),
+      ...(message(row?.message) ? { message: message(row.message) } : {}),
+      counts: {
+        added: diff.added.length,
+        removed: diff.removed.length,
+        renamed: diff.renamed.length,
+        changed: diff.changed.length,
+        stale: Array.isArray(row?.stale) ? row.stale.length : 0,
+      },
+      diff,
+      before,
+      after,
+    }
+  }).sort((left, right) => left.provider.localeCompare(right.provider))
+  const startedAt = Number.isFinite(result?.startedAt) ? result.startedAt : Date.now()
+  const finishedAt = Number.isFinite(result?.finishedAt) ? result.finishedAt : startedAt
+  return {
+    id: `sync-${version}-${finishedAt}`,
+    version,
+    startedAt,
+    finishedAt,
+    providers,
+  }
+}
+
+export function appendHistory(history, entry, limit = DEFAULT_HISTORY_LIMIT) {
+  const rows = Array.isArray(history) ? history.filter((row) => row && typeof row === 'object') : []
+  const next = [...rows, structuredClone(entry)]
+  next.sort((left, right) => Number(left.version ?? 0) - Number(right.version ?? 0))
+  return next.slice(-historyLimit(limit))
+}
+
+function briefModel(model) {
+  if (!model || typeof model !== 'object') return null
+  return { id: model.id, name: model.name }
+}
+
+function briefDiff(diff) {
+  const source = diff ?? {}
+  return {
+    added: (source.added ?? []).map(briefModel).filter(Boolean),
+    removed: (source.removed ?? []).map(briefModel).filter(Boolean),
+    renamed: (source.renamed ?? []).map((pair) => ({ before: briefModel(pair.before), after: briefModel(pair.after) })).filter((pair) => pair.before && pair.after),
+    changed: (source.changed ?? []).map((pair) => ({ before: briefModel(pair.before), after: briefModel(pair.after) })).filter((pair) => pair.before && pair.after),
+  }
+}
+
+function summaryProvider(row) {
+  return {
+    provider: row.provider,
+    status: row.status,
+    changed: Boolean(row.changed),
+    ...(row.retries === undefined ? {} : { retries: row.retries }),
+    ...(row.message ? { message: row.message } : {}),
+    counts: structuredClone(row.counts ?? { added: 0, removed: 0, renamed: 0, changed: 0, stale: 0 }),
+    diff: briefDiff(row.diff),
+    hasRollback: Array.isArray(row.before),
+  }
+}
+
+export function historySummary(entry) {
+  return {
+    id: entry.id,
+    version: entry.version,
+    startedAt: entry.startedAt,
+    finishedAt: entry.finishedAt,
+    providers: (entry.providers ?? []).map(summaryProvider),
+  }
+}
+
+export function listHistory(history, { limit = DEFAULT_HISTORY_LIMIT, provider, historyId, details = false } = {}) {
+  let rows = Array.isArray(history) ? history : []
+  if (historyId) rows = rows.filter((entry) => entry.id === historyId)
+  if (provider) rows = rows.map((entry) => ({ ...entry, providers: (entry.providers ?? []).filter((row) => row.provider === provider) })).filter((entry) => entry.providers.length > 0)
+  rows = rows.slice().sort((left, right) => Number(right.version ?? 0) - Number(left.version ?? 0)).slice(0, historyLimit(limit))
+  return rows.map((entry) => details ? structuredClone(entry) : historySummary(entry))
+}
+
+export function historyEntry(history, id) {
+  return (Array.isArray(history) ? history : []).find((entry) => entry?.id === id) ?? null
+}

package/lib/http.js

@@ -1,3 +1,5 @@
+import { validatePolicy } from './policy.js'
+
 const BASE = '/dsh-model-sync'
 
 function json(res, status, body) {
@@ -40,6 +42,77 @@ export function normalizeRunRequest(body) {
   }
 }
 
+export function normalizeCredentialRequest(url = '') {
+  const parsed = new URL(url || '/', 'http://dsh-model-sync.local')
+  const provider = parsed.searchParams.get('provider') || undefined
+  if (provider && (provider.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(provider))) throw new Error('provider must be a short string')
+  return provider ? { provider } : {}
+}
+
+export function normalizeNotificationRequest(url = '') {
+  const parsed = new URL(url || '/', 'http://dsh-model-sync.local')
+  return { includeAcknowledged: parsed.searchParams.get('includeAcknowledged') !== 'false' }
+}
+
+export function normalizeNotificationAction(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
+  if (typeof body.id !== 'string' || !body.id || body.id.length > 128) throw new Error('notification id is invalid')
+  return { id: body.id.trim() }
+}
+
+export function normalizeCredentialCheckRequest(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
+  if (body.provider !== undefined && (typeof body.provider !== 'string' || body.provider.length > 128)) throw new Error('provider must be a short string')
+  return body.provider ? { provider: body.provider.trim() } : {}
+}
+
+export function normalizeHealthRequest(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
+  if (body.provider !== undefined && (typeof body.provider !== 'string' || body.provider.length > 128)) throw new Error('provider must be a short string')
+  return body.provider ? { provider: body.provider } : {}
+}
+
+export function normalizePolicyRequest(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
+  if (typeof body.provider !== 'string' || !body.provider || body.provider.length > 128) throw new Error('provider must be a short string')
+  for (const field of ['include', 'exclude']) {
+    if (body[field] !== undefined && (!Array.isArray(body[field]) || body[field].length > 100)) throw new Error(`${field} must be an array`)
+    if (Array.isArray(body[field]) && body[field].some((value) => typeof value !== 'string' || value.length > 256)) throw new Error(`${field} patterns must be short strings`)
+  }
+  for (const field of ['requireCapabilities', 'denyCapabilities']) {
+    if (body[field] !== undefined && (!body[field] || typeof body[field] !== 'object' || Array.isArray(body[field]))) throw new Error(`${field} must be an object`)
+    if (body[field] && Object.keys(body[field]).length > 4) throw new Error(`${field} has too many capabilities`)
+    if (body[field] && Object.values(body[field]).some((value) => typeof value !== 'boolean')) throw new Error(`${field} values must be boolean`)
+  }
+  return {
+    provider: body.provider.trim(),
+    policy: validatePolicy({
+      include: body.include,
+      exclude: body.exclude,
+      requireCapabilities: body.requireCapabilities,
+      denyCapabilities: body.denyCapabilities,
+    }),
+  }
+}
+
+export function normalizeHistoryRequest(url = '') {
+  const parsed = new URL(url || '/', 'http://dsh-model-sync.local')
+  const limitValue = Number(parsed.searchParams.get('limit') ?? 50)
+  const limit = Number.isFinite(limitValue) ? Math.min(100, Math.max(1, Math.floor(limitValue))) : 50
+  const provider = parsed.searchParams.get('provider') || undefined
+  const historyId = parsed.searchParams.get('historyId') || undefined
+  if (provider && provider.length > 128) throw new Error('provider must be a short string')
+  if (historyId && historyId.length > 128) throw new Error('historyId must be a short string')
+  return { limit, ...(provider ? { provider } : {}), ...(historyId ? { historyId } : {}), details: parsed.searchParams.get('details') === 'true' }
+}
+
+export function normalizeHistoryRollbackRequest(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
+  if (typeof body.historyId !== 'string' || !body.historyId || body.historyId.length > 128) throw new Error('historyId must be a short string')
+  if (typeof body.provider !== 'string' || !body.provider || body.provider.length > 128) throw new Error('provider must be a short string')
+  return { historyId: body.historyId.trim(), provider: body.provider.trim() }
+}
+
 export function normalizeSelectionRequest(body) {
   if (body === null || typeof body !== 'object' || Array.isArray(body)) throw new Error('request body must be an object')
   if (typeof body.provider !== 'string' || !body.provider || body.provider.length > 128) throw new Error('provider must be a short string')
@@ -57,31 +130,75 @@ export function normalizeSelectionRequest(body) {
   return { provider: body.provider, models }
 }
 
-export function registerHttpApi(ctx, synchronizer) {
+export function registerHttpApi(ctx, synchronizer, { getSchedulerStatus = () => null } = {}) {
   const makeHandler = (route) => async (req, res) => {
     if (!trusted(req)) return json(res, 403, { error: { code: 'forbidden', message: 'dsh-model-sync: cross-origin request rejected' } })
     if (route === 'status') {
       if (req.method !== 'GET') return json(res, 405, { error: { code: 'method', message: 'GET only' } })
-      return json(res, 200, { ...synchronizer.status(), providers: synchronizer.listProviders() })
+      return json(res, 200, { ...synchronizer.status(), scheduler: getSchedulerStatus(), providers: synchronizer.listProviders() })
+    }
+    if (route === 'history') {
+      if (req.method !== 'GET') return json(res, 405, { error: { code: 'method', message: 'GET only' } })
+      try { return json(res, 200, { history: synchronizer.history(normalizeHistoryRequest(req.url)) }) }
+      catch (error) { return json(res, 400, { error: { code: 'bad-request', message: error instanceof Error ? error.message : String(error) } }) }
+    }
+    if (route === 'credentials') {
+      if (req.method !== 'GET') return json(res, 405, { error: { code: 'method', message: 'GET only' } })
+      try { return json(res, 200, await synchronizer.credentialDiagnostics(normalizeCredentialRequest(req.url))) }
+      catch (error) { return json(res, 400, { error: { code: 'bad-request', message: error instanceof Error ? error.message : String(error) } }) }
+    }
+    if (route === 'report') {
+      if (req.method !== 'GET') return json(res, 405, { error: { code: 'method', message: 'GET only' } })
+      return json(res, 200, { report: synchronizer.report() })
+    }
+    if (route === 'notifications') {
+      if (req.method !== 'GET') return json(res, 405, { error: { code: 'method', message: 'GET only' } })
+      return json(res, 200, { notifications: synchronizer.notifications(normalizeNotificationRequest(req.url)) })
     }
     if (req.method !== 'POST') return json(res, 405, { error: { code: 'method', message: 'POST only' } })
     let options
-    try { options = route === 'selection' ? normalizeSelectionRequest(await readJson(req)) : normalizeRunRequest(await readJson(req)) }
+    try {
+      const body = await readJson(req)
+      options = route === 'selection'
+        ? normalizeSelectionRequest(body)
+        : route === 'policy' ? normalizePolicyRequest(body)
+        : route === 'health' ? normalizeHealthRequest(body)
+        : route === 'credentials-check' ? normalizeCredentialCheckRequest(body)
+        : route === 'notification-read' || route === 'notification-acknowledge' ? normalizeNotificationAction(body)
+        : route === 'rollback' ? normalizeHistoryRollbackRequest(body)
+        : normalizeRunRequest(body)
+    }
     catch (error) { return json(res, 400, { error: { code: 'bad-request', message: error instanceof Error ? error.message : String(error) } }) }
     try {
       const result = route === 'selection'
         ? await synchronizer.setModelSelection(options.provider, options.models)
+        : route === 'policy' ? await synchronizer.setModelPolicy(options.provider, options.policy)
+        : route === 'health' ? await synchronizer.health(options)
+        : route === 'credentials-check' ? { health: await synchronizer.health(options), credentials: await synchronizer.credentialDiagnostics(options) }
+        : route === 'notification-read' ? await synchronizer.updateNotification(options.id, 'read')
+        : route === 'notification-acknowledge' ? await synchronizer.updateNotification(options.id, 'acknowledged')
+        : route === 'rollback' ? await synchronizer.rollbackHistory(options)
         : await synchronizer.run(options)
       return json(res, 200, { ...result, providers: synchronizer.listProviders() })
     }
     catch (error) {
-      const code = error?.code === 'SETTINGS_CONFLICT' ? 409 : error?.code === 'SETTINGS_UNAVAILABLE' || error?.code === 'CONFIG_UNAVAILABLE' ? 503 : error?.code === 'PROVIDER_NOT_CONFIGURED' || error?.code === 'UNKNOWN_MODEL' ? 400 : 500
+      const code = error?.code === 'SETTINGS_CONFLICT' ? 409 : error?.code === 'SETTINGS_UNAVAILABLE' || error?.code === 'CONFIG_UNAVAILABLE' ? 503 : error?.code === 'PROVIDER_NOT_CONFIGURED' || error?.code === 'UNKNOWN_MODEL' || error?.code === 'INVALID_POLICY' || error?.code === 'INVALID_HISTORY' || error?.code === 'HISTORY_NOT_FOUND' || error?.code === 'INVALID_NOTIFICATION' || error?.code === 'NOTIFICATION_NOT_FOUND' ? 400 : 500
       return json(res, code, { error: { code: error?.code ?? 'run-failed', message: error instanceof Error ? error.message : String(error) } })
     }
   }
   return [
     ctx.webServer.register({ kind: 'exact', path: `${BASE}/status`, handler: makeHandler('status') }),
     ctx.webServer.register({ kind: 'exact', path: `${BASE}/run`, handler: makeHandler('run') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/health`, handler: makeHandler('health') }),
     ctx.webServer.register({ kind: 'exact', path: `${BASE}/selection`, handler: makeHandler('selection') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/policy`, handler: makeHandler('policy') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/history`, handler: makeHandler('history') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/history/rollback`, handler: makeHandler('rollback') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/credentials`, handler: makeHandler('credentials') }),
+    ctx.webServer.register({ kind: 'exact', path: `${BASE}/credentials/check`, handler: makeHandler('credentials-check') }),
+    ctx.webServer.register({ kind: 'exact', path: BASE + '/report', handler: makeHandler('report') }),
+    ctx.webServer.register({ kind: 'exact', path: BASE + '/notifications', handler: makeHandler('notifications') }),
+    ctx.webServer.register({ kind: 'exact', path: BASE + '/notifications/read', handler: makeHandler('notification-read') }),
+    ctx.webServer.register({ kind: 'exact', path: BASE + '/notifications/acknowledge', handler: makeHandler('notification-acknowledge') }),
   ]
 }

package/lib/index.js

@@ -12,12 +12,73 @@ const NS = 'dsh-model-sync'
 export const Config = Schema.object({
   enabled: Schema.boolean().default(true),
   intervalMinutes: Schema.number().default(60),
+  scheduleEnabled: Schema.boolean().default(false),
+  jitterMinutes: Schema.number().default(0),
+  ttlMinutes: Schema.number().default(0),
   autoApply: Schema.boolean().default(false),
+  requestTimeoutMs: Schema.number().default(15000),
+  retryAttempts: Schema.number().default(3),
+  retryBaseDelayMs: Schema.number().default(250),
+  retryMaxDelayMs: Schema.number().default(4000),
+  concurrency: Schema.number().default(4),
+  circuitBreakerFailures: Schema.number().default(3),
+  circuitBreakerCooldownMinutes: Schema.number().default(5),
+  historyLimit: Schema.number().default(50),
+  notificationLimit: Schema.number().default(50),
+  notifications: Schema.array(Schema.object({
+    id: Schema.string().required(),
+    fingerprint: Schema.string().required(),
+    createdAt: Schema.number().required(),
+    updatedAt: Schema.number().required(),
+    occurrences: Schema.number().default(1),
+    readAt: Schema.any().default(null),
+    acknowledgedAt: Schema.any().default(null),
+    severity: Schema.string().required(),
+    title: Schema.string().required(),
+    message: Schema.string().required(),
+    providers: Schema.array(Schema.object({}).loose()).default([]),
+  }).loose()).default([]),
+  staleGraceRuns: Schema.number().default(2),
+  lifecycleRetentionRuns: Schema.number().default(20),
+  lifecycleRevision: Schema.number().default(0),
+  modelLifecycle: Schema.dict(Schema.dict(Schema.object({
+    status: Schema.string().required(),
+    consecutiveMissing: Schema.number().default(0),
+    firstMissingAt: Schema.number().default(0),
+    lastSeenAt: Schema.number().default(0),
+    lastObservedRun: Schema.number().default(0),
+  }).loose())).default({}),
+  history: Schema.array(Schema.object({
+    id: Schema.string().required(),
+    version: Schema.number().required(),
+    startedAt: Schema.number().required(),
+    finishedAt: Schema.number().required(),
+    providers: Schema.array(Schema.object({}).loose()).default([]),
+  }).loose()).default([]),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     enabled: Schema.boolean().default(true),
+    intervalMinutes: Schema.number().default(0),
+    jitterMinutes: Schema.number().default(0),
+    ttlMinutes: Schema.number().default(0),
   })).default([]),
   modelSelections: Schema.dict(Schema.array(Schema.string())).default({}),
+  adapterRegistry: Schema.dict(Schema.object({
+    enabled: Schema.boolean().default(true),
+    endpoint: Schema.string().default(''),
+    auth: Schema.string().default('bearer'),
+    parser: Schema.string().default('openai'),
+    modelsPath: Schema.string().default('data'),
+    fields: Schema.any().default({}),
+    capabilityMap: Schema.any().default({}),
+    headers: Schema.dict(Schema.string()).default({}),
+  }).loose()).default({}),
+  modelPolicies: Schema.dict(Schema.object({
+    include: Schema.array(Schema.string()).default([]),
+    exclude: Schema.array(Schema.string()).default([]),
+    requireCapabilities: Schema.dict(Schema.boolean()).default({}),
+    denyCapabilities: Schema.dict(Schema.boolean()).default({}),
+  }).loose()).default({}),
   // Full catalogs are cached separately from the allowlist applied to DSH.
   // This keeps the model picker useful after a restart without widening the
   // active llm-pi-ai catalog.
@@ -81,7 +142,7 @@ export function apply(ctx, config) {
   reconfigure = () => scheduler.reconfigure()
   scheduler.start()
   ctx.effect(() => {
-    const registrations = registerHttpApi(ctx, synchronizer)
+    const registrations = registerHttpApi(ctx, synchronizer, { getSchedulerStatus: () => scheduler.status() })
   ctx.effect(() => () => scheduler.stop(), 'dsh-model-sync: scheduler cleanup')
     return () => {
       for (const dispose of registrations) if (typeof dispose === 'function') dispose()

package/lib/lifecycle.js

@@ -0,0 +1,130 @@
+export const LIFECYCLE_STATES = Object.freeze(['active', 'stale', 'deprecated', 'removed'])
+export const DEFAULT_STALE_GRACE_RUNS = 2
+export const DEFAULT_LIFECYCLE_RETENTION_RUNS = 20
+
+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 lifecycleOptions(config = {}) {
+  return {
+    staleGraceRuns: boundedInteger(config.staleGraceRuns, DEFAULT_STALE_GRACE_RUNS, 1, 20),
+    lifecycleRetentionRuns: boundedInteger(config.lifecycleRetentionRuns, DEFAULT_LIFECYCLE_RETENTION_RUNS, 1, 200),
+  }
+}
+
+function dateValue(value) {
+  if (typeof value !== 'string' || !value.trim()) return undefined
+  const timestamp = Date.parse(value)
+  return Number.isFinite(timestamp) ? timestamp : undefined
+}
+
+function explicitLifecycle(model, now) {
+  const source = model?.lifecycle && typeof model.lifecycle === 'object' ? model.lifecycle : {}
+  const deprecated = source.deprecated === true || model?.deprecated === true || model?.isDeprecated === true
+  const deprecationDate = source.deprecationDate ?? source.deprecation_date ?? source.expirationDate ?? source.expiration_date ?? source.expiresAt ?? source.expires_at
+  const deprecationAt = dateValue(deprecationDate)
+  return {
+    deprecated: deprecated || deprecationAt !== undefined && deprecationAt <= now,
+    ...(deprecationAt === undefined ? {} : { deprecationAt }),
+  }
+}
+
+function recordOf(previous, runNumber, now) {
+  const record = previous && typeof previous === 'object' ? structuredClone(previous) : {}
+  return {
+    status: LIFECYCLE_STATES.includes(record.status) ? record.status : 'active',
+    consecutiveMissing: Number.isFinite(record.consecutiveMissing) ? Math.max(0, record.consecutiveMissing) : 0,
+    firstMissingAt: Number.isFinite(record.firstMissingAt) ? record.firstMissingAt : 0,
+    lastSeenAt: Number.isFinite(record.lastSeenAt) ? record.lastSeenAt : 0,
+    lastObservedRun: Number.isFinite(record.lastObservedRun) ? record.lastObservedRun : runNumber,
+    ...(Number.isFinite(record.deprecationAt) ? { deprecationAt: record.deprecationAt } : {}),
+    ...(Number.isFinite(record.removedAt) ? { removedAt: record.removedAt } : {}),
+    ...(typeof record.reason === 'string' ? { reason: record.reason.slice(0, 256) } : {}),
+    observedAt: now,
+  }
+}
+
+function publicRecord(id, record) {
+  return { id, ...record }
+}
+
+export function updateLifecycle(previous, beforeModels, advertisedModels, {
+  runNumber = 1,
+  now = Date.now(),
+  removeMissing = false,
+  staleGraceRuns = DEFAULT_STALE_GRACE_RUNS,
+  lifecycleRetentionRuns = DEFAULT_LIFECYCLE_RETENTION_RUNS,
+} = {}) {
+  const before = Array.isArray(beforeModels) ? beforeModels : []
+  const advertised = Array.isArray(advertisedModels) ? advertisedModels : []
+  const advertisedIds = new Set(advertised.map((row) => row?.id).filter(Boolean))
+  const result = structuredClone(previous && typeof previous === 'object' ? previous : {})
+  const changes = []
+  const removedIds = []
+  for (const model of advertised) {
+    const id = model?.id
+    if (!id) continue
+    const previousRecord = result[id]
+    const record = recordOf(previousRecord, runNumber, now)
+    const signal = explicitLifecycle(model, now)
+    record.status = signal.deprecated ? 'deprecated' : 'active'
+    record.consecutiveMissing = 0
+    record.firstMissingAt = 0
+    record.lastSeenAt = now
+    record.lastObservedRun = runNumber
+    if (signal.deprecationAt !== undefined) record.deprecationAt = signal.deprecationAt
+    else delete record.deprecationAt
+    delete record.removedAt
+    delete record.reason
+    if (previousRecord?.status !== record.status) changes.push({ id, before: previousRecord?.status ?? 'active', after: record.status })
+    result[id] = record
+  }
+  for (const model of before) {
+    const id = model?.id
+    if (!id || advertisedIds.has(id)) continue
+    const previousRecord = result[id]
+    const record = recordOf(previousRecord, runNumber, now)
+    if (record.status === 'removed') continue
+    record.consecutiveMissing += 1
+    record.firstMissingAt ||= now
+    record.lastObservedRun = runNumber
+    if (record.status !== 'deprecated') record.status = 'stale'
+    if (removeMissing && record.status === 'stale' && record.consecutiveMissing >= staleGraceRuns) {
+      record.status = 'removed'
+      record.removedAt = now
+      record.reason = `missing for ${record.consecutiveMissing} discovery runs`
+      removedIds.push(id)
+    }
+    if (previousRecord?.status !== record.status || previousRecord?.consecutiveMissing !== record.consecutiveMissing) {
+      changes.push({ id, before: previousRecord?.status ?? 'active', after: record.status, consecutiveMissing: record.consecutiveMissing })
+    }
+    result[id] = record
+  }
+  for (const [id, record] of Object.entries(result)) {
+    if (record.status === 'removed' && Number.isFinite(record.removedAt) && runNumber - (record.lastObservedRun ?? runNumber) >= lifecycleRetentionRuns) {
+      delete result[id]
+    }
+  }
+  return {
+    records: result,
+    changes,
+    removedIds,
+    statuses: Object.entries(result).map(([id, record]) => publicRecord(id, record)).sort((left, right) => left.id.localeCompare(right.id)),
+  }
+}
+
+export function lifecycleStatus(records, provider, models) {
+  const map = records?.[provider] && typeof records[provider] === 'object' ? records[provider] : {}
+  return (models ?? []).map((model) => ({
+    ...model,
+    lifecycleStatus: map[model.id]?.status ?? 'active',
+    lifecycleMissingRuns: map[model.id]?.consecutiveMissing ?? 0,
+  }))
+}
+
+export function selectableModels(records, provider, models) {
+  return lifecycleStatus(records, provider, models).filter((model) => model.lifecycleStatus === 'active')
+}