// src/backend-contract/backend.ts

import type { AdvertisementObservation, OwnerScanOptions } from './advertisement'
import type { FeatureRegistry } from './capabilities'
import {
  attachmentRecordsEqual,
  type AdapterStateSnapshot,
  type AdapterStateWatch,
  type AttachmentRecord,
  type BackendIdentity,
  type BackendRuntimeMetadata
} from './identity'
import type { CharacteristicPath, ConnectionPath, DatabasePath, DescriptorPath, GattDatabase } from './gatt'
import type { NotificationValue } from './gatt'
import type {
  BackendOperationDispatch,
  OperationOptions,
  OperationTerminalRecord,
  PublicOperationOptions,
  ReadRequest,
  ReadResult,
  SubscribeRequest,
  WriteRequest,
  WriteResult
} from './operations'
import type {
  ConnectionMaximumWriteLengthMeasurement,
  ConnectionMaximumWriteLengthRequest,
  ConnectionPhyObservation,
  ConnectionPhyRequest,
  ConnectionPriorityRequest,
  ConnectionWriteReadinessWatch,
  EffectiveMtuMeasurement,
  EffectiveMtuRequest,
  MtuNegotiation,
  ReadRssiRequest,
  ReadPhyRequest,
  RequestPhyRequest,
  RequestPriorityRequest,
  RequestMtuRequest,
  RssiMeasurement
} from './connection-controls'
import { contractError } from './errors'
import type { CleanupRecord } from './errors'
import type {
  ApplicableVersionAxes,
  AttachmentId,
  BackendCompatibilityOffer,
  ClientId,
  ConnectionId,
  GenerationId,
  LeaseId,
  ManagerId,
  PeerId,
  ResourceCount,
  ScanShareToken,
  ScanSessionId,
  SubscriptionId,
  SerializableRecord
} from './primitives'
import { applicableVersionAxesEqual, assertCoreVersionsAccepted, snapshotApplicableVersionAxes } from './primitives'
import { serializableRecordsEqual, snapshotSerializableRecord } from './serializable'
import type { BoundedAsyncStream } from './streams'
import type { ManagerRestorationCapability } from './restoration'
import type { PeerReference } from './peer-reference'
import type { SecurityBackend } from './security'
import type { DiagnosticTraceDocument } from '../diagnostics/trace-format'
import type { NormalizedScanQuery } from './scan-query'
import type { ScanPlan } from './scan-planning'

export type OwnerMode = 'owning' | 'borrowing'
export type ManagerState = 'new' | 'ready' | 'destroying' | 'destroyed' | 'failed'
export type ConnectionState = 'connecting' | 'connected' | 'disconnecting' | 'disconnected' | 'lost'
export interface ResourceCounters {
  readonly activeScanControllers: ResourceCount
  readonly scanConsumers: ResourceCount
  readonly chooserSessions: ResourceCount
  readonly connectionLeases: ResourceCount
  readonly physicalLinks: ResourceCount
  readonly databaseSnapshots: ResourceCount
  readonly physicalCccdEnablements: ResourceCount
  readonly subscriptionConsumers: ResourceCount
  readonly queuedOperations: ResourceCount
  readonly dispatchedOperations: ResourceCount
  readonly retainedByteBuffers: ResourceCount
  readonly restorationRecords: ResourceCount
  readonly orphanedIpcOwners: ResourceCount
}
export interface AdapterBackend<Attachment extends string> {
  currentState(): Promise<AdapterStateSnapshot<Attachment>>
  watchState(): Promise<AdapterStateWatch<Attachment>>
}

export type PeerSource =
  | 'scan-observed'
  | 'app-reference'
  | 'system-connected'
  | 'system-bonded'
  | 'origin-authorized'
  | 'restored'
  | 'backend-cache'

export interface BlePeerState {
  readonly reachability: 'reachable' | 'unreachable' | 'unknown'
  readonly connection: 'connected' | 'disconnected' | 'unknown'
  readonly bond: 'bonded' | 'not-bonded' | 'unknown' | 'unsupported'
  readonly lastSeenAtMonotonicMs: number | null
}

