@thebtf/dsh-cliproxyapi-provider 0.0.0-stage → 0.4.3

package/src/index.js

@@ -0,0 +1,513 @@
+import { AsyncResource } from 'node:async_hooks'
+import z from '@deepseek-ai/schemastery'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { assertUsableApiKey, attributionHeaders } from '@deepseek-ai/dsh-llm'
+import { Config as PiAiConfig } from '@deepseek-ai/dsh-llm-pi-ai'
+import { deepEqualJson } from '@deepseek-ai/dsh-util-values'
+import { catalogURL, readCodexCatalogWithMetadata } from './catalog.js'
+import { installGateway } from './gateway.js'
+import { protocolOf } from './policy.js'
+import { ConnectionError, resolveIdentity, validateEndpoint } from './connection.js'
+
+const MAX_CATALOG_BYTES = 4 * 1024 * 1024
+const DISCOVERY_HANDOFF_TTL_MS = 60_000
+const MAX_DISCOVERY_HANDOFFS = 8
+const DISCOVERY_NS = 'llm-cliproxyapi'
+const PI_NS = 'llm-pi-ai'
+const API_KEY_REF = credentialRef('DSH_CLIPROXY_API_KEY')
+const PROVIDER = 'CLIProxyAPI'
+
+export const PROFILE_SYNC_HEADER = 'x-dsh-provider-cpa-sync'
+export const PLACEHOLDER_AUTHORIZATION = 'Bearer dsh-cliproxyapi-no-key'
+export const CATALOG_PATH = '/api/cliproxyapi/catalog'
+
+export const name = DISCOVERY_NS
+export const inject = ['settings', 'credentials', 'llm', 'timer']
+
+export const Config = z.object({
+  defaultContextWindow: z.number().step(1).min(1).default(262144),
+  defaultMaxTokens: z.number().step(1).min(1).default(32768),
+  defaultInput: z.array(z.union(['text', 'image'])).default(['text']),
+  headers: z.dict(z.string()).default({}),
+  fetchTimeoutMs: z.number().step(1).min(1).default(15000),
+  retryInitialMs: z.number().step(1).min(1).default(3000),
+  retryMaxMs: z.number().step(1).min(1).default(60000),
+  modelSelection: z.dict(z.boolean()).default({}).volatile(),
+  refreshIntervalMs: z.number().step(1).min(0).default(300000),
+  baseURL: z.string().volatile(),
+  enabled: z.boolean().default(true).volatile(),
+  authIdentity: z.any().volatile(),
+  policy: z.any().volatile(),
+  generation: z.string().volatile(),
+  operationId: z.string().volatile(),
+  overrides: z.any().volatile(),
+  migration: z.any().volatile(),
+})
+
+function normalizedBaseURL(value) {
+  const baseURL = String(value ?? '').trim().replace(/\/+$/, '')
+  if (!baseURL) throw new TypeError('CLIProxyAPI baseURL must not be empty')
+  let parsed
+  try {
+    parsed = new URL(baseURL)
+  } catch (error) {
+    throw new TypeError('CLIProxyAPI baseURL must be a valid URL', { cause: error })
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new TypeError('CLIProxyAPI baseURL must use http or https')
+  }
+  return baseURL
+}
+
+function headerKey(headers, expected) {
+  const normalized = expected.toLowerCase()
+  return Object.keys(headers ?? {}).find((key) => key.toLowerCase() === normalized)
+}
+
+function profileSyncValue(profile) {
+  const key = headerKey(profile?.headers, PROFILE_SYNC_HEADER)
+  return key === undefined ? undefined : String(profile.headers[key])
+}
+
+function profileSynchronizationPending(profile) {
+  return profileSyncValue(profile) !== undefined
+}
+
+function profileHasRichBootstrap(profile) {
+  return profileSyncValue(profile)?.startsWith('rich:') ?? false
+}
+
+function mergedHeadersOf(profileHeaders, configuredHeaders) {
+  const headers = {}
+  for (const source of [configuredHeaders, profileHeaders]) {
+    for (const [key, value] of Object.entries(source ?? {})) {
+      const existing = headerKey(headers, key)
+      if (existing !== undefined) delete headers[existing]
+      if (key.toLowerCase() !== PROFILE_SYNC_HEADER) headers[key] = value
+    }
+  }
+  return headers
+}
+
+function catalogHeadersOf(profileHeaders, configuredHeaders) {
+  const headers = mergedHeadersOf(profileHeaders, configuredHeaders)
+  const authorization = headerKey(headers, 'authorization')
+  if (authorization !== undefined && headers[authorization] === PLACEHOLDER_AUTHORIZATION) {
+    delete headers[authorization]
+  }
+  return headers
+}
+
+function profileHeadersOf(profileHeaders, configuredHeaders, hasApiKey) {
+  const headers = mergedHeadersOf(profileHeaders, configuredHeaders)
+  const authorization = headerKey(headers, 'authorization')
+  if (hasApiKey) {
+    if (authorization !== undefined && headers[authorization] === PLACEHOLDER_AUTHORIZATION) {
+      delete headers[authorization]
+    }
+  } else if (authorization === undefined) {
+    headers.authorization = PLACEHOLDER_AUTHORIZATION
+  }
+  return headers
+}
+
+async function optionalApiKey(ctx, supplied) {
+  const raw = supplied === undefined
+    ? (await ctx.credentials.resolve(API_KEY_REF))?.value
+    : supplied
+  if (raw === undefined || raw.length === 0) return undefined
+  return assertUsableApiKey(raw, DISCOVERY_NS, API_KEY_REF)
+}
+
+function timedSignal(parent, timeoutMs) {
+  const controller = new AbortController()
+  const timeoutError = new Error(`CLIProxyAPI model catalog timed out after ${timeoutMs} ms`)
+  timeoutError.name = 'TimeoutError'
+  const forwardAbort = () => controller.abort(parent.reason)
+  if (parent?.aborted) forwardAbort()
+  else parent?.addEventListener('abort', forwardAbort, { once: true })
+  const timer = setTimeout(() => controller.abort(timeoutError), timeoutMs)
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer)
+      parent?.removeEventListener('abort', forwardAbort)
+    },
+  }
+}
+
+async function readBoundedJson(response, maxBytes = MAX_CATALOG_BYTES) {
+  const declared = Number(response.headers.get('content-length') ?? Number.NaN)
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await response.body?.cancel()
+    throw new ConnectionError('CATALOG_TOO_LARGE', 'CPA catalog is too large')
+  }
+  if (!response.body) return JSON.parse(await response.text())
+  const reader = response.body.getReader()
+  const chunks = []
+  let total = 0
+  try {
+    for (; ;) {
+      const part = await reader.read()
+      if (part.done) break
+      total += part.value.byteLength
+      if (total > maxBytes) throw new ConnectionError('CATALOG_TOO_LARGE', 'CPA catalog is too large')
+      chunks.push(part.value)
+    }
+  } finally {
+    await reader.cancel().catch(() => { })
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return JSON.parse(new TextDecoder().decode(bytes))
+}
+
+async function discoverCatalog(ctx, options, suppliedApiKey, parentSignal) {
+  const apiKey = await optionalApiKey(ctx, suppliedApiKey)
+  const baseURL = normalizedBaseURL(options.baseURL)
+  const url = catalogURL(baseURL)
+  const request = timedSignal(parentSignal, options.fetchTimeoutMs)
+  try {
+    let response
+    try {
+      response = await fetch(url, {
+        method: 'GET',
+        redirect: 'error',
+        signal: request.signal,
+        headers: {
+          accept: 'application/json',
+          ...options.headers,
+          ...(apiKey ? { authorization: 'Bearer ' + apiKey } : {}),
+          ...attributionHeaders(),
+        },
+      })
+    } catch (error) {
+      if (parentSignal?.aborted) throw parentSignal.reason ?? error
+      if (request.signal.aborted) throw new ConnectionError('CATALOG_TIMEOUT', `CLIProxyAPI model catalog timed out after ${options.fetchTimeoutMs} ms`)
+      throw new ConnectionError('CATALOG_TRANSPORT', 'Could not reach CPA catalog')
+    }
+    if (!response.ok) {
+      const failure = new ConnectionError(response.status === 401 || response.status === 403 ? 'CATALOG_AUTH' : 'CATALOG_TRANSPORT', 'CPA catalog request failed')
+      failure.status = response.status
+      throw failure
+    }
+    let body
+    try {
+      body = await readBoundedJson(response)
+    } catch (error) {
+      if (parentSignal?.aborted) throw parentSignal.reason ?? error
+      if (request.signal.aborted) throw new ConnectionError('CATALOG_TIMEOUT', `CLIProxyAPI model catalog timed out after ${options.fetchTimeoutMs} ms`)
+      if (error?.code === 'CATALOG_TOO_LARGE') throw error
+      throw new ConnectionError('CATALOG_INVALID_RESPONSE', 'CPA catalog returned invalid JSON')
+    }
+    try {
+      return {
+        ...readCodexCatalogWithMetadata(body, options),
+        hasApiKey: apiKey !== undefined,
+      }
+    } catch (error) {
+      throw new ConnectionError('CATALOG_INVALID_RESPONSE', 'CPA catalog response is invalid')
+    }
+  } finally {
+    request.dispose()
+  }
+}
+
+function sortedHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers).sort(([left], [right]) => {
+    return left.toLowerCase().localeCompare(right.toLowerCase())
+  }))
+}
+
+function refreshKeyOf(profile, config) {
+  if (!profile) return undefined
+  return JSON.stringify({
+    displayName: profile.displayName,
+    api: profile.api,
+    baseURL: String(profile.baseURL ?? '').trim().replace(/\/+$/, ''),
+    models: profile.models,
+    defaultContextWindow: profile.defaultContextWindow,
+    defaultMaxTokens: profile.defaultMaxTokens,
+    defaultInput: profile.defaultInput,
+    sync: profileSyncValue(profile),
+    supportsStrictMode: profile.compat?.supportsStrictMode,
+    headers: sortedHeaders(catalogHeadersOf(profile.headers, config.headers)),
+  })
+}
+
+async function profileOf(profile, models, hasApiKey, config) {
+  const {
+    apiKeyEnv: _previousApiKeyEnv,
+    modelOverrides: _previousModelOverrides,
+    ...rest
+  } = profile
+  const candidate = {
+    ...rest,
+    displayName: PROVIDER,
+    api: protocolOf(profile),
+    baseURL: normalizedBaseURL(profile.baseURL),
+    // This enables pi-ai's explicit strict:false, avoiding upstream auto-strict.
+    compat: { ...profile.compat, supportsStrictMode: true },
+    models,
+    defaultContextWindow: profile.defaultContextWindow ?? config.defaultContextWindow,
+    defaultMaxTokens: profile.defaultMaxTokens ?? config.defaultMaxTokens,
+    defaultInput: [...(profile.defaultInput ?? config.defaultInput)],
+    headers: profileHeadersOf(profile.headers, config.headers, hasApiKey),
+    ...(hasApiKey ? { apiKeyEnv: API_KEY_REF } : {}),
+  }
+  // providers is volatile in DSH 0.2: the Standard Schema view omits it.
+  // The callable schema validates the entry and keeps its resolved value.
+  return PiAiConfig({ providers: { [PROVIDER]: candidate } }).providers.get()[PROVIDER]
+}
+
+function retryDelay(config, failures) {
+  return Math.min(config.retryInitialMs * (2 ** Math.max(0, failures - 1)), config.retryMaxMs)
+}
+
+export function apply(ctx, config) {
+  const validateConfig = (value) => {
+    if (!value.defaultInput.length) throw new Error('defaultInput must contain at least one modality')
+    if (value.retryMaxMs < value.retryInitialMs) {
+      throw new Error('retryMaxMs must be greater than or equal to retryInitialMs')
+    }
+  }
+  validateConfig(config)
+  const syncContext = new AsyncResource('dsh-cliproxyapi-sync')
+  let source = () => config
+  const currentConfig = () => source()
+
+  const catalogFor = (profile, signal, activeConfig) => discoverCatalog(ctx, {
+    baseURL: profile.baseURL,
+    defaultContextWindow: activeConfig.defaultContextWindow,
+    defaultMaxTokens: activeConfig.defaultMaxTokens,
+    defaultInput: activeConfig.defaultInput,
+    headers: catalogHeadersOf(profile.headers, activeConfig.headers),
+    fetchTimeoutMs: activeConfig.fetchTimeoutMs,
+  }, undefined, signal)
+
+  // DSH 0.2 stores pi-ai providers in the loader entry's volatile form,
+  // exposed by settings.describe(), rather than a settings.get() section.
+  const currentProfile = () => ctx.settings.describe()
+    .find((entry) => entry.ns === PI_NS)?.value?.providers?.[PROVIDER]
+
+  const currentSelection = (settings) => settings
+    .find((entry) => entry.ns === DISCOVERY_NS)?.value?.modelSelection ?? config.modelSelection?.get?.() ?? {}
+
+  const discoveryHandoffs = new Map()
+
+  const rememberDiscovery = (baseURL, models) => {
+    const now = Date.now()
+    for (const [key, handoff] of discoveryHandoffs) {
+      if (now - handoff.storedAt > DISCOVERY_HANDOFF_TTL_MS) discoveryHandoffs.delete(key)
+    }
+    while (discoveryHandoffs.size >= MAX_DISCOVERY_HANDOFFS) {
+      discoveryHandoffs.delete(discoveryHandoffs.keys().next().value)
+    }
+    discoveryHandoffs.set(normalizedBaseURL(baseURL), {
+      models: structuredClone(models),
+      storedAt: now,
+    })
+  }
+
+  const takeDiscovery = (baseURL) => {
+    const key = normalizedBaseURL(baseURL)
+    const handoff = discoveryHandoffs.get(key)
+    discoveryHandoffs.delete(key)
+    if (!handoff || Date.now() - handoff.storedAt > DISCOVERY_HANDOFF_TTL_MS) return undefined
+    return handoff.models
+  }
+  const previewKey = async (endpoint, supplied, allowEndpointReuse) => {
+    validateEndpoint(endpoint)
+    if (supplied !== undefined) {
+      if (typeof supplied !== 'string' || Buffer.byteLength(supplied) > 4096) throw new ConnectionError('INVALID_AUTH', 'Invalid key')
+      return supplied
+    }
+    if (allowEndpointReuse !== undefined && typeof allowEndpointReuse !== 'boolean') throw new ConnectionError('INVALID_REQUEST', 'Invalid endpoint reuse')
+    const settings = ctx.settings.describe()
+    const own = settings.find((entry) => entry.ns === DISCOVERY_NS)?.value
+    if (own?.baseURL && own.authIdentity) {
+      if (own.baseURL !== endpoint && allowEndpointReuse !== true) return ''
+      if (own.authIdentity.type === 'missing') throw new ConnectionError('MISSING_CREDENTIAL', 'CPA credential is missing')
+      const key = await resolveIdentity(ctx.credentials, own.authIdentity)
+      if (own.authIdentity.type !== 'none' && !key) throw new ConnectionError('MISSING_CREDENTIAL', 'CPA credential is missing')
+      return key ?? ''
+    }
+    const legacy = settings.find((entry) => entry.ns === PI_NS)?.value?.providers?.[PROVIDER]
+    if (legacy?.baseURL === endpoint) return (await optionalApiKey(ctx)) ?? ''
+    return ''
+  }
+
+
+  const discoverModels = async (request, signal) => {
+    const activeConfig = currentConfig()
+    const catalog = await discoverCatalog(ctx, {
+      baseURL: request.baseURL,
+      defaultContextWindow: activeConfig.defaultContextWindow,
+      defaultMaxTokens: activeConfig.defaultMaxTokens,
+      defaultInput: activeConfig.defaultInput,
+      headers: {},
+      fetchTimeoutMs: activeConfig.fetchTimeoutMs,
+    }, await previewKey(request.baseURL, request.apiKey, request.allowEndpointReuse), signal ?? request.signal)
+    rememberDiscovery(request.baseURL, catalog.models)
+    return catalog.discovery
+  }
+  ctx.llm.registerModelDiscovery(DISCOVERY_NS, discoverModels)
+  installGateway(ctx, currentConfig, async (request, signal, key) => discoverCatalog(ctx, {
+    baseURL: request.baseURL,
+    defaultContextWindow: request.policy?.defaultContextWindow ?? currentConfig().defaultContextWindow,
+    defaultMaxTokens: request.policy?.defaultMaxTokens ?? currentConfig().defaultMaxTokens,
+    defaultInput: request.policy?.defaultInput ?? currentConfig().defaultInput,
+    overrides: request.overrides,
+    headers: request.policy?.headers ?? {},
+    fetchTimeoutMs: currentConfig().fetchTimeoutMs,
+  }, key ?? '', signal), readBoundedJson, previewKey)
+
+
+  let observedRefreshKey
+
+  const synchronize = async (signal, authOnly = false) => {
+    const activeConfig = currentConfig()
+    const settings = ctx.settings.describe()
+    const own = settings.find((entry) => entry.ns === DISCOVERY_NS)?.value
+    if (own?.baseURL && own.migration?.phase !== 'prepared') return false
+    const descriptor = settings.find((entry) => entry.ns === PI_NS)
+    const profile = descriptor?.value?.providers?.[PROVIDER]
+    if (!profile) return false
+    if (!Number.isSafeInteger(descriptor.revision)) throw new Error('CLIProxyAPI cannot synchronize without a settings revision')
+    if (authOnly && profileSynchronizationPending(profile)) return true
+    if (signal.aborted) throw signal.reason
+    const hasApiKey = async () => (await optionalApiKey(ctx)) !== undefined
+    let catalog
+    if (authOnly) {
+      catalog = { models: profile.models, hasApiKey: await hasApiKey() }
+    } else if (profileHasRichBootstrap(profile)) {
+      const discovered = takeDiscovery(profile.baseURL)
+      catalog = discovered
+        ? { models: discovered, hasApiKey: await hasApiKey() }
+        : await catalogFor(profile, signal, activeConfig)
+    } else {
+      catalog = await catalogFor(profile, signal, activeConfig)
+    }
+    if (signal.aborted) throw signal.reason
+    const selection = authOnly ? undefined : currentSelection(settings)
+    const enabledModels = authOnly ? catalog.models : catalog.models.filter((model) => selection[model.id] !== false)
+    if (!enabledModels.length) throw new Error('CLIProxyAPI has no enabled models in the current catalog; the existing profile was not changed')
+    const next = await profileOf(profile, enabledModels, catalog.hasApiKey, activeConfig)
+    if (signal.aborted) throw signal.reason
+    const nextRefreshKey = refreshKeyOf(next, activeConfig)
+    if (!deepEqualJson(next, profile)) {
+      const previousRefreshKey = observedRefreshKey
+      observedRefreshKey = nextRefreshKey
+      try {
+        await ctx.settings.mutate(PI_NS, [{
+          op: 'set',
+          path: ['providers', PROVIDER],
+          value: next,
+        }], descriptor.revision)
+      } catch (error) {
+        if (observedRefreshKey === nextRefreshKey) observedRefreshKey = previousRefreshKey
+        throw error
+      }
+    } else {
+      observedRefreshKey = nextRefreshKey
+    }
+    return true
+  }
+
+  let stopped = false
+  let running = false
+  let rerun = false
+  let authOnlyRequested = false
+  let activeController
+  let wakeDispose
+  let failures = 0
+  let lastError = ''
+
+  const cancelWake = () => {
+    wakeDispose?.()
+    wakeDispose = undefined
+  }
+
+  const wakeAfter = (delay) => {
+    cancelWake()
+    if (delay <= 0) return
+    wakeDispose = ctx.timeout(() => {
+      wakeDispose = undefined
+      rerun = true
+      void drain()
+    }, delay)
+  }
+
+  const drain = async () => {
+    if (running || stopped) return
+    running = true
+    try {
+      while (rerun && !stopped) {
+        rerun = false
+        const authOnly = authOnlyRequested
+        authOnlyRequested = false
+        const controller = new AbortController()
+        activeController = controller
+        try {
+          const hasProfile = await synchronize(controller.signal, authOnly)
+          failures = 0
+          lastError = ''
+          if (authOnly) rerun = true
+          else if (hasProfile && !rerun) wakeAfter(currentConfig().refreshIntervalMs)
+        } catch (error) {
+          if (controller.signal.aborted || stopped) continue
+          failures += 1
+          const message = error instanceof Error ? error.message : String(error)
+          if (message !== lastError) {
+            ctx.logger.warn('CLIProxyAPI provider refresh failed: ' + message)
+            lastError = message
+          }
+          wakeAfter(retryDelay(currentConfig(), failures))
+          break
+        } finally {
+          if (activeController === controller) activeController = undefined
+        }
+      }
+    } finally {
+      running = false
+      if (rerun && !wakeDispose && !stopped) void drain()
+    }
+  }
+
+  const schedule = ({ authOnly = false } = {}) => {
+    if (stopped) return
+    if (authOnly) authOnlyRequested = true
+    cancelWake()
+    rerun = true
+    activeController?.abort(new Error('CLIProxyAPI provider refresh superseded'))
+    if (!running) syncContext.runInAsyncScope(() => void drain())
+  }
+
+  const scheduleFromSettings = (force = false) => {
+    const profile = currentProfile()
+    const refreshKey = refreshKeyOf(profile, currentConfig())
+    if (!force && refreshKey === observedRefreshKey) return
+    observedRefreshKey = refreshKey
+    schedule()
+  }
+
+  ctx.on('settings/document-updated', (ns) => {
+    if (ns === PI_NS) scheduleFromSettings()
+    else if (ns === DISCOVERY_NS) schedule()
+  })
+  ctx.on('credentials/reference-updated', (ref) => {
+    if (ref === API_KEY_REF) schedule({ authOnly: true })
+  })
+  ctx.effect(() => () => {
+    stopped = true
+    cancelWake()
+    activeController?.abort(new Error('CLIProxyAPI provider plugin disposed'))
+    syncContext.emitDestroy()
+  })
+
+  scheduleFromSettings(true)
+}

