@camstack/server 0.1.7 → 0.2.0

package/src/api/core/cap-providers.ts

@@ -41,9 +41,10 @@ import type {
   Integration,
   IIntegrationRegistry,
   IDeviceProvider,
+  IBrokerProvider,
   CapabilityMethodAuth,
 } from '@camstack/types'
-import { asJsonObject, asJsonArray, errMsg } from '@camstack/types'
+import { asJsonObject, asJsonArray, errMsg, EventCategory } from '@camstack/types'
 import type { CapabilityRegistry } from '@camstack/kernel'
 import { getCapUsageRegistry } from '@camstack/kernel'
 import type { ToastService, NotificationService } from '@camstack/core'
@@ -57,6 +58,7 @@ import type { AddonRegistryService } from '../../core/addon/addon-registry.servi
 import type { AddonPackageService } from '../../core/addon/addon-package.service'
 import type { NetworkQualityService } from '../../core/network/network-quality.service'
 import type { ConfigService } from '../../core/config/config.service'
+import { planDeleteTimeStamps } from '../../boot/integration-id-backfill'
 import { persistCollectionDisabled } from './collection-preference.js'
 import { BulkUpdateCoordinator } from './bulk-update-coordinator.js'
 import { FRAMEWORK_PACKAGE_ALLOWLIST } from '../../core/addon/addon-package.service.js'