export interface BackendPeerQuery extends PublicOperationOptions {
  readonly sources?: readonly PeerSource[]
  readonly services?: readonly string[]
  readonly references?: readonly PeerReference[]
  readonly includeUnavailable?: boolean
}

export interface BackendPeerRecord<Attachment extends string> {
  readonly reference: PeerReference
  readonly peerId: PeerId<Attachment>
  readonly name: string | null
  readonly rssi: number | null
  readonly source: PeerSource
  readonly state: BlePeerState
  readonly clockScope?: string
}

export interface PeerDirectoryBackend<Attachment extends string> {
  resolve(reference: PeerReference, options: BackendPeerQuery): Promise<BackendPeerRecord<Attachment> | null>
  known(options: BackendPeerQuery): Promise<readonly BackendPeerRecord<Attachment>[]>
  connected(options: BackendPeerQuery): Promise<readonly BackendPeerRecord<Attachment>[]>
  bonded(options: BackendPeerQuery): Promise<readonly BackendPeerRecord<Attachment>[]>
  authorized(options: BackendPeerQuery): Promise<readonly BackendPeerRecord<Attachment>[]>
  restored(options: BackendPeerQuery): Promise<readonly BackendPeerRecord<Attachment>[]>
}
export interface ScanLease<Attachment extends string, _Lease extends string> {
  readonly scanSessionId: ScanSessionId<Attachment, string>
  readonly leaseId: LeaseId<Attachment, string>
  readonly shareToken: ScanShareToken<Attachment, string> | null
  readonly observations: BoundedAsyncStream<AdvertisementObservation<Attachment>>
  stop(): Promise<CleanupRecord>
}
export interface ScannerBackend<Attachment extends string> {
  plan?(query: NormalizedScanQuery): ScanPlan
  start(
    options: OwnerScanOptions<Attachment, string>,
    clientId: ClientId<Attachment, string>
  ): Promise<ScanLease<Attachment, string>>
  join(
    sharedLeaseId: LeaseId<Attachment, string>,
    shareToken: ScanShareToken<Attachment, string>,
    clientId: ClientId<Attachment, string>
  ): Promise<ScanLease<Attachment, string>>
}
export interface ConnectionLease<Attachment extends string, _Connection extends string, _Lease extends string> {
  readonly leaseId: LeaseId<Attachment, string>
  readonly connection: BackendConnection<Attachment, string>
  release(): Promise<CleanupRecord>
}
export interface BackendConnection<Attachment extends string, _Connection extends string> {
  readonly attachment: AttachmentRecord<Attachment>
  readonly attachmentId: AttachmentId<Attachment>
  readonly peerId: PeerId<Attachment>
  readonly connectionId: ConnectionId<Attachment, string>
  readonly connectionGeneration: GenerationId<'connection-generation', string>
  readonly state: ConnectionState
  disconnect(): Promise<CleanupRecord>
}
export type ConnectionIntent = 'direct' | 'when-available'
/**
 * A canonical out-of-band radio address accepted by the optional `peer:address-targeting`
 * capability. Only public/static addresses are expressible; resolvable private addresses
 * must re-enter through a durable `PeerReference`.
 */