package/src/migration.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto'
+import { ConnectionError, validateEndpoint } from './connection.js'
+import { credentialField } from './secrets.js'
+import { PROTOCOLS, validatePolicy } from './policy.js'
+
+const OWN = 'llm-cliproxyapi'
+const LEGACY = 'llm-pi-ai'
+const PROVIDER = 'CLIProxyAPI'
+const fingerprintOf = (profile) => createHash('sha256').update(JSON.stringify(profile)).digest('hex')
+const PLACEHOLDER = 'Bearer dsh-cliproxyapi-no-key'
+function portableProfile(value) {
+  const profile = structuredClone(value)
+  if (profile.headers) {
+    for (const [key, header] of Object.entries(profile.headers)) {
+      if (key.toLowerCase() === 'x-dsh-provider-cpa-sync' || key.toLowerCase() === 'authorization' && header === PLACEHOLDER) delete profile.headers[key]
+    }
+  }
+  return profile
+}
+function containsSecrets(value) {
+  if (!value || typeof value !== 'object') return false
+  return Object.entries(value).some(([key, item]) => credentialField(key) || containsSecrets(item))
+}
+function rows(settings) {
+  const entries = settings.describe()
+  return { own: entries.find((row) => row.ns === OWN), legacy: entries.find((row) => row.ns === LEGACY) }
+}
+export function legacyView(settings) {
+  const { legacy } = rows(settings)
+  const profile = legacy?.user?.providers?.[PROVIDER]
+  if (!profile) return { available: false }
+  if (legacy.base?.providers?.[PROVIDER]) return { available: false, reason: 'Legacy provider also exists in a base layer' }
+  if (!profile.baseURL) return { available: false, reason: 'Legacy endpoint is missing' }
+  if (containsSecrets(portableProfile(profile))) return { available: false, reason: 'Legacy provider contains a secret field requiring manual migration' }
+  return { available: true, baseURL: profile.baseURL, revision: legacy.revision, fingerprint: fingerprintOf(profile) }
+}
+async function setOwn(settings, values, revision) {
+  await settings.mutate(OWN, Object.entries(values).map(([key, value]) => ({ op: 'set', path: [key], value })), revision)
+}
+export async function prepareLegacy(settings, input) {
+  const { own, legacy } = rows(settings)
+  if (!own || !legacy || own.revision !== input.expectedRevision || legacy.revision !== input.expectedLegacyRevision) throw new ConnectionError('SETTINGS_CONFLICT', 'Settings changed before migration')
+  if (own.value?.baseURL || own.value?.migration) throw new ConnectionError('MIGRATION_CONFLICT', 'Connection already exists')
+  const summary = legacyView(settings)
+  if (!summary.available || summary.fingerprint !== input.fingerprint) throw new ConnectionError('MIGRATION_CONFLICT', summary.reason ?? 'Legacy provider changed')
+  const profile = portableProfile(legacy.user.providers[PROVIDER])
+  validateEndpoint(profile.baseURL)
+  if (profile.api !== undefined && !PROTOCOLS.includes(profile.api)) throw new ConnectionError('MIGRATION_UNSUPPORTED', 'Legacy wire protocol cannot be migrated')
+  const known = new Set(['displayName', 'api', 'baseURL', 'apiKeyEnv', 'models', 'modelOverrides', 'defaultContextWindow', 'defaultMaxTokens', 'defaultInput', 'headers', 'compat', 'retryPolicy', 'reasoning', 'thinkingBudgets', 'streamIdleTimeoutMs', 'maxRequestImageBytes', 'maxRequestImages', 'imageOffloadCountQuantum', 'requestImagePixelBudget', 'requestImageMaxBytes', 'cacheRetention', 'transport', 'timeoutMs', 'websocketConnectTimeoutMs'])
+  if (Object.keys(profile).some((key) => !known.has(key))) throw new ConnectionError('MIGRATION_UNSUPPORTED', 'Legacy provider has unsupported fields')
+  if (typeof input.operationId !== 'string' || !input.operationId) throw new ConnectionError('INVALID_OPERATION', 'An operation ID is required')
+  const generation = createHash('sha256').update(input.operationId).update('\0').update(String(own.revision)).digest('hex')
+  const authIdentity = profile.apiKeyEnv ? { type: 'reference', ref: profile.apiKeyEnv } : { type: 'none' }
+  const { baseURL, apiKeyEnv, models, modelOverrides, ...policy } = profile
+  validatePolicy(policy)
+  const overrides = {}
+  for (const model of models ?? []) {
+    const { id, input, ...rest } = model
+    if (typeof id !== 'string' || !id || Object.keys(rest).some((key) => !['name', 'contextWindow', 'maxTokens', 'reasoningEfforts', 'compat'].includes(key))) throw new ConnectionError('MIGRATION_UNSUPPORTED', 'Legacy model has unsupported fields')
+    overrides[id] = { ...rest, ...(input === undefined ? {} : { inputModalities: input }) }
+  }
+  for (const [id, value] of Object.entries(modelOverrides ?? {})) {
+    const { input, ...rest } = value
+    if (Object.keys(rest).some((key) => !['name', 'contextWindow', 'maxTokens', 'reasoningEfforts', 'compat'].includes(key))) throw new ConnectionError('MIGRATION_UNSUPPORTED', 'Legacy model override has unsupported fields')
+    overrides[id] = { ...overrides[id], ...rest, ...(rest.compat && overrides[id]?.compat ? { compat: { ...overrides[id].compat, ...rest.compat } } : {}), ...(input === undefined ? {} : { inputModalities: input }) }
+  }
+  const migration = { phase: 'prepared', operationId: input.operationId, generation, legacyRevision: legacy.revision, fingerprint: summary.fingerprint, backupFingerprint: fingerprintOf(profile), backup: profile, provenance: 'legacy' }
+  await setOwn(settings, { baseURL, authIdentity, enabled: true, generation, operationId: input.operationId, policy, overrides, migration }, own.revision)
+  return migration
+}
+// Undo a prepared-but-not-cut-over migration. The legacy provider is still in
+// place at this point, so only our own row is cleared; rollbackLegacy is for the
+// post-cutover case where the legacy entry has to be restored.
+export async function discardPrepared(settings) {
+  const { own } = rows(settings)
+  const migration = own?.value?.migration
+  if (!migration || migration.phase !== 'prepared') return false
+  if (own.value.generation !== migration.generation) throw new ConnectionError('MIGRATION_CONFLICT', 'Connection changed after migration; forward repair is required')
+  await settings.mutate(OWN, ['baseURL', 'authIdentity', 'generation', 'operationId', 'policy', 'overrides', 'migration'].map((key) => ({ op: 'unset', path: [key] })), own.revision)
+  return true
+}
+export async function cutoverLegacy(settings) {
+  let { own, legacy } = rows(settings)
+  let migration = own?.value?.migration
+  if (!migration || !['prepared', 'cutover'].includes(migration.phase)) return false
+  const current = legacy?.user?.providers?.[PROVIDER]
+  if (legacy?.base?.providers?.[PROVIDER]) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider exists in a base layer')
+  if (current && fingerprintOf(current) !== migration.fingerprint) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider changed during migration')
+  if (migration.phase === 'prepared') {
+    if (!current || legacy.revision !== migration.legacyRevision) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider changed before cutover')
+    migration = { ...migration, phase: 'cutover' }
+    await setOwn(settings, { migration }, own.revision)
+      ; ({ own, legacy } = rows(settings))
+  }
+  if (legacy?.user?.providers?.[PROVIDER]) await settings.mutate(LEGACY, [{ op: 'unset', path: ['providers', PROVIDER] }], legacy.revision)
+    ; ({ legacy } = rows(settings))
+  if (legacy?.value?.providers?.[PROVIDER]) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider remains after cutover')
+  return true
+}
+export async function finishLegacy(settings) {
+  const { own, legacy } = rows(settings)
+  if (own?.value?.migration?.phase !== 'cutover' || legacy?.value?.providers?.[PROVIDER]) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy cutover is not complete')
+  await setOwn(settings, { migration: { ...own.value.migration, phase: 'active' } }, own.revision)
+}
+
+export async function rollbackLegacy(settings, releaseRoute) {
+  let { own, legacy } = rows(settings)
+  const migration = own?.value?.migration
+  if (!migration || own.value.generation !== migration.generation) throw new ConnectionError('MIGRATION_CONFLICT', 'Connection changed after migration; forward repair is required')
+  let ownedRevision = own.revision
+  const checkOwner = () => {
+    const current = rows(settings).own
+    if (current?.revision !== ownedRevision || current.value?.generation !== migration.generation || current.value?.migration?.operationId !== migration.operationId || current.value?.migration?.generation !== migration.generation) throw new ConnectionError('MIGRATION_CONFLICT', 'Connection changed during rollback; forward repair is required')
+  }
+  if (legacy?.base?.providers?.[PROVIDER]) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider exists in a base layer')
+  if (migration.phase !== 'rollback') {
+    if (legacy?.value?.providers?.[PROVIDER] || legacy?.user?.providers?.[PROVIDER]) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider already exists')
+    await setOwn(settings, { migration: { ...migration, phase: 'rollback' } }, own.revision)
+    ownedRevision += 1
+    checkOwner()
+  }
+  await releaseRoute()
+  checkOwner()
+    ; ({ own, legacy } = rows(settings))
+  const existing = legacy?.user?.providers?.[PROVIDER]
+  if (legacy?.base?.providers?.[PROVIDER] || (existing && fingerprintOf(existing) !== migration.backupFingerprint) || (!existing && legacy?.value?.providers?.[PROVIDER])) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy provider appeared during rollback')
+  if (!existing) await settings.mutate(LEGACY, [{ op: 'set', path: ['providers', PROVIDER], value: migration.backup }], legacy.revision)
+  checkOwner()
+    ; ({ own, legacy } = rows(settings))
+  if (!legacy?.user?.providers?.[PROVIDER] || fingerprintOf(legacy.user.providers[PROVIDER]) !== migration.backupFingerprint) throw new ConnectionError('MIGRATION_CONFLICT', 'Legacy rollback could not be confirmed')
+  await settings.mutate(OWN, ['baseURL', 'authIdentity', 'generation', 'operationId', 'policy', 'overrides', 'migration'].map((key) => ({ op: 'unset', path: [key] })), ownedRevision)
+}