@@ -66,7 +68,9 @@ const execFileAsync = promisify(execFile)
 // ── system ──────────────────────────────────────────────────────────
 
 function getRetention(registry: CapabilityRegistry | null) {
-  return registry?.getSingleton<IAnalysisDataPersistence>('analysis-data-persistence')?.retention ?? null
+  return (
+    registry?.getSingleton<IAnalysisDataPersistence>('analysis-data-persistence')?.retention ?? null
+  )
 }
 
 export function buildSystemProvider(
@@ -105,9 +109,7 @@ export function buildSystemProvider(
 
 // ── network-quality ─────────────────────────────────────────────────
 
-export function buildNetworkQualityProvider(
-  nq: NetworkQualityService,
-): INetworkQualityProvider {
+export function buildNetworkQualityProvider(nq: NetworkQualityService): INetworkQualityProvider {
   return {
     getDeviceStats: async (input) => nq.getDeviceStats(input.deviceId),
     getAllStats: async () => nq.getAllStats(),
@@ -116,6 +118,7 @@ export function buildNetworkQualityProvider(
         rttMs: input.rttMs,
         jitterMs: input.jitterMs,
         estimatedBandwidthKbps: input.estimatedBandwidthKbps,
+        packetLossPercent: input.packetLossPercent,
       })
     },
   }
@@ -138,7 +141,9 @@ export function buildToastProvider(
       if (!toastService) return () => {}
       const userId = ctx.user?.id ?? 'anonymous'
       const connectionId = randomUUID()
-      const unsubscribe = toastService.subscribe(connectionId, userId, (toast: Toast) => push(toast))
+      const unsubscribe = toastService.subscribe(connectionId, userId, (toast: Toast) =>
+        push(toast),
+      )
       return unsubscribe ?? (() => {})
     },
   }
@@ -181,14 +186,14 @@ export async function computeTopology(
 ): Promise<readonly TopologyNode[]> {
   const nodes = await agentRegistry.listNodes()
   const allAddons = addonRegistry?.listAddons() ?? []
-  const getInGroupAddonIds = (node: typeof nodes[number]): readonly string[] => {
+  const getInGroupAddonIds = (node: (typeof nodes)[number]): readonly string[] => {
     const subs = (node.subProcesses ?? []) as readonly SubProcessLite[]
     return subs.flatMap((p) => p.addonIds ?? [])
   }
   const addonCaps = new Map<string, readonly string[]>()
   for (const a of allAddons) {
     const id = a.manifest?.id ?? ''
-    const caps = a.declaration?.capabilities?.map(c => typeof c === 'string' ? c : c.name) ?? []
+    const caps = a.declaration?.capabilities?.map((c) => (typeof c === 'string' ? c : c.name)) ?? []
     addonCaps.set(id, caps)
   }
   const addonCategory = new Map<string, string>()
@@ -199,7 +204,8 @@ export async function computeTopology(
   }
   return nodes.map((node) => {
     const inGroupAddonIds = new Set(getInGroupAddonIds(node))
-    const agentAddonIds: readonly string[] = (node as { agentAddons?: readonly string[] }).agentAddons ?? []
+    const agentAddonIds: readonly string[] =
+      (node as { agentAddons?: readonly string[] }).agentAddons ?? []
     type NodeAddonEntry = { id: string; capabilities: readonly string[]; status: 'running' }
     const allNodeAddons: NodeAddonEntry[] = node.isHub
       ? allAddons.map((a) => {
@@ -212,31 +218,33 @@ export async function computeTopology(
           status: 'running' as const,
         }))
     const inProcessAddons = allNodeAddons.filter((a) => !inGroupAddonIds.has(a.id))
-    const isolatedProcesses = ((node.subProcesses ?? []) as readonly SubProcessLite[])
-    const mainProcessServices = inProcessAddons.map(a => ({
+    const isolatedProcesses = (node.subProcesses ?? []) as readonly SubProcessLite[]
+    const mainProcessServices = inProcessAddons.map((a) => ({
       addonId: a.id,
       capabilities: a.capabilities,
       status: a.status,
     }))
-    const mainProcess = node.isHub ? {
-      pid: process.pid,
-      name: 'hub (core)',
-      state: 'running' as const,
-      cpuPercent: node.status?.cpuPercent ?? 0,
-      memoryRss: process.memoryUsage().rss,
-      uptimeSeconds: Math.floor(process.uptime()),
-      services: mainProcessServices,
-    } : {
-      pid: 0,
-      name: `${node.info.id} (core)`,
-      state: 'running' as const,
-      cpuPercent: node.status?.cpuPercent ?? 0,
-      memoryRss: 0,
-      uptimeSeconds: Math.floor((Date.now() - node.connectedSince) / 1000),
-      services: mainProcessServices,
-    }
+    const mainProcess = node.isHub
+      ? {
+          pid: process.pid,
+          name: 'hub (core)',
+          state: 'running' as const,
+          cpuPercent: node.status?.cpuPercent ?? 0,
+          memoryRss: process.memoryUsage().rss,
+          uptimeSeconds: Math.floor(process.uptime()),
+          services: mainProcessServices,
+        }
+      : {
+          pid: 0,
+          name: `${node.info.id} (core)`,
+          state: 'running' as const,
+          cpuPercent: node.status?.cpuPercent ?? 0,
+          memoryRss: 0,
+          uptimeSeconds: Math.floor((Date.now() - node.connectedSince) / 1000),
+          services: mainProcessServices,
+        }
     const childProcesses = isolatedProcesses.map((p) => {
-      const memberIds = (p.addonIds && p.addonIds.length > 0) ? p.addonIds : [p.name]
+      const memberIds = p.addonIds && p.addonIds.length > 0 ? p.addonIds : [p.name]
       return {
         pid: p.pid,
         name: p.name,
@@ -255,16 +263,23 @@ export async function computeTopology(
     // Aggregate node-local addons by category. `allNodeAddons` already
     // contains the per-node addon roster (hub uses every installed
     // addon; agents use their assigned agentAddons subset).
-    const byCategory = new Map<string, {
-      category: string
-      total: number
-      healthy: number
-      addons: { id: string; status: string; cpuPercent: number; memoryRss: number }[]
-    }>()
+    const byCategory = new Map<
+      string,
+      {
+        category: string
+        total: number
+        healthy: number
+        addons: { id: string; status: string; cpuPercent: number; memoryRss: number }[]
+      }
+    >()
     const procByAddon = new Map<string, { cpuPercent: number; memoryRss: number; state: string }>()
     for (const p of (node.subProcesses ?? []) as readonly SubProcessLite[]) {
-      for (const addonId of (p.addonIds ?? [])) {
-        procByAddon.set(addonId, { cpuPercent: p.cpuPercent, memoryRss: p.memoryRss, state: p.state })
+      for (const addonId of p.addonIds ?? []) {
+        procByAddon.set(addonId, {
+          cpuPercent: p.cpuPercent,
+          memoryRss: p.memoryRss,
+          state: p.state,
+        })
       }
     }
     for (const a of allNodeAddons) {
@@ -301,10 +316,7 @@ export async function computeTopology(
       lastSeen: new Date().toISOString(),
       localIps: node.isHub ? getLocalIps() : (node.localIps ?? []),
       addons: allNodeAddons,
-      processes: [
-        mainProcess,
-        ...childProcesses,
-      ],
+      processes: [mainProcess, ...childProcesses],
       categories: categoriesProjection,
     }
   })
@@ -319,7 +331,11 @@ export async function computeTopology(
  * `addon-registry.service.ts`; consider hoisting if a third call site appears.
  */
 interface BrokerLike {
-  call<T = unknown>(action: string, params?: unknown, opts?: { nodeID?: string; timeout?: number }): Promise<T>
+  call<T = unknown>(
+    action: string,
+    params?: unknown,
+    opts?: { nodeID?: string; timeout?: number },
+  ): Promise<T>
 }
 
 export function buildNodesProvider(
@@ -335,9 +351,13 @@ export function buildNodesProvider(
       return { success: true }
     },
     undeployAddon: async (input) => {
-      await broker.call('$agent.undeploy', {
-        addonId: input.addonId,
-      }, { nodeID: input.nodeId, timeout: 30_000 })
+      await broker.call(
+        '$agent.undeploy',
+        {
+          addonId: input.addonId,
+        },
+        { nodeID: input.nodeId, timeout: 30_000 },
+      )
       return { success: true }
     },
     restartAddon: async (input) => {
@@ -350,31 +370,47 @@ export function buildNodesProvider(
         return { success: true }
       }
       const agentNodeId = input.nodeId.includes('/') ? input.nodeId.split('/')[0]! : input.nodeId
-      await broker.call('$agent.restart', {
-        addonId: input.addonId,
-      }, { nodeID: agentNodeId, timeout: 30_000 })
+      await broker.call(
+        '$agent.restart',
+        {
+          addonId: input.addonId,
+        },
+        { nodeID: agentNodeId, timeout: 30_000 },
+      )
       return { success: true }
     },
     restartProcess: async (input) => {
-      return await broker.call('$process.restart', {
-        name: input.processName,
-      }, { nodeID: input.nodeId, timeout: 30_000 }) as { success: boolean; reason?: string }
+      return (await broker.call(
+        '$process.restart',
+        {
+          name: input.processName,
+        },
+        { nodeID: input.nodeId, timeout: 30_000 },
+      )) as { success: boolean; reason?: string }
     },
     restartNode: async (input) => {
-      return await broker.call('$process.restartAll', {}, {
-        nodeID: input.nodeId,
-        timeout: 60_000,
-      }) as { restarted: readonly string[]; failed: readonly string[] }
+      return (await broker.call(
+        '$process.restartAll',
+        {},
+        {
+          nodeID: input.nodeId,
+          timeout: 60_000,
+        },
+      )) as { restarted: readonly string[]; failed: readonly string[] }
     },
     shutdownNode: async (input) => {
       if (input.nodeId === 'hub') {
         setTimeout(() => process.exit(0), 500)
         return { success: true }
       }
-      await broker.call('$agent.shutdown', {}, {
-        nodeID: input.nodeId,
-        timeout: 10_000,
-      })
+      await broker.call(
+        '$agent.shutdown',
+        {},
+        {
+          nodeID: input.nodeId,
+          timeout: 10_000,
+        },
+      )
       return { success: true }
     },
     renameNode: async (input) => {
@@ -387,9 +423,13 @@ export function buildNodesProvider(
           value: trimmed,
         })
       } else {
-        await broker.call('$agent.rename', {
-          name: trimmed,
-        }, { nodeID: input.nodeId, timeout: 10_000 })
+        await broker.call(
+          '$agent.rename',
+          {
+            name: trimmed,
+          },
+          { nodeID: input.nodeId, timeout: 10_000 },
+        )
         agentRegistry.updateAgentName(input.nodeId, trimmed)
       }
       return { nodeId: input.nodeId, name: trimmed }
@@ -436,17 +476,50 @@ export function buildNodesProvider(
       const remoteStatuses = await Promise.all(
         remoteNodes.map(async (node) => {
           try {
-            const status = await broker.call('$agent.status', {}, {
-              nodeID: node.info.id, timeout: 5_000,
-            }) as { addons?: readonly { id: string; status: string; version?: string; packageName?: string }[] }
-            return { nodeId: node.info.id, name: node.info.name, online: true, addons: status.addons ?? [] }
+            const status = (await broker.call(
+              '$agent.status',
+              {},
+              {
+                nodeID: node.info.id,
+                timeout: 5_000,
+              },
+            )) as {
+              addons?: readonly {
+                id: string
+                status: string
+                version?: string
+                packageName?: string
+              }[]
+            }
+            return {
+              nodeId: node.info.id,
+              name: node.info.name,
+              online: true,
+              addons: status.addons ?? [],
+            }
           } catch {
-            return { nodeId: node.info.id, name: node.info.name, online: false, addons: [] as readonly { id: string; status: string; version?: string; packageName?: string }[] }
+            return {
+              nodeId: node.info.id,
+              name: node.info.name,
+              online: false,
+              addons: [] as readonly {
+                id: string
+                status: string
+                version?: string
+                packageName?: string
+              }[],
+            }
           }
         }),
       )
 
-      type NodeDeployment = { nodeId: string; name: string; version: string; status: string; synced: boolean }
+      type NodeDeployment = {
+        nodeId: string
+        name: string
+        version: string
+        status: string
+        synced: boolean
+      }
       const result: Record<string, { hubVersion: string; nodes: NodeDeployment[] }> = {}
 
       for (const [addonId, hubAddon] of hubMap) {
@@ -486,9 +559,13 @@ export function buildNodesProvider(
       // also work — both are safe to run in parallel during Phase E.
       const reachedViaUds = moleculer.setChildLogLevelByNodeId(input.nodeId, input.level)
       if (!reachedViaUds) {
-        await broker.call('$node-mgmt.setLogLevel', {
-          level: input.level,
-        }, { nodeID: input.nodeId, timeout: 5_000 })
+        await broker.call(
+          '$node-mgmt.setLogLevel',
+          {
+            level: input.level,
+          },
+          { nodeID: input.nodeId, timeout: 5_000 },
+        )
       }
       return { success: true }
     },
@@ -515,9 +592,11 @@ function requireIntegrationRegistry(ar: AddonRegistryService): IIntegrationRegis
 }
 
 function isDeviceProvider(value: unknown): value is IDeviceProvider {
-  return value !== null
-    && typeof value === 'object'
-    && typeof Reflect.get(value, 'discoverDevices') === 'function'
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof Reflect.get(value, 'discoverDevices') === 'function'
+  )
 }
 
 function getDeviceProvider(ar: AddonRegistryService, addonId: string): IDeviceProvider | null {
@@ -525,17 +604,33 @@ function getDeviceProvider(ar: AddonRegistryService, addonId: string): IDevicePr
   return isDeviceProvider(provider) ? provider : null
 }
 
+/**
+ * Marker caps that flag an addon as a creatable integration type:
+ *   - `device-provider` — classic providers (Reolink/ONVIF/Frigate)
+ *     that expose `createDevice` + `discoverDevices` via their
+ *     device-provider cap.
+ *   - `device-adoption` — integration-style providers (Home Assistant
+ *     and future siblings) that materialise devices via a generic
+ *     adoption cap instead of a manual create-form. The picker treats
+ *     them the same way; the wizard's discovery step routes through the
+ *     specific cap based on the addon's declared surface.
+ *
+ * Exported so the integration-markers spec can assert the recognised set
+ * without booting the whole provider factory.
+ */
+export const INTEGRATION_CAP_MARKERS = new Set(['device-provider', 'device-adoption'])
+
 export function buildIntegrationsProvider(
   ar: AddonRegistryService,
   eb: EventBusService,
   loggingService: LoggingService,
+  capabilityRegistry: CapabilityRegistry | null,
 ): IIntegrationsProvider {
   const logger = loggingService.createLogger('integrations')
   const withProcessState = (i: Integration): IntegrationWithProcessState => ({
     ...i,
     processState:
-      ar.listAddons().find(a => a.manifest.id === i.addonId)?.process?.state
-      ?? 'unknown',
+      ar.listAddons().find((a) => a.manifest.id === i.addonId)?.process?.state ?? 'unknown',
   })
 
   return {
@@ -548,25 +643,27 @@ export function buildIntegrationsProvider(
       if (!integration) throw new Error(`Integration "${input.id}" not found`)
       return withProcessState(integration)
     },
-    getByAddonId: async (input) => requireIntegrationRegistry(ar).getIntegrationByAddonId(input.addonId),
+    getByAddonId: async (input) =>
+      requireIntegrationRegistry(ar).getIntegrationByAddonId(input.addonId),
     create: async (input) => {
       const { skipRestart, ...payload } = input
       const reg = requireIntegrationRegistry(ar)
 
-      logger.info('request', { tags: { addonId: input.addonId }, meta: { phase: 'create', name: input.name } })
+      logger.info('request', {
+        tags: { addonId: input.addonId },
+        meta: { phase: 'create', name: input.name },
+      })
 
       const addon = ar.listAddons().find((a) => a.manifest.id === input.addonId)
       const instanceMode =
         addon?.declaration?.instanceMode ?? addon?.manifest?.instanceMode ?? 'multiple'
       if (instanceMode === 'unique') {
-        const existing = (await reg.listIntegrations()).filter(
-          (i) => i.addonId === input.addonId,
-        )
+        const existing = (await reg.listIntegrations()).filter((i) => i.addonId === input.addonId)
         if (existing.length > 0) {
-          logger.warn(
-            'rejected duplicate unique',
-            { tags: { addonId: input.addonId, integrationId: existing[0]!.id }, meta: { phase: 'create' } },
-          )
+          logger.warn('rejected duplicate unique', {
+            tags: { addonId: input.addonId, integrationId: existing[0]!.id },
+            meta: { phase: 'create' },
+          })
           throw new Error(
             `Addon "${input.addonId}" is unique-instance and already has an integration (${existing[0]!.id})`,
           )
@@ -574,15 +671,26 @@ export function buildIntegrationsProvider(
       }
 
       const integration = await reg.createIntegration(payload)
-      logger.info('persisted', { tags: { integrationId: integration.id, addonId: integration.addonId }, meta: { phase: 'create' } })
+      logger.info('persisted', {
+        tags: { integrationId: integration.id, addonId: integration.addonId },
+        meta: { phase: 'create' },
+      })
 
       const hasSettings = input.settings != null && Object.keys(input.settings).length > 0
       if (!skipRestart && hasSettings) {
-        logger.info('settings present — restarting addon', { tags: { addonId: input.addonId }, meta: { phase: 'create' } })
+        logger.info('settings present — restarting addon', {
+          tags: { addonId: input.addonId },
+          meta: { phase: 'create' },
+        })
         await ar.restartAddon(input.addonId)
-        logger.info('addon restart complete', { tags: { addonId: input.addonId }, meta: { phase: 'create' } })
+        logger.info('addon restart complete', {
+          tags: { addonId: input.addonId },
+          meta: { phase: 'create' },
+        })
       } else {
-        logger.info('skipping restart (no settings or skipRestart=true)', { meta: { phase: 'create' } })
+        logger.info('skipping restart (no settings or skipRestart=true)', {
+          meta: { phase: 'create' },
+        })
       }
       return integration
     },
@@ -597,22 +705,21 @@ export function buildIntegrationsProvider(
       const changedFields = Object.keys(updates).filter(
         (k) => (updates as Record<string, unknown>)[k] !== undefined,
       )
-      logger.info(
-        'request',
-        { tags: { integrationId: input.id, addonId: previous.addonId }, meta: { phase: 'update', fields: changedFields } },
-      )
+      logger.info('request', {
+        tags: { integrationId: input.id, addonId: previous.addonId },
+        meta: { phase: 'update', fields: changedFields },
+      })
 
       const result = await reg.updateIntegration(id, updates)
       if (!result) throw new Error(`Integration "${id}" not found`)
 
-      const enabledChanged =
-        input.enabled !== undefined && input.enabled !== previous.enabled
+      const enabledChanged = input.enabled !== undefined && input.enabled !== previous.enabled
       if (enabledChanged) {
         const category = input.enabled ? 'integration.enabled' : 'integration.disabled'
-        logger.info(
-          'enabled state changed',
-          { tags: { integrationId: result.id, addonId: result.addonId }, meta: { phase: 'update', enabled: input.enabled } },
-        )
+        logger.info('enabled state changed', {
+          tags: { integrationId: result.id, addonId: result.addonId },
+          meta: { phase: 'update', enabled: input.enabled },
+        })
         eb.emit({
           id: `integration-${category}-${Date.now()}`,
           timestamp: new Date(),
@@ -626,17 +733,23 @@ export function buildIntegrationsProvider(
       }
 
       if (input.name !== undefined && input.name !== previous.name) {
-        logger.info(
-          'renamed',
-          { tags: { integrationId: result.id }, meta: { phase: 'update', previousName: previous.name, newName: input.name } },
-        )
+        logger.info('renamed', {
+          tags: { integrationId: result.id },
+          meta: { phase: 'update', previousName: previous.name, newName: input.name },
+        })
       }
 
       const infoChanged = input.info !== undefined
       if (infoChanged) {
-        logger.info('info changed — restarting addon', { tags: { addonId: result.addonId }, meta: { phase: 'update' } })
+        logger.info('info changed — restarting addon', {
+          tags: { addonId: result.addonId },
+          meta: { phase: 'update' },
+        })
         await ar.restartAddon(result.addonId)
-        logger.info('addon restart complete', { tags: { addonId: result.addonId }, meta: { phase: 'update' } })
+        logger.info('addon restart complete', {
+          tags: { addonId: result.addonId },
+          meta: { phase: 'update' },
+        })
       } else {
         logger.info('no restart needed (only enabled/name changed)', { meta: { phase: 'update' } })
       }
@@ -651,23 +764,107 @@ export function buildIntegrationsProvider(
         logger.warn('not found', { tags: { integrationId: input.id }, meta: { phase: 'delete' } })
         throw new Error(`Integration "${input.id}" not found`)
       }
-      logger.info(
-        'removing',
-        { tags: { integrationId: input.id, addonId: integration.addonId }, meta: { phase: 'delete', name: integration.name } },
-      )
+      logger.info('removing', {
+        tags: { integrationId: input.id, addonId: integration.addonId },
+        meta: { phase: 'delete', name: integration.name },
+      })
+
+      // Cascade-delete every live device whose integrationId matches.
+      // Best-effort: a device-removal hiccup must not abort the integration
+      // delete — log a warning and continue so the record + event always fire.
+      const dm =
+        capabilityRegistry?.getSingleton<{
+          removeByIntegration?: (input: { integrationId: string }) => Promise<{ removed: number }>
+          listAll?: (input: Record<string, never>) => Promise<
+            readonly {
+              id: number
+              addonId: string
+              parentDeviceId: number | null
+              integrationId?: string
+            }[]
+          >
+          setIntegrationId?: (input: { deviceId: number; integrationId: string }) => Promise<void>
+        }>('device-manager') ?? null
+
+      // Claim legacy un-tagged devices BEFORE the cascade. Devices created
+      // before stamping (or whose provider never stamps, e.g. `provider-rtsp`)
+      // carry no integrationId, so `removeByIntegration` (which matches on
+      // integrationId) would leave them orphaned forever once their integration
+      // is gone. While the integration record still exists, stamp the
+      // unambiguous ones (addons hosting exactly one integration) so the cascade
+      // below removes them too. Best-effort: never abort the delete.
+      if (dm?.listAll && dm?.setIntegrationId) {
+        try {
+          const [integrations, devices] = await Promise.all([
+            reg.listIntegrations(),
+            dm.listAll({}),
+          ])
+          const stamps = planDeleteTimeStamps(
+            input.id,
+            integrations.map((i) => ({ id: i.id, addonId: i.addonId })),
+            devices.map((d) => ({
+              id: d.id,
+              addonId: d.addonId,
+              parentDeviceId: d.parentDeviceId,
+              ...(d.integrationId !== undefined ? { integrationId: d.integrationId } : {}),
+            })),
+          )
+          for (const stamp of stamps) {
+            await dm.setIntegrationId({
+              deviceId: stamp.deviceId,
+              integrationId: stamp.integrationId,
+            })
+          }
+          if (stamps.length > 0) {
+            logger.info('claimed legacy un-tagged devices for cascade', {
+              tags: { integrationId: input.id, addonId: integration.addonId },
+              meta: { phase: 'delete', claimed: stamps.length },
+            })
+          }
+        } catch (err) {
+          logger.warn('legacy device claim failed (best-effort — continuing)', {
+            tags: { integrationId: input.id },
+            meta: { phase: 'delete', error: errMsg(err) },
+          })
+        }
+      }
+
+      if (dm?.removeByIntegration) {
+        try {
+          const result = await dm.removeByIntegration({ integrationId: input.id })
+          logger.info('cascade-removed devices', {
+            tags: { integrationId: input.id },
+            meta: { phase: 'delete', removed: result.removed },
+          })
+        } catch (err) {
+          logger.warn('device cascade-remove failed (best-effort — continuing)', {
+            tags: { integrationId: input.id },
+            meta: { phase: 'delete', error: errMsg(err) },
+          })
+        }
+      } else {
+        logger.warn('device-manager not available — skipping cascade device removal', {
+          tags: { integrationId: input.id },
+          meta: { phase: 'delete' },
+        })
+      }
+
       await reg.deleteIntegration(input.id)
 
       eb.emit({
         id: `integration-deleted-${Date.now()}`,
         timestamp: new Date(),
         source: { type: 'integration', id: input.id },
-        category: 'integration.deleted',
+        category: EventCategory.IntegrationDeleted,
         data: {
           integrationId: input.id,
           addonId: integration.addonId,
         },
       })
-      logger.info('completed (no restart)', { tags: { integrationId: input.id }, meta: { phase: 'delete' } })
+      logger.info('completed (no restart)', {
+        tags: { integrationId: input.id },
+        meta: { phase: 'delete' },
+      })
 
       return { success: true, deletedId: input.id }
     },
@@ -681,19 +878,28 @@ export function buildIntegrationsProvider(
       const reg = requireIntegrationRegistry(ar)
       const integration = await reg.getIntegration(input.id)
       if (!integration) {
-        logger.warn('not found', { tags: { integrationId: input.id }, meta: { phase: 'setSettings' } })
+        logger.warn('not found', {
+          tags: { integrationId: input.id },
+          meta: { phase: 'setSettings' },
+        })
         throw new Error(`Integration "${input.id}" not found`)
       }
       const settingsKeys = Object.keys(input.settings)
-      logger.info(
-        'request',
-        { tags: { integrationId: input.id, addonId: integration.addonId }, meta: { phase: 'setSettings', keys: settingsKeys } },
-      )
+      logger.info('request', {
+        tags: { integrationId: input.id, addonId: integration.addonId },
+        meta: { phase: 'setSettings', keys: settingsKeys },
+      })
       await reg.setIntegrationSettings(input.id, input.settings)
 
-      logger.info('persisted — restarting addon', { tags: { addonId: integration.addonId }, meta: { phase: 'setSettings' } })
+      logger.info('persisted — restarting addon', {
+        tags: { addonId: integration.addonId },
+        meta: { phase: 'setSettings' },
+      })
       await ar.restartAddon(integration.addonId)
-      logger.info('addon restart complete', { tags: { addonId: integration.addonId }, meta: { phase: 'setSettings' } })
+      logger.info('addon restart complete', {
+        tags: { addonId: integration.addonId },
+        meta: { phase: 'setSettings' },
+      })
       return { success: true }
     },
     getAvailableTypes: async () => {
@@ -704,22 +910,52 @@ export function buildIntegrationsProvider(
       // integration against an addon that didn't load produces an orphaned
       // row that `createFilteredRegistry` then filters out — silent data
       // loss from the operator's POV. Filter at the source instead.
-      const providerAddons = addons.filter(a =>
-        a.process?.state !== 'failed' &&
-        a.manifest.capabilities?.some(c =>
-          typeof c === 'string' ? c === 'device-provider' : c.name === 'device-provider',
-        ),
+      //
+      // Markers that flag an addon as a creatable integration type live
+      // in the module-level `INTEGRATION_CAP_MARKERS` set (exported so the
+      // integration-markers spec can assert the recognised caps).
+      const providerAddons = addons.filter(
+        (a) =>
+          a.process?.state !== 'failed' &&
+          a.manifest.capabilities?.some((c) => {
+            const name = typeof c === 'string' ? c : c.name
+            return typeof name === 'string' && INTEGRATION_CAP_MARKERS.has(name)
+          }),
       )
       const integrations = await reg.listIntegrations()
-      return providerAddons.map(addon => {
+      return providerAddons.map((addon) => {
         const m = addon.manifest
         const d = addon.declaration
         const icon = d?.icon ?? m.icon
         const color = d?.color ?? m.color ?? '#78716c'
         const instanceMode = d?.instanceMode ?? m.instanceMode ?? 'multiple'
-        const existing = integrations.filter(i => i.addonId === m.id)
+        const existing = integrations.filter((i) => i.addonId === m.id)
         const provider = getDeviceProvider(ar, m.id)
         const discoveryMode = provider?.discoveryMode ?? 'manual'
+
+        // Branch by CAP, not by addon name. Surface which integration-marker
+        // cap the addon declared so the wizard routes `device-adoption`
+        // (Approach A: pick/create a broker, store `{ brokerId }`) vs the
+        // legacy `device-provider` config → discovery flow. A `device-adoption`
+        // marker wins when both are present (an integration-style addon may
+        // also expose a `device-provider` shim); the broker step is the
+        // intended entry point for it.
+        const capNames = (m.capabilities ?? []).map((c) => (typeof c === 'string' ? c : c.name))
+        const kind: 'device-adoption' | 'device-provider' = capNames.includes('device-adoption')
+          ? 'device-adoption'
+          : 'device-provider'
+
+        // For device-adoption addons, the broker kind to create/link comes
+        // from the addon manifest (`brokerKind`). Null for device-provider
+        // addons, which carry no broker.
+        const brokerKind =
+          kind === 'device-adoption' ? (d?.brokerKind ?? m.brokerKind ?? null) : null
+
+        const supportsLocationImport =
+          kind === 'device-adoption'
+            ? (d?.supportsLocationImport ?? m.supportsLocationImport ?? false)
+            : false
+
         return {
           addonId: m.id,
           name: m.name ?? m.id,
@@ -728,7 +964,10 @@ export function buildIntegrationsProvider(
           color,
           instanceMode,
           discoveryMode,
-          existingInstances: existing.map(i => ({
+          kind,
+          brokerKind,
+          supportsLocationImport,
+          existingInstances: existing.map((i) => ({
             id: i.id,
             name: i.name,
           })),
@@ -737,14 +976,55 @@ export function buildIntegrationsProvider(
       })
     },
     testConnection: async (input) => {
-      const url = String(
-        input.settings['main_stream_url'] ?? input.settings['url'] ?? '',
-      ).trim()
+      // Broker-backed integrations (Approach A) carry their connection
+      // identity as a `brokerId` in settings — testing is a broker
+      // concern now, so delegate to the addon's `broker` cap. The broker
+      // already owns the real semantic check (HA opens a temporary WS
+      // handshake; MQTT pings the bridge). We translate the broker's
+      // discriminated result (`{ok:true,latencyMs}|{ok:false,error}`) into
+      // the integrations `{success, error?}` output shape. Falls back to
+      // the default RTSP/ffprobe path below for legacy device-provider
+      // addons (Reolink/Frigate/ONVIF) that probe a stream URL.
+      const registry = ar.getCapabilityRegistry()
+      const brokerId = input.settings['brokerId']
+      if (typeof brokerId === 'string' && brokerId.length > 0) {
+        const brokerProvider = registry.getProviderByAddonId<IBrokerProvider>(
+          'broker',
+          input.addonId,
+        )
+        if (!brokerProvider) {
+          return {
+            success: false,
+            error: `Broker provider for addon '${input.addonId}' is not available`,
+          }
+        }
+        try {
+          const result = await brokerProvider.testConnection({ id: brokerId })
+          return result.ok ? { success: true } : { success: false, error: result.error }
+        } catch (err) {
+          return { success: false, error: errMsg(err) }
+        }
+      }
+
+      // Default — RTSP/Frigate/ONVIF legacy path: probe the stream URL.
+      const url = String(input.settings['main_stream_url'] ?? input.settings['url'] ?? '').trim()
       if (!url) return { success: false, error: 'No stream URL provided' }
       try {
         const { stdout } = await execFileAsync(
           'ffprobe',
-          ['-v', 'error', '-rtsp_transport', 'tcp', '-timeout', '3000000', '-show_entries', 'stream=codec_name,width,height', '-of', 'json', url],
+          [
+            '-v',
+            'error',
+            '-rtsp_transport',
+            'tcp',
+            '-timeout',
+            '3000000',
+            '-show_entries',
+            'stream=codec_name,width,height',
+            '-of',
+            'json',
+            url,
+          ],
           { timeout: 5000 },
         )
         const parsed = asJsonObject(JSON.parse(stdout))
@@ -839,7 +1119,9 @@ export function buildAddonsProvider(
 
   const bulkCoordinator = new BulkUpdateCoordinator({
     eventBus: bulkEventBus,
-    updateAddon: async (i) => { await ps.updatePackage(i.name, i.version) },
+    updateAddon: async (i) => {
+      await ps.updatePackage(i.name, i.version)
+    },
     updateFrameworkPackage: async (i) => {
       await ps.updateFrameworkPackage({
         packageName: i.packageName,
@@ -858,7 +1140,10 @@ export function buildAddonsProvider(
   return {
     list: async () => {
       const rollbackable = ps.getRollbackablePackages()
-      const healthByPackage = new Map<string, ReturnType<typeof ar.getAddonHealthSnapshot>[number]>()
+      const healthByPackage = new Map<
+        string,
+        ReturnType<typeof ar.getAddonHealthSnapshot>[number]
+      >()
       for (const h of ar.getAddonHealthSnapshot()) {
         healthByPackage.set(h.packageName, h)
       }
@@ -868,11 +1153,12 @@ export function buildAddonsProvider(
         health: healthByPackage.get(item.manifest.packageName) ?? null,
       }))
     },
-    getLogs: async (input) => ls.query({
-      tags: { addonId: input.addonId },
-      limit: input.limit,
-      level: input.level,
-    }),
+    getLogs: async (input) =>
+      ls.query({
+        tags: { addonId: input.addonId },
+        limit: input.limit,
+        level: input.level,
+      }),
     listPackages: async () => ps.listInstalled(),
     installPackage: async (input) => ps.installAndLoad(input.packageName, input.version),
     installFromWorkspace: async (input) => ps.installFromWorkspaceAndLoad(input.packageName),
@@ -890,10 +1176,11 @@ export function buildAddonsProvider(
     },
     listUpdates: async (input) => {
       const nodeId = input.nodeId
-      const updates = nodeId === undefined || isHubNode(nodeId)
-        ? await ps.checkUpdates()
-        : await ps.checkUpdatesForInstalled(await fetchAgentInstalledPackages(broker, nodeId))
-      return updates.map(u => ({ ...u, isSystem: frameworkAllowSet.has(u.name) }))
+      const updates =
+        nodeId === undefined || isHubNode(nodeId)
+          ? await ps.checkUpdates()
+          : await ps.checkUpdatesForInstalled(await fetchAgentInstalledPackages(broker, nodeId))
+      return updates.map((u) => ({ ...u, isSystem: frameworkAllowSet.has(u.name) }))
     },
     updatePackage: async (input) => {
       const nodeId = input.nodeId
@@ -903,7 +1190,11 @@ export function buildAddonsProvider(
       // Agent target: the hub packs the resolved version and ships the
       // tarball over `$agent.deploy` — the agent has no npm runtime.
       const packed = await ps.packPackage(input.name, input.version)
-      await broker.call('$agent.deploy', { addonId: input.name, bundle: packed.buffer }, { nodeID: nodeId, timeout: 120_000 })
+      await broker.call(
+        '$agent.deploy',
+        { addonId: input.name, bundle: packed.buffer },
+        { nodeID: nodeId, timeout: 120_000 },
+      )
       await broker.call('$agent.reload', {}, { nodeID: nodeId, timeout: 120_000 })
       return { success: true, name: input.name, version: packed.version, nodeId }
     },
@@ -929,14 +1220,12 @@ export function buildAddonsProvider(
       const caps = registry.listCapabilities()
       const found = caps.find((c) => c.name === input.capName)
       if (!found) return []
-      const mode = found.mode === 'collection' ? 'collection' as const : 'singleton' as const
+      const mode = found.mode === 'collection' ? ('collection' as const) : ('singleton' as const)
       const disabled = new Set(found.disabledProviders)
       return found.providers.map((addonId) => ({
         addonId,
         mode,
-        isActive: mode === 'collection'
-          ? !disabled.has(addonId)
-          : found.activeProvider === addonId,
+        isActive: mode === 'collection' ? !disabled.has(addonId) : found.activeProvider === addonId,
       }))
     },
     setCapabilityProviderEnabled: async (input) => {
@@ -970,23 +1259,20 @@ export function buildAddonsProvider(
       // Reuses the same `capabilities.collection.<cap>` key/format the
       // `capabilities` core router writes — via the shared canonical writer.
       const updated = registry.listCapabilities().find((c) => c.name === input.capName)
-      persistCollectionDisabled(
-        configService,
-        input.capName,
-        updated?.disabledProviders ?? [],
-      )
+      persistCollectionDisabled(configService, input.capName, updated?.disabledProviders ?? [])
       return { success: true as const }
     },
-    updateFrameworkPackage: async (input) => ps.updateFrameworkPackage({
-      packageName: input.packageName,
-      ...(input.version !== undefined ? { version: input.version } : {}),
-      ...(ctx.user?.username !== undefined
-        ? { requestedBy: ctx.user.username }
-        : ctx.user?.id !== undefined
-          ? { requestedBy: ctx.user.id }
-          : {}),
-      ...(input.deferRestart !== undefined ? { deferRestart: input.deferRestart } : {}),
-    }),
+    updateFrameworkPackage: async (input) =>
+      ps.updateFrameworkPackage({
+        packageName: input.packageName,
+        ...(input.version !== undefined ? { version: input.version } : {}),
+        ...(ctx.user?.username !== undefined
+          ? { requestedBy: ctx.user.username }
+          : ctx.user?.id !== undefined
+            ? { requestedBy: ctx.user.id }
+            : {}),
+        ...(input.deferRestart !== undefined ? { deferRestart: input.deferRestart } : {}),
+      }),
     getVersions: async (input) => ps.getPackageVersions(input.name),
     restartAddon: async (input) => ar.restartAddon(input.addonId),
     retryLoad: async (input) => {
@@ -994,7 +1280,8 @@ export function buildAddonsProvider(
       return { success: true as const }
     },
     getAutoUpdateSettings: async () => ps.getAutoUpdateSettings(),
-    setAutoUpdateSettings: async (input) => ps.setAutoUpdateSettings(input.channel, input.intervalSeconds),
+    setAutoUpdateSettings: async (input) =>
+      ps.setAutoUpdateSettings(input.channel, input.intervalSeconds),
     getAddonAutoUpdate: async (input) => ps.getAddonAutoUpdate(input.addonId),
     setAddonAutoUpdate: async (input) => ps.setAddonAutoUpdate(input.addonId, input.channel),
     applyAutoUpdateToAll: async (input) => {
@@ -1025,11 +1312,17 @@ export function buildAddonsProvider(
     onAddonLogs: (input, push) => {
       const unsubscribe = ls.subscribe(
         { tags: { addonId: input.addonId }, level: input.level },
-        (entry: { timestamp: Date | string | number; level: string; message: string; scope?: string }) => {
+        (entry: {
+          timestamp: Date | string | number
+          level: string
+          message: string
+          scope?: string
+        }) => {
           push({
-            timestamp: entry.timestamp instanceof Date
-              ? entry.timestamp.toISOString()
-              : String(entry.timestamp),
+            timestamp:
+              entry.timestamp instanceof Date
+                ? entry.timestamp.toISOString()
+                : String(entry.timestamp),
             level: entry.level,
             message: entry.message,
             scope: entry.scope,