@astrale-os/cli 0.8.1-alpha.6 → 0.8.1-alpha.7

package/src/connection/errors.ts

@@ -1,21 +1,24 @@
 import chalk from 'chalk'
 
-import type { SelfExpansionMeta } from './self'
-
 import { AstraleError } from '../errors'
-import { decodeJwtExpiration, readLocalStatus, type LocalStatus } from '../lib/local-status'
+import { readLocalStatus, type LocalStatus } from '../lib/local-status'
 import { log } from '../lib/log'
+import {
+  functionInputIssues,
+  queryInputRepair,
+  reasonCode,
+  schemaUpgradeDetails,
+  schemaUpgradeHint,
+  type FunctionInputIssue,
+  type QueryInputRepair,
+} from './reasons'
 
-type FieldError = { path: string[]; code: string; message: string }
-type InvariantError = { code: string; message: string; context?: unknown }
+export { functionInputIssues, schemaUpgradeHint } from './reasons'
 
 /**
  * Format and display a kernel client error.
  *
- * Handles AstraleError (CLI-local) and every error class exported by
- * @astrale-os/kernel-client: ConnectionError, DisconnectedError,
- * TimeoutError, AuthenticationError, PermissionDeniedError, NotFoundError,
- * KernelError and its subclasses (ValidationError, InvariantViolationError).
+ * Handles CLI-local errors plus the current Kernel Client public error families.
  *
  * When `debug` is true, additional diagnostic information (class name, full
  * error chain, attached url/details) is printed after the user-facing line.
@@ -25,12 +28,10 @@ export async function formatKernelError(
   isRaw: boolean,
   urlArg = '',
   debug = false,
-  opts: { credential?: string } = {},
 ): Promise<void> {
   const url =
     urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
   const localContext = await contextForError(error)
-  const credentialExpiration = opts.credential ? decodeJwtExpiration(opts.credential) : null
   // Handle AstraleError (AuthError, etc.) with structured hints
   if (error instanceof AstraleError) {
     if (isRaw) {
@@ -52,167 +53,60 @@ export async function formatKernelError(
   const name = error.name
 
   switch (name) {
-    case 'ConnectionError':
-      if (isRaw)
-        writeRaw({ error: 'CONNECTION_ERROR', message: error.message, url, context: localContext })
-      else {
-        log.error(`Could not connect to ${chalk.bold(url || 'kernel')}`)
-        log.dim(`  ${error.message}`)
-        log.dim('  Is the kernel running? Try: astrale status')
-        printLocalContext(localContext)
-      }
-      break
-
-    case 'DisconnectedError':
-      if (isRaw) writeRaw({ error: 'DISCONNECTED', message: error.message })
-      else {
-        log.error('Connection closed while request was pending')
-        log.dim('  The kernel may have been stopped or restarted. Retry the command.')
-      }
-      break
-
-    case 'TimeoutError': {
-      const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
-      if (isRaw) writeRaw({ error: 'TIMEOUT', message: error.message, timeoutMs })
-      else {
-        log.error(`Request timed out after ${timeoutMs ?? '?'}ms`)
-        log.dim('  Try increasing with --timeout')
-      }
-      break
-    }
-
-    case 'AuthenticationError': {
-      const reason = (error as { reason?: string }).reason ?? 'unknown'
-      if (isRaw)
-        writeRaw({
-          error: 'AUTH_ERROR',
-          reason,
-          message: error.message,
-          credential: credentialExpiration,
-          context: localContext,
-        })
-      else {
-        log.error(`Authentication failed: ${error.message}`)
-        if (reason === 'missing')
-          log.dim('  No credential was sent. Run: astrale identity create <name>')
-        else if (reason === 'invalid')
-          log.dim('  Credential is invalid — check issuer/keypair. Try: astrale identity whoami')
-        else if (reason === 'expired') log.dim('  Credential expired — sign a fresh one')
-        if (credentialExpiration) {
-          const state = credentialExpiration.expired ? 'expired' : 'expires'
-          log.dim(`  Credential ${state} at ${credentialExpiration.expiresAt}`)
-        }
-        printLocalContext(localContext)
-      }
-      break
-    }
-
-    case 'PermissionDeniedError':
-      if (isRaw) writeRaw({ error: 'PERMISSION_DENIED', message: error.message })
-      else {
-        log.error(`Permission denied: ${error.message}`)
-        log.dim('  Your identity does not have the required permissions for this operation')
-      }
-      break
-
-    case 'NotFoundError': {
-      const cleanMsg = stripMethodSuffix(error.message)
-      const selfMeta = (error as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf
-      // kernel-client maps both NOT_FOUND (the node doesn't exist) and
-      // METHOD_NOT_FOUND (the method doesn't exist on a real node) to
-      // `NotFoundError`. Firing the authenticated-principal hint for the
-      // method case is misleading. Gate on the message referencing the
-      // expanded id — node lookup errors mention `@<id>` whereas method
-      // errors mention the method path.
-      const selfHintApplies = selfMeta && error.message.includes(`@${selfMeta.selfId}`)
-      if (isRaw) {
-        const payload: Record<string, unknown> = { error: 'NOT_FOUND', message: cleanMsg }
-        if (selfHintApplies) payload.expandedFromSelf = selfMeta
-        writeRaw(payload)
-      } else {
-        log.error(`Not found: ${cleanMsg}`)
-        log.dim('  Check the path/ID and that the instance is booted')
-        if (selfHintApplies && selfMeta) {
-          const where = selfMeta.slug ? ` on "${selfMeta.slug}"` : ''
-          log.dim(
-            `  @self resolved through authenticated Identity.whoami to @${selfMeta.selfId}${where}.`,
-          )
-          log.dim('  Check that the requested node path still exists for that principal.')
-        }
-      }
-      break
-    }
-
-    case 'ValidationError': {
-      const errors = (error as { errors?: FieldError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'VALIDATION_ERROR', message: error.message, details: errors })
-      else {
-        log.error('Validation Error')
-        if (errors.length > 0) {
-          for (const e of errors) {
-            console.log(chalk.red(`  ${e.path.join('.')}: ${e.message} (${chalk.dim(e.code)})`))
-          }
-        } else {
-          // Server often sends details in message but empty errors array
-          console.log(chalk.red(`  ${error.message}`))
-        }
-        log.dim('  Use `astrale introspect <path>` to see the expected schema')
-      }
-      break
-    }
-
-    case 'InvariantViolationError': {
-      const errors = (error as { errors?: InvariantError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'INVARIANT_VIOLATION', message: error.message, details: errors })
-      else {
-        log.error('Invariant Violation')
-        for (const e of errors) {
-          console.log(chalk.red(`  ${e.code}: ${e.message}`))
-          if (e.context) console.log(chalk.dim(`    ${JSON.stringify(e.context)}`))
-        }
-      }
+    case 'TransportError':
+      presentTransportError(error, isRaw, url, localContext)
       break
-    }
 
     case 'ResponseError': {
       const code = (error as { readonly code?: unknown }).code
       const reason = (error as { readonly reason?: unknown }).reason
-      const reasonCode =
-        reason !== null &&
-        typeof reason === 'object' &&
-        typeof (reason as { readonly code?: unknown }).code === 'string'
-          ? (reason as { readonly code: string }).code
-          : undefined
+      const codeOfReason = reasonCode(reason)
+      const inputIssues = functionInputIssues(reason)
+      const queryRepair = queryInputRepair(reason)
+      const upgrade = schemaUpgradeDetails(reason)
+      const removalHint = schemaDataRemovalHint(reason)
+      const domainAddressNotPublic = codeOfReason === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
+      const displayMessage = domainAddressNotPublic
+        ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
+        : removalHint !== undefined && !isRaw
+          ? 'Existing business data still uses schema definitions being removed.'
+          : error.message
       const hint =
-        reasonCode === 'FUNCTION_INPUT_INVALID'
+        codeOfReason === 'FUNCTION_INPUT_INVALID' && (isRaw || inputIssues.length === 0)
           ? 'Use `astrale introspect <path>` to see the callable input.'
-          : undefined
+          : (removalHint ?? (upgrade === undefined ? undefined : schemaUpgradeHint(upgrade)))
       if (isRaw) {
         writeRaw({
           error: 'RESPONSE_ERROR',
           ...(code === undefined ? {} : { code }),
-          message: error.message,
+          message: displayMessage,
           ...(reason === undefined ? {} : { reason }),
           ...(hint === undefined ? {} : { hint }),
         })
       } else {
         log.error(
-          `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${error.message}`,
+          domainAddressNotPublic
+            ? `${chalk.bold('SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC')}: ${displayMessage}`
+            : removalHint !== undefined
+              ? `${chalk.bold('DATA_MIGRATION_REQUIRED')}: ${displayMessage}`
+              : `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${displayMessage}`,
         )
-        if (reasonCode !== undefined) log.dim(`  reason: ${reasonCode}`)
+        if (codeOfReason !== undefined && !domainAddressNotPublic && removalHint === undefined) {
+          log.dim(`  reason: ${codeOfReason}`)
+        }
+        presentFunctionInputIssues(inputIssues)
+        if (queryRepair !== undefined) presentQueryInputRepair(queryRepair)
+        if (upgrade?.expected !== undefined) {
+          log.dim(`  installed issuer: ${upgrade.expected}`)
+        }
+        if (upgrade?.actual !== undefined) {
+          log.dim(`  replacement issuer: ${upgrade.actual}`)
+        }
         if (hint !== undefined) log.dim(`  ${hint}`)
       }
       break
     }
 
-    case 'KernelError': {
-      const code = (error as { code?: number | string }).code ?? 'UNKNOWN'
-      const type = (error as { type?: string }).type ?? 'KERNEL_ERROR'
-      if (isRaw) writeRaw({ error: type, code, message: error.message })
-      else log.error(`${chalk.bold(`${type}(${code})`)}: ${error.message}`)
-      break
-    }
-
     default: {
       const mapped = mapPublicError(error)
       if (isRaw) {
@@ -232,9 +126,28 @@ export async function formatKernelError(
   if (debug) printDebug(error, url)
 }
 
-/** Strip internal `::methodName` suffixes from paths in error messages (e.g., "/path::listChildren" → "/path") */
-export function stripMethodSuffix(msg: string): string {
-  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
+function schemaDataRemovalHint(reason: unknown): string | undefined {
+  if (reason === null || typeof reason !== 'object') return undefined
+  const value = reason as { readonly code?: unknown; readonly details?: unknown }
+  if (value.code !== 'DATA_MIGRATION_REQUIRED') return undefined
+  if (value.details === null || typeof value.details !== 'object') return undefined
+
+  const requirements = (value.details as { readonly requirements?: unknown }).requirements
+  if (
+    !Array.isArray(requirements) ||
+    requirements.length === 0 ||
+    !requirements.every(
+      (requirement) =>
+        requirement !== null &&
+        typeof requirement === 'object' &&
+        (requirement as { readonly operation?: unknown }).operation === 'remove-facts' &&
+        (requirement as { readonly reason?: unknown }).reason === 'destructive-change',
+    )
+  ) {
+    return undefined
+  }
+
+  return 'Delete this data explicitly, then retry. No data was deleted.'
 }
 
 function mapPublicError(error: Error): {
@@ -273,14 +186,80 @@ function mapPublicError(error: Error): {
       hint: 'Pass the Kernel issuer URL (no /invoke suffix), e.g. https://host/kernel/host',
     }
   }
-  if (name === 'Error' && /unable to connect/i.test(error.message)) {
-    return {
-      code: 'CONNECTION_ERROR',
+  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
+}
+
+function presentTransportError(
+  error: Error,
+  isRaw: boolean,
+  url: string,
+  context: LocalStatus | undefined,
+): void {
+  const phase = transportPhase(error)
+  const delivery = transportDelivery(error)
+  const code =
+    phase === 'connect'
+      ? 'CONNECTION_ERROR'
+      : phase === 'timeout'
+        ? 'TIMEOUT'
+        : phase === 'closed'
+          ? 'DISCONNECTED'
+          : 'TRANSPORT_ERROR'
+  if (isRaw) {
+    writeRaw({
+      error: code,
       message: error.message,
-      hint: 'Check --url / -i and that the Kernel is reachable. Try: astrale status',
-    }
+      ...(url === '' ? {} : { url }),
+      ...(phase === undefined ? {} : { phase }),
+      ...(delivery === undefined ? {} : { delivery }),
+      ...(context === undefined ? {} : { context }),
+    })
+    return
   }
-  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
+  log.error(`${chalk.bold(code)}: ${error.message}`)
+  if (url !== '') log.dim(`  target: ${url}`)
+  if (phase !== undefined) log.dim(`  phase: ${phase}`)
+  if (phase === 'connect') log.dim('  Check the target and run `astrale status`.')
+  else if (phase === 'timeout') log.dim('  Try increasing `--timeout`.')
+  else if (delivery === 'unknown') {
+    log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
+  }
+  printLocalContext(context)
+}
+
+function presentFunctionInputIssues(issues: readonly FunctionInputIssue[]): void {
+  for (const issue of issues) {
+    const location = issue.path === undefined || issue.path === '' ? '<input>' : issue.path
+    console.log(chalk.red(`  ${location}: ${issue.message} (${chalk.dim(issue.code)})`))
+  }
+}
+
+function presentQueryInputRepair(repair: QueryInputRepair): void {
+  if (repair.phase === 'plan') {
+    log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
+    return
+  }
+  if (repair.phase === 'limit') {
+    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
+    return
+  }
+  log.dim(`  ${repair.path}  ${repair.phase} input`)
+}
+
+function transportPhase(error: Error): string | undefined {
+  const phase = (error as Error & { readonly phase?: unknown }).phase
+  return phase === 'connect' ||
+    phase === 'send' ||
+    phase === 'receive' ||
+    phase === 'timeout' ||
+    phase === 'closed'
+    ? phase
+    : undefined
+}
+
+function transportDelivery(error: Error): string | undefined {
+  const delivery = (error as Error & { readonly delivery?: unknown }).delivery
+  return delivery === 'not-sent' || delivery === 'unknown' ? delivery : undefined
 }
 
 function writeRaw(payload: Record<string, unknown>): void {
@@ -289,7 +268,7 @@ function writeRaw(payload: Record<string, unknown>): void {
 
 async function contextForError(error: unknown): Promise<LocalStatus | undefined> {
   if (!(error instanceof Error)) return undefined
-  if (error.name !== 'AuthenticationError' && error.name !== 'ConnectionError') return undefined
+  if (error.name !== 'TransportError') return undefined
   return readLocalStatus().catch(() => undefined)
 }
 

package/src/connection/exchange.ts

@@ -156,6 +156,7 @@ async function exchange(
     try {
       admitted = exchangeProtocol.acceptErrorResponse(body)
     } catch (cause) {
+      if (!(cause instanceof TypeError)) throw cause
       throw new AstraleError(
         'TOKEN_EXCHANGE_PROTOCOL_ERROR',
         `Token exchange failed with HTTP ${response.status} and an invalid error response.`,
@@ -165,8 +166,19 @@ async function exchange(
     throw new AstraleError(String(admitted.error.code), admitted.error.message)
   }
   requireExchangeResponseHeaders(response)
-  const exchanged = exchangeProtocol.acceptResponse(body)
-  const inspected = credential.inspect(exchanged.token)
+  let exchanged: exchangeProtocol.Response
+  let inspected: ReturnType<typeof credential.inspect>
+  try {
+    exchanged = exchangeProtocol.acceptResponse(body)
+    inspected = credential.inspect(exchanged.token)
+  } catch (cause) {
+    if (!(cause instanceof TypeError)) throw cause
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange returned an invalid success response.',
+      cause.message,
+    )
+  }
   if (
     inspected.iss !== domainIssuer ||
     inspected.aud !== kernelIssuer ||

package/src/connection/reasons.ts

@@ -0,0 +1,179 @@
+export type FunctionInputIssue = Readonly<{
+  code: string
+  path?: string
+  message: string
+}>
+
+export type QueryInputRepair =
+  | Readonly<{ phase: 'decode' | 'input'; path: string }>
+  | Readonly<{ phase: 'plan'; issue: string; path?: string }>
+  | Readonly<{
+      phase: 'limit'
+      limit: string
+      maximum: number
+      actual: number
+      path?: string
+    }>
+
+export type SchemaUpgradeDetails = {
+  readonly origin?: string
+  readonly issue?: string
+  readonly expected?: string
+  readonly actual?: string
+}
+
+const JSON_POINTER = /^(?:\/(?:[^~/]|~[01])*)*$/u
+const MAXIMUM_FUNCTION_ISSUES = 32
+const MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH = 512
+
+export function reasonCode(reason: unknown): string | undefined {
+  if (!record(reason) || typeof reason.code !== 'string') return undefined
+  return stableCode(reason.code) ? reason.code : undefined
+}
+
+/** Admit only bounded caller-safe Function input issues established by the Kernel. */
+export function functionInputIssues(reason: unknown): readonly FunctionInputIssue[] {
+  if (!reasonWithCode(reason, 'FUNCTION_INPUT_INVALID')) return Object.freeze([])
+  const issues = reason.details.issues
+  if (!Array.isArray(issues)) return Object.freeze([])
+  return Object.freeze(
+    issues.slice(0, MAXIMUM_FUNCTION_ISSUES).flatMap((candidate): FunctionInputIssue[] => {
+      if (
+        !record(candidate) ||
+        typeof candidate.code !== 'string' ||
+        !stableCode(candidate.code) ||
+        typeof candidate.message !== 'string' ||
+        candidate.message.length === 0 ||
+        candidate.message.length > MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH ||
+        candidate.message.normalize('NFC') !== candidate.message ||
+        containsControl(candidate.message) ||
+        (candidate.path !== undefined && !coordinate(candidate.path))
+      ) {
+        return []
+      }
+      return [
+        Object.freeze({
+          code: candidate.code,
+          ...(candidate.path === undefined ? {} : { path: candidate.path }),
+          message: candidate.message,
+        }),
+      ]
+    }),
+  )
+}
+
+/** Admit only public Query-input repair variants; unknown details remain machine-only. */
+export function queryInputRepair(reason: unknown): QueryInputRepair | undefined {
+  if (!reasonWithCode(reason, 'QUERY_INPUT_INVALID')) return undefined
+  const details = reason.details
+  if (details.phase === 'decode' || details.phase === 'input') {
+    if (!exact(details, ['phase', 'path']) || !coordinate(details.path)) return undefined
+    return Object.freeze({ phase: details.phase, path: details.path })
+  }
+  if (details.phase === 'plan') {
+    const fields = details.path === undefined ? ['phase', 'issue'] : ['phase', 'issue', 'path']
+    if (
+      !exact(details, fields) ||
+      typeof details.issue !== 'string' ||
+      !stableCode(details.issue) ||
+      (details.path !== undefined && !coordinate(details.path))
+    ) {
+      return undefined
+    }
+    return Object.freeze({
+      phase: 'plan',
+      issue: details.issue,
+      ...(details.path === undefined ? {} : { path: details.path }),
+    })
+  }
+  if (details.phase !== 'limit') return undefined
+  const fields =
+    details.path === undefined
+      ? ['phase', 'limit', 'maximum', 'actual']
+      : ['phase', 'limit', 'maximum', 'actual', 'path']
+  if (
+    !exact(details, fields) ||
+    typeof details.limit !== 'string' ||
+    !Number.isSafeInteger(details.maximum) ||
+    (details.maximum as number) < 0 ||
+    !Number.isSafeInteger(details.actual) ||
+    (details.actual as number) <= (details.maximum as number) ||
+    (details.path !== undefined && !coordinate(details.path))
+  ) {
+    return undefined
+  }
+  return Object.freeze({
+    phase: 'limit',
+    limit: details.limit,
+    maximum: details.maximum as number,
+    actual: details.actual as number,
+    ...(details.path === undefined ? {} : { path: details.path }),
+  })
+}
+
+/** Decode bounded recovery guidance while preserving the admitted reason itself elsewhere. */
+export function schemaUpgradeDetails(reason: unknown): SchemaUpgradeDetails | undefined {
+  if (!record(reason) || reason.code !== 'SCHEMA_UPGRADE_INCOMPATIBLE') return undefined
+  const details = record(reason.details) ? reason.details : {}
+  return {
+    ...(typeof details.origin === 'string' ? { origin: details.origin } : {}),
+    ...(typeof details.issue === 'string' ? { issue: details.issue } : {}),
+    ...(typeof details.expected === 'string' ? { expected: details.expected } : {}),
+    ...(typeof details.actual === 'string' ? { actual: details.actual } : {}),
+  }
+}
+
+export function schemaUpgradeHint(details: SchemaUpgradeDetails): string {
+  const target = details.origin ?? '<origin>'
+  const explanation =
+    details.expected !== undefined && details.actual !== undefined
+      ? 'A replacement cannot change an installed Domain issuer.'
+      : 'The replacement changes an immutable part of the installed Domain.'
+  return (
+    `${explanation} If this change is intentional, first run ` +
+    `\`astrale domain uninstall ${target}\`, then install it again. ` +
+    'The Kernel refuses uninstall while dependents or business data remain; uninstall never deletes business data.'
+  )
+}
+
+function reasonWithCode(
+  input: unknown,
+  code: string,
+): input is Readonly<{ code: string; details: Readonly<Record<string, unknown>> }> {
+  return (
+    record(input) &&
+    exact(input, ['code', 'details']) &&
+    input.code === code &&
+    record(input.details)
+  )
+}
+
+function coordinate(input: unknown): input is string {
+  return (
+    typeof input === 'string' &&
+    input.length <= 1_024 &&
+    input.normalize('NFC') === input &&
+    JSON_POINTER.test(input)
+  )
+}
+
+function stableCode(input: string): boolean {
+  return /^[A-Z][A-Z0-9_]{0,127}$/u.test(input) && input.normalize('NFC') === input
+}
+
+function containsControl(input: string): boolean {
+  for (const character of input) {
+    const point = character.codePointAt(0)!
+    if (point <= 0x1f || point === 0x7f) return true
+  }
+  return false
+}
+
+function record(input: unknown): input is Readonly<Record<string, unknown>> {
+  return input !== null && typeof input === 'object' && !Array.isArray(input)
+}
+
+function exact(input: Readonly<Record<string, unknown>>, fields: readonly string[]): boolean {
+  const actual = Object.keys(input)
+  return actual.length === fields.length && actual.every((field) => fields.includes(field))
+}

package/src/lib/__tests__/instance.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 
-import { InstanceStoreSchema, normalizeInstanceKernelUrl, sanitizeStore } from '../instance'
+import {
+  findBookmarkTrustConflicts,
+  InstanceStoreSchema,
+  normalizeInstanceKernelUrl,
+  sanitizeStore,
+} from '../instance'
 
 describe('InstanceStoreSchema', () => {
   test('parses valid store with url', () => {
@@ -134,3 +139,48 @@ describe('sanitizeStore — read must not rewrite', () => {
     expect(changed).toBe(false)
   })
 })
+
+describe('bookmark TLS trust collisions', () => {
+  test('finds the same normalized URL with a different CA configuration', () => {
+    const store = InstanceStoreSchema.parse({
+      active: 'stable',
+      instances: {
+        stable: {
+          url: 'https://local.example/kernel/',
+          caFile: '/certs/stable.pem',
+        },
+        alias: {
+          url: 'https://local.example/kernel',
+          caFile: '/certs/old.pem',
+        },
+        other: {
+          url: 'https://other.example/kernel',
+          caFile: '/certs/old.pem',
+        },
+      },
+    })
+
+    expect(
+      findBookmarkTrustConflicts(
+        store,
+        'stable',
+        'https://local.example/kernel',
+        '/certs/stable.pem',
+      ),
+    ).toEqual([{ name: 'alias', caFile: '/certs/old.pem' }])
+  })
+
+  test('treats custom CA versus system trust as a meaningful difference', () => {
+    const store = InstanceStoreSchema.parse({
+      active: 'custom',
+      instances: {
+        custom: { url: 'https://local.example', caFile: '/certs/local.pem' },
+        system: { url: 'https://local.example' },
+      },
+    })
+
+    expect(
+      findBookmarkTrustConflicts(store, 'custom', 'https://local.example', '/certs/local.pem'),
+    ).toEqual([{ name: 'system', caFile: null }])
+  })
+})