docs(dap): correct the loader and adapter comments

Name the user-override materialization as the second mason-nvim-dap load
site, correct the upstream default_setup ipairs claim, and point the
validate-order notes in every client back at the canonical contract in
init.lua. delve: 38697 is the nvim-dap wiki's example port, not a delve
default. lldb: the lldb-dap rename landed in LLVM 18, not 15. python:
cover all raise sites and drop two boilerplate configuration comments.

Author: charliie-dev

lua/modules/configs/tool/dap/clients/codelldb.lua

@@ -4,7 +4,8 @@ return function()
 	local utils = require("modules.utils.dap")
 	local is_windows = require("core.global").is_windows
 
-	-- Self-validate at config time: launch AND attach both spawn the local binary, so
+	-- Self-validate at config time (validate FIRST — contract: tool/dap/init.lua
+	-- resolver spec): launch AND attach both spawn the local binary, so
 	-- unlike delve/python nothing is worth registering without it — error if missing.
 	local command =
 		require("modules.utils.tools").exepath_or_error("codelldb", "install it via Mason or your package manager")

lua/modules/configs/tool/dap/clients/delve.lua

@@ -15,8 +15,9 @@ return function()
 	---@param config table
 	local function delve_adapter(callback, config)
 		if config.request == "attach" and config.mode == "remote" then
-			-- Default when unset, but a malformed user port errors rather than silently
-			-- falling back to delve's default 38697.
+			-- Default when unset (38697 is the conventional example port from the
+			-- nvim-dap wiki, not a delve default), but a malformed user port
+			-- errors rather than silently falling back to it.
 			local port = 38697
 			if config.port ~= nil then
 				local n = tonumber(config.port)

lua/modules/configs/tool/dap/clients/lldb.lua

@@ -4,8 +4,10 @@ return function()
 	local utils = require("modules.utils.dap")
 
 	-- Opt-in preset (not in default dap_deps; codelldb covers C-family). Self-validate
-	-- so the resolver surfaces `lldb`. LLVM 15 renamed `lldb-vscode` -> `lldb-dap`;
-	-- probe the new name first, keep the old for distros still shipping it.
+	-- so the resolver surfaces `lldb` (validate FIRST — contract:
+	-- tool/dap/init.lua resolver spec). LLVM 18 renamed `lldb-vscode` ->
+	-- `lldb-dap`; probe the new name first, keep the old for distros still
+	-- shipping it.
 	local command = require("modules.utils.tools").exepath_or_error(
 		{ "lldb-dap", "lldb-vscode" },
 		"install it via your package manager (ships with LLVM/lldb)"

lua/modules/configs/tool/dap/clients/python.lua

@@ -52,7 +52,7 @@ return function()
 		import_probe_retries = 0
 		return command, args
 	end
-	-- One copy for both raise sites so the install guidance can't drift.
+	-- One copy for all raise sites so the install guidance can't drift.
 	local no_debugpy = "debugpy not found: no `debugpy-adapter` shim on $PATH or in Mason's bin dir,\n"
 		.. "and no python able to import debugpy; install debugpy via Mason (`:Mason`)\n"
 		.. "or your package manager"
@@ -159,11 +159,9 @@ return function()
 	end
 	dap.configurations.python = {
 		{
-			-- The first three options are required by nvim-dap
-			type = "python", -- the type here established the link to the adapter definition: `dap.adapters.python`
+			type = "python", -- links to the adapter definition: `dap.adapters.python`
 			request = "launch",
 			name = "Debug",
-			-- Options below are for debugpy, see https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings for supported options
 			console = "integratedTerminal",
 			program = utils.input_file_path(),
 			pythonPath = function()
@@ -176,11 +174,9 @@ return function()
 			end,
 		},
 		{
-			-- NOTE: This setting is for people using venv
 			type = "python",
 			request = "launch",
 			name = "Debug (using venv)",
-			-- Options below are for debugpy, see https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings for supported options
 			console = "integratedTerminal",
 			program = utils.input_file_path(),
 			pythonPath = function()

lua/modules/configs/tool/dap/init.lua

@@ -96,10 +96,11 @@ return function()
 	vim.fn.sign_define("DapLogPoint", { text = icons.dap.LogPoint, texthl = "DapLogPoint", linehl = "", numhl = "" })
 
 	-- Everything Mason-flavored loads LAZILY: a session where every adapter
-	-- self-validates from $PATH must not load mason.nvim / mason-nvim-dap on
-	-- the :Dap* tick. First use (the factory fallback or a phase-2
-	-- classification) goes through lazy.nvim's module loader; absence degrades
-	-- to client-config/$PATH resolution as before.
+	-- self-validates from $PATH — with no user overrides — must not load
+	-- mason.nvim / mason-nvim-dap on the :Dap* tick. First use (the factory
+	-- fallback, a phase-2 classification, or a user override's opts
+	-- materialization) goes through lazy.nvim's module loader; absence
+	-- degrades to client-config/$PATH resolution as before.
 	local mason_dap = nil
 	local function mason_dap_mod()
 		if mason_dap == nil then
@@ -160,15 +161,16 @@ return function()
 	end
 
 	---A handler to setup all clients defined under `tool/dap/clients/*.lua`.
-	---Only the factory branch touches mason-nvim-dap: a client-config'd adapter
-	---(every adapter in this repo) configures without loading Mason.
+	---The factory branch and a user override's opts materialization load
+	---mason-nvim-dap; a repo zero-arg client (every adapter in this repo)
+	---configures without loading Mason.
 	---@param dap_name string
 	local function mason_dap_handler(dap_name)
 		local custom_handler, broken_reason, _, user_won = load_client_config(dap_name)
 		-- No-fall-through contract, enforced by the ONE shared implementation
-		-- (tools.usable_or_raise, also used by mason_lsp_handler): a broken or
-		-- wrong-shaped config must never read as success — that would suppress
-		-- both the warning and the install fallback.
+		-- (tools.usable_or_raise): a broken or wrong-shaped config must never
+		-- read as success — that would suppress both the warning and the
+		-- install fallback.
 		custom_handler = tools.usable_or_raise(custom_handler, broken_reason, {
 			label = "client config",
 			expected = "a fun(opts)",
@@ -217,9 +219,10 @@ return function()
 				)
 			end
 			-- Partial mappings drift can hand us configurations without
-			-- filetypes (or vice versa); default_setup ipairs() both
-			-- unconditionally. Degrade to whatever half is present instead of
-			-- a raw ipairs(nil) raise.
+			-- filetypes: upstream's default_setup guards configurations
+			-- (`or {}`) but ipairs()es filetypes whenever configurations are
+			-- non-empty — that combination raises ipairs(nil). Normalize both
+			-- halves defensively.
 			if type(config.configurations) ~= "table" then
 				config.configurations = {}
 			end
@@ -345,8 +348,8 @@ return function()
 		-- install fallback — python resolves debugpy from a venv $PATH can't see.
 		-- The raise on a missing launch binary is the provisioning signal.
 		--
-		-- CANONICAL availability contract for dap/clients/*.lua (referenced by the
-		-- one-line notes in each client; keep the two patterns in sync here).
+		-- CANONICAL availability contract for dap/clients/*.lua (the raise-LAST
+		-- clients carry pointer notes back here; keep the two patterns in sync).
 		-- Shape enforcement itself lives in tools.usable_or_raise; a
 		-- metadata-declared contract ({ attach_capable, binaries }) was
 		-- considered and rejected — it would churn the fun(opts) user-override