export interface PeerAddressDescriptor {
  readonly address: string
  readonly addressType: 'public' | 'random'
}
export type BlePhy = 'le-1m' | 'le-2m' | 'le-coded'
export interface ConnectionOptions extends PublicOperationOptions {
  readonly intent?: ConnectionIntent
  readonly transport?: 'le' | 'auto'
  readonly preferredPhy?: readonly BlePhy[]
}
export interface ConnectionBackend<Attachment extends string> {
  connect(
    peerId: PeerId<Attachment>,
    clientId: ClientId<Attachment, string>,
    options: ConnectionOptions
  ): Promise<ConnectionLease<Attachment, string, string>>
  /**
   * Optional `peer:address-targeting` seam: mints a connectable peer handle for a canonical
   * radio address known out of band, without requiring a prior scan observation. Backends
   * that do not register the capability leave this undefined and callers fail closed.
   */
  peerFromAddress?(descriptor: PeerAddressDescriptor): PeerId<Attachment>
  readRssi?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: ReadRssiRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, RssiMeasurement<Attachment, Operation>>
  requestMtu?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: RequestMtuRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, MtuNegotiation<Attachment, Operation>>
  effectiveMtu?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: EffectiveMtuRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, EffectiveMtuMeasurement<Attachment, Operation>>
  requestPriority?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: RequestPriorityRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ConnectionPriorityRequest<Attachment, Operation>>
  readPhy?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: ReadPhyRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ConnectionPhyObservation<Attachment, Operation>>
  requestPhy?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: RequestPhyRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ConnectionPhyRequest<Attachment, Operation>>
  writeWithoutResponseReadiness?(
    connection: BackendConnection<Attachment, string>,
    options?: PublicOperationOptions
  ): Promise<ConnectionWriteReadinessWatch<Attachment>>
  maximumWriteLength?<Operation extends string>(
    connection: BackendConnection<Attachment, string>,
    request: ConnectionMaximumWriteLengthRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ConnectionMaximumWriteLengthMeasurement<Attachment, Operation>>
}
export interface GattBackend<Attachment extends string> {
  discover(
    connection: BackendConnection<Attachment, string>,
    options: PublicOperationOptions
  ): Promise<GattDatabase<Attachment, string, string>>
  read<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Operation extends string
  >(
    path: CharacteristicPath<Attachment, Connection, Database, Service, Characteristic, 'current'>,
    request: ReadRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ReadResult<Attachment, Operation>>
  write<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Operation extends string
  >(
    path: CharacteristicPath<Attachment, Connection, Database, Service, Characteristic, 'current'>,
    request: WriteRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, WriteResult<Attachment, Operation>>
  readDescriptor<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Descriptor extends string,
    Operation extends string
  >(
    path: DescriptorPath<Attachment, Connection, Database, Service, Characteristic, Descriptor, 'current'>,
    request: ReadRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, ReadResult<Attachment, Operation>>
  writeDescriptor<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Descriptor extends string,
    Operation extends string
  >(
    path: DescriptorPath<Attachment, Connection, Database, Service, Characteristic, Descriptor, 'current'>,
    request: WriteRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, WriteResult<Attachment, Operation>>
  subscribe<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Operation extends string
  >(
    path: CharacteristicPath<Attachment, Connection, Database, Service, Characteristic, 'current'>,
    request: SubscribeRequest<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, BackendSubscription<Attachment, string, string, string, string>>
  unsubscribe<
    Connection extends string,
    Database extends string,
    Service extends string,
    Characteristic extends string,
    Operation extends string
  >(
    subscription: BackendSubscription<Attachment, Connection, Database, Service, Characteristic>,
    operation: OperationOptions<Attachment, Operation>
  ): BackendOperationDispatch<Attachment, OperationTerminalRecord<Attachment, string>>
}
export interface BackendSubscription<
  Attachment extends string,
  Connection extends string,
  Database extends string,
  Service extends string,
  Characteristic extends string
> {
  readonly subscriptionId: SubscriptionId<Attachment, string, string, string, string, string>
  readonly path: CharacteristicPath<Attachment, Connection, Database, Service, Characteristic, 'current'>
  readonly terminal: OperationTerminalRecord<Attachment, string>
  readonly notifications: BoundedAsyncStream<NotificationValue>
}
export interface BackendEventBase<Attachment extends string> {
  readonly attachment: AttachmentRecord<Attachment>
  readonly attachmentId: AttachmentId<Attachment>
  readonly ingressOrdinal: number
}
export interface BackendDatabaseChangedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'database-changed'
  readonly database: DatabasePath<Attachment, string, string>
}
/** A loss is scoped to the exact attachment, connection generation, and owner lease. */
export interface BackendConnectionLostEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'connection-lost'
  readonly connection: ConnectionPath<Attachment, string>
}
export interface BackendGenericEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'adapter-state' | 'backend-restarted' | 'diagnostic'
}
/** Normalized scan delivery, separate from a stream's bounded overflow accounting record. */
export interface BackendScanResultEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'scan-result'
  readonly observation: AdvertisementObservation<Attachment>
}
export interface BackendScanOverflowEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'scan-overflow'
  readonly scanSessionId: ScanSessionId<Attachment, string>
  readonly policy: import('./streams').OverflowPolicy
  readonly droppedItems: ResourceCount
  readonly droppedBytes: ResourceCount
  readonly replacedItems: ResourceCount
}
export type BackendDisconnectReason = 'local' | 'peer' | 'adapter' | 'backend-restart'
const backendDisconnectReasons: readonly BackendDisconnectReason[] = Object.freeze([
  'local',
  'peer',
  'adapter',
  'backend-restart'
])
const connectionStates: readonly ConnectionState[] = Object.freeze([
  'connecting',
  'connected',
  'disconnecting',
  'disconnected',
  'lost'
])
export interface BackendConnectionStateChangedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'connection-state-changed'
  readonly connection: ConnectionPath<Attachment, string>
  readonly previous: ConnectionState
  readonly current: ConnectionState
  readonly reason: BackendDisconnectReason | null
}
export interface BackendDisconnectedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'disconnected'
  readonly connection: ConnectionPath<Attachment, string>
  readonly reason: BackendDisconnectReason
}
export interface BackendCharacteristicValueChangedEvent<Attachment extends string>
  extends BackendEventBase<Attachment> {
  readonly kind: 'characteristic-value-changed'
  readonly path: CharacteristicPath<Attachment, string, string, string, string, 'current'>
  readonly value: NotificationValue
}
export interface BackendNotificationOverflowEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'notification-overflow'
  readonly subscriptionId: SubscriptionId<Attachment, string, string, string, string, string>
  readonly policy: import('./streams').OverflowPolicy
  readonly droppedItems: ResourceCount
  readonly droppedBytes: ResourceCount
  readonly replacedItems: ResourceCount
}
export interface BackendMtuChangedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'mtu-changed'
  readonly connection: ConnectionPath<Attachment, string>
  readonly mtu: number
  readonly maximumWriteLength: number
}
export interface BackendBondSecurityEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'bond-security-changed'
  readonly peerId: PeerId<Attachment>
  readonly bond: 'none' | 'bonding' | 'bonded' | 'failed' | 'unavailable'
  readonly security: 'unencrypted' | 'encrypted' | 'authenticated' | 'unavailable'
}
export interface BackendPhyChangedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'phy-changed'
  readonly connection: ConnectionPath<Attachment, string>
  readonly txPhy: '1m' | '2m' | 'coded' | 'unavailable'
  readonly rxPhy: '1m' | '2m' | 'coded' | 'unavailable'
}
export interface BackendPermissionStateChangedEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'permission-state-changed'
  readonly state: AdapterStateSnapshot<Attachment>
}
export interface BackendRestorationEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'restoration-received'
  readonly record: SerializableRecord
}
export interface BackendRestartingEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'backend-restarting'
  readonly reason: string
}
export interface BackendDiagnosticEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: 'diagnostic-warning'
  readonly code: string
  readonly message: string
  readonly detail: SerializableRecord
}
/** Open extension lane: namespaced event kinds retain typed serializable payloads without central-union edits. */
export interface BackendExtensionEvent<Attachment extends string> extends BackendEventBase<Attachment> {
  readonly kind: `extension:${string}`
  readonly payload: SerializableRecord
}
export type BackendEvent<Attachment extends string> =
  | BackendDatabaseChangedEvent<Attachment>
  | BackendConnectionLostEvent<Attachment>
  | BackendGenericEvent<Attachment>
  | BackendScanResultEvent<Attachment>
  | BackendScanOverflowEvent<Attachment>
  | BackendConnectionStateChangedEvent<Attachment>
  | BackendDisconnectedEvent<Attachment>
  | BackendCharacteristicValueChangedEvent<Attachment>
  | BackendNotificationOverflowEvent<Attachment>
  | BackendMtuChangedEvent<Attachment>
  | BackendBondSecurityEvent<Attachment>
  | BackendPhyChangedEvent<Attachment>
  | BackendPermissionStateChangedEvent<Attachment>
  | BackendRestorationEvent<Attachment>
  | BackendRestartingEvent<Attachment>
  | BackendDiagnosticEvent<Attachment>
  | BackendExtensionEvent<Attachment>
export function assertBackendEvent<Attachment extends string>(event: BackendEvent<Attachment>): void {
  if (!Number.isSafeInteger(event.ingressOrdinal) || event.ingressOrdinal < 0) {
    throw contractError('protocol.malformed', 'core', 'backend.assert-event.ingress-ordinal')
  }
  if (event.attachment.attachmentId !== event.attachmentId) {
    throw contractError('protocol.malformed', 'core', 'backend.assert-event.attachment-id')
  }
  if (
    event.kind === 'database-changed' &&
    (event.database.attachmentId !== event.attachmentId ||
      !attachmentRecordsEqual(event.database.attachment, event.attachment))
  ) {
    throw contractError('protocol.violation', 'core', 'backend.assert-event.database-attachment')
  }
  if (
    (event.kind === 'connection-lost' || event.kind === 'connection-state-changed' || event.kind === 'disconnected') &&
    (event.connection.attachmentId !== event.attachmentId ||
      !attachmentRecordsEqual(event.connection.attachment, event.attachment))
  ) {
    throw contractError('protocol.violation', 'core', 'backend.assert-event.connection-attachment')
  }
  if (
    event.kind === 'connection-state-changed' &&
    (!connectionStates.includes(event.previous) ||
      !connectionStates.includes(event.current) ||
      (event.reason !== null && !backendDisconnectReasons.includes(event.reason)) ||
      (event.current === 'disconnected' || event.current === 'lost') === (event.reason === null))
  ) {
    throw contractError('protocol.malformed', 'core', 'backend.assert-event.connection-transition-reason')
  }
  if (event.kind === 'disconnected' && !backendDisconnectReasons.includes(event.reason)) {
    throw contractError('protocol.malformed', 'core', 'backend.assert-event.disconnect-reason')
  }
}
export interface BleCentralBackend<Attachment extends string, Identity extends BackendIdentity<Attachment>> {
  readonly identity: Identity
  readonly adapter: AdapterBackend<Attachment>
  readonly scanner: ScannerBackend<Attachment>
  readonly connections: ConnectionBackend<Attachment>
  readonly gatt: GattBackend<Attachment>
  readonly security?: SecurityBackend
  readonly peers?: PeerDirectoryBackend<Attachment>
  readonly features: FeatureRegistry
  readonly traceDocument?: () => DiagnosticTraceDocument
  attach(request: BackendAttachmentRequest): Promise<BackendAttachment<Attachment, Identity>>
  events(): BoundedAsyncStream<BackendEvent<Attachment>>
  resourceCounters(): ResourceCounters
  destroy(): Promise<CleanupRecord>
}

interface AttachedBackendAuthentication<Attachment extends string, Identity extends BackendIdentity<Attachment>> {
  readonly backend: BleCentralBackend<Attachment, Identity>
  readonly attachment: AttachmentRecord<Attachment>
  readonly identity: BackendIdentityAuthenticationClaim<Attachment>
}

interface BackendIdentityAuthenticationClaim<Attachment extends string> {
  readonly registeredBackendId: string
  readonly registeredPlatformId: string
  readonly attachment: AttachmentRecord<Attachment>
  readonly versions: ApplicableVersionAxes
  readonly runtime: BackendRuntimeMetadata
}

const authenticatedAttachedBackends = new WeakMap<
  AttachedBackend<string, BackendIdentity<string>>,
  AttachedBackendAuthentication<string, BackendIdentity<string>>
>()

/** Opaque result of the one manager-neutral backend attachment handshake. */
export abstract class AttachedBackend<Attachment extends string, Identity extends BackendIdentity<Attachment>> {
  private readonly authenticatedReceiptMarker = true

  protected constructor() {
    if (!this.authenticatedReceiptMarker) {
      throw contractError('ownership.denied', 'core', 'backend.attach-receipt-construction')
    }
  }

  abstract readonly backend: BleCentralBackend<Attachment, Identity>
  abstract readonly attachment: BackendAttachment<Attachment, Identity>

  protected hasAuthenticatedReceiptMarker(): boolean {
    return this.authenticatedReceiptMarker
  }
}

class IssuedAttachedBackend<
  Attachment extends string,
  Identity extends BackendIdentity<Attachment>
> extends AttachedBackend<Attachment, Identity> {
  constructor(
    readonly backend: BleCentralBackend<Attachment, Identity>,
    readonly attachment: BackendAttachment<Attachment, Identity>
  ) {
    super()
    if (!this.hasAuthenticatedReceiptMarker()) {
      throw contractError('ownership.denied', 'core', 'backend.attach-receipt-issuance')
    }
    authenticatedAttachedBackends.set(this, {
      backend,
      attachment: snapshotAttachmentRecord(attachment.attachment),
      identity: snapshotBackendIdentityClaim(attachment.identity)
    })
    Object.freeze(this)
  }
}

/** Negotiates one backend attachment before logical manager admission. */
export async function attachBackend<Attachment extends string, Identity extends BackendIdentity<Attachment>>(
  backend: BleCentralBackend<Attachment, Identity>,
  coreCompatibility: BackendCompatibilityOffer
): Promise<AttachedBackend<Attachment, Identity>> {
  const attachment = await backend.attach({ coreCompatibility })
  assertAttachmentMatchesBackend(backend, attachment)
  assertCoreVersionsAccepted(attachment.identity.versions, coreCompatibility)
  return new IssuedAttachedBackend(backend, attachment)
}

/** Rejects mismatched backend/identity tuples before any manager can use the binding. */
export function assertAttachedBackend<Attachment extends string, Identity extends BackendIdentity<Attachment>>(
  attachedBackend: AttachedBackend<Attachment, Identity>
): void {
  const authentication = authenticatedAttachedBackends.get(attachedBackend)
  if (authentication === undefined) {
    throw contractError('ownership.denied', 'core', 'backend.assert-attached-backend.receipt')
  }
  if (
    authentication.backend !== attachedBackend.backend ||
    !completeAttachmentRecordsEqual(authentication.attachment, attachedBackend.attachment.attachment) ||
    !backendIdentityClaimsEqual(authentication.identity, attachedBackend.attachment.identity) ||
    !backendIdentityClaimsEqual(authentication.identity, attachedBackend.backend.identity)
  ) {
    throw contractError('protocol.violation', 'core', 'backend.assert-attached-backend.authentication')
  }
  assertAttachmentMatchesBackend(attachedBackend.backend, attachedBackend.attachment)
}

function assertAttachmentMatchesBackend<Attachment extends string, Identity extends BackendIdentity<Attachment>>(
  backend: BleCentralBackend<Attachment, Identity>,
  attachment: BackendAttachment<Attachment, Identity>
): void {
  if (
    !completeAttachmentRecordsEqual(attachment.attachment, attachment.identity.attachment) ||
    !completeAttachmentRecordsEqual(attachment.attachment, backend.identity.attachment)
  ) {
    throw contractError('protocol.violation', 'core', 'backend.assert-attached-backend')
  }
}

function snapshotBackendIdentityClaim<Attachment extends string>(
  identity: BackendIdentity<Attachment>
): BackendIdentityAuthenticationClaim<Attachment> {
  return Object.freeze({
    registeredBackendId: identity.registeredBackendId,
    registeredPlatformId: identity.registeredPlatformId,
    attachment: snapshotAttachmentRecord(identity.attachment),
    versions: snapshotApplicableVersionAxes(identity.versions),
    runtime: Object.freeze({
      hostKind: identity.runtime.hostKind,
      implementationVersion: identity.runtime.implementationVersion,
      diagnostics: snapshotSerializableRecord(identity.runtime.diagnostics).value
    })
  })
}

function backendIdentityClaimsEqual<Attachment extends string>(
  expected: BackendIdentityAuthenticationClaim<Attachment>,
  actual: BackendIdentity<Attachment>
): boolean {
  return (
    expected.registeredBackendId === actual.registeredBackendId &&
    expected.registeredPlatformId === actual.registeredPlatformId &&
    completeAttachmentRecordsEqual(expected.attachment, actual.attachment) &&
    applicableVersionAxesEqual(expected.versions, actual.versions) &&
    expected.runtime.hostKind === actual.runtime.hostKind &&
    expected.runtime.implementationVersion === actual.runtime.implementationVersion &&
    serializableRecordsEqual(expected.runtime.diagnostics, snapshotSerializableRecord(actual.runtime.diagnostics).value)
  )
}

function completeAttachmentRecordsEqual<Attachment extends string>(
  left: AttachmentRecord<Attachment>,
  right: AttachmentRecord<Attachment>
): boolean {
  return (
    attachmentRecordsEqual(left, right) &&
    left.adapter.displayName === right.adapter.displayName &&
    left.adapter.state.availability === right.adapter.state.availability &&
    left.adapter.state.authorization === right.adapter.state.authorization &&
    left.adapter.state.power === right.adapter.state.power &&
    left.adapter.state.backendGeneration === right.adapter.state.backendGeneration &&
    left.adapter.state.updatedAt === right.adapter.state.updatedAt &&
    left.adapter.state.safeReason === right.adapter.state.safeReason &&
    stringArraysEqual(left.adapter.limitations, right.adapter.limitations)
  )
}

function stringArraysEqual(left: readonly string[], right: readonly string[]): boolean {
  if (left.length !== right.length) {
    return false
  }
  for (let index = 0; index < left.length; index += 1) {
    if (left[index] !== right[index]) {
      return false
    }
  }
  return true
}

function snapshotAttachmentRecord<Attachment extends string>(
  attachment: AttachmentRecord<Attachment>
): AttachmentRecord<Attachment> {
  return Object.freeze({
    attachmentId: attachment.attachmentId,
    backendInstanceId: attachment.backendInstanceId,
    backendGeneration: attachment.backendGeneration,
    adapter: Object.freeze({
      adapterId: attachment.adapter.adapterId,
      displayName: attachment.adapter.displayName,
      state: Object.freeze({
        availability: attachment.adapter.state.availability,
        authorization: attachment.adapter.state.authorization,
        power: attachment.adapter.state.power,
        backendGeneration: attachment.adapter.state.backendGeneration,
        updatedAt: attachment.adapter.state.updatedAt,
        safeReason: attachment.adapter.state.safeReason
      }),
      adapterGeneration: attachment.adapter.adapterGeneration,
      limitations: Object.freeze([...attachment.adapter.limitations])
    })
  })
}
export interface ManagerConstructionBase<Attachment extends string, Identity extends BackendIdentity<Attachment>> {
  readonly attachedBackend: AttachedBackend<Attachment, Identity>
  readonly clientId: ClientId<Attachment, string>
  readonly managerId: ManagerId<Attachment, string>
  /** Present only when this provider owns a bound native restoration authority. */
  readonly restoration?: ManagerRestorationCapability<Attachment>
}
export interface BackendAttachmentRequest {
  readonly coreCompatibility: BackendCompatibilityOffer
}
export interface BackendAttachment<Attachment extends string, Identity extends BackendIdentity<Attachment>> {
  readonly attachment: AttachmentRecord<Attachment>
  readonly identity: Identity
}
export interface OwningManagerConstruction<Attachment extends string, Identity extends BackendIdentity<Attachment>>
  extends ManagerConstructionBase<Attachment, Identity> {
  readonly ownerMode: 'owning'
}
export interface BorrowingManagerConstruction<Attachment extends string, Identity extends BackendIdentity<Attachment>>
  extends ManagerConstructionBase<Attachment, Identity> {
  readonly ownerMode: 'borrowing'
}
export type ManagerConstruction<Attachment extends string, Identity extends BackendIdentity<Attachment>> =
  | OwningManagerConstruction<Attachment, Identity>
  | BorrowingManagerConstruction<Attachment, Identity>