weir-harness 1.2.2 → 2.0.0

package/src/lease-broker/state.js

@@ -0,0 +1,425 @@
+// In-memory arbitration kernel behind `weir-editlockd`.
+//
+// Pure state machine: no IO, no timers, no real clock (the clock is injected),
+// no DSH/cordis/@deepseek-ai imports. Everything the kernel knows lives in two
+// maps and is thrown away when the process dies — that is the whole point of
+// the design (design D6): `kill` equals "every lease expired at once", and no
+// question about who owns what survives the process.
+//
+// Two states only (design D3): a path is `held` by exactly one connection, or
+// it is free. A transfer request is a mailbox entry with a bounded window, not
+// a third ownership state.
+//
+// Multiplicity rules that are easy to get wrong and are therefore stated once
+// here and enforced in one place:
+//
+// - Identity is `owner.id` (the client's lineage). `session` and `label` are
+//   display/delivery hints and may change; an acquisition from the SAME
+//   `owner.id` on the SAME connection is the same owner, so it adopts and
+//   refreshes instead of conflicting. The same `owner.id` through a DIFFERENT
+//   connection is a different owner for arbitration purposes (spec: "Same
+//   owner identifier from another connection").
+// - Validity is `max(expiresAt, holdUntil ?? 0)`. Once `now() >=` that instant
+//   the path is free for anyone, without negotiation and without notification.
+// - `release` judges identity only (a lapsed row still belongs to its owner, so
+//   releasing it is `released`, keeping the call idempotent), while `hold`
+//   additionally requires the row to still be valid — you cannot extend
+//   ownership that already lapsed, you must acquire again first.
+
+/**
+ * @typedef {{ id: string, session: string, label: string }} Owner
+ * @typedef {{ path: string, connectionId: string, owner: Owner, scope: string, acquiredAt: number, expiresAt: number, holdUntil: number | null }} Lease
+ * @typedef {{ path: string, holder: Owner, expiresAt: number, holdUntil: number | null }} Conflict
+ * @typedef {{ path: string, owner: Owner, scope: string, acquiredAt: number, expiresAt: number, holdUntil: number | null }} LeaseView
+ * @typedef {{ requestId: string, path: string, from: Owner, connectionId: string, holderConnectionId: string, holderId: string, expiresAt: number }} PendingRequest
+ * @typedef {{ event: 'request', requestId: string, path: string, from: Owner, expiresAt: number }} RequestEvent
+ * @typedef {{ event: 'settled', requestId: string, path: string, state: 'transferred' | 'declined' | 'expired' }} SettledEvent
+ * @typedef {{ connectionId: string, owner: Owner, scope: string, paths: string[], ttlMs?: number }} AcquireInput
+ * @typedef {{ connectionId: string, owner: Owner, paths: string[] }} ReleaseInput
+ * @typedef {{ connectionId: string, owner: Owner, paths: string[], minutes: number }} HoldInput
+ * @typedef {{ connectionId: string, from: Owner, path: string }} RequestInput
+ * @typedef {{ connectionId: string, owner: Owner, requestId: string, decision: 'release' | 'keep' }} ReplyInput
+ * @typedef {{ scope?: string, session?: string, path?: string }} StatusFilter
+ * @typedef {{ ok: true, granted: LeaseView[] } | { ok: false, code: 'held', conflicts: Conflict[] }} AcquireResult
+ * @typedef {{ ok: true, released: string[], notOwned: string[] }} ReleaseResult
+ * @typedef {{ ok: true, held: { path: string, expiresAt: number, holdUntil: number | null }[] } | { ok: false, code: 'limit', maxMinutes: number } | { ok: false, code: 'not-owned', paths: string[] } | { ok: false, code: 'bad-request' }} HoldResult
+ * @typedef {{ ok: true, leases: LeaseView[] }} StatusResult
+ * @typedef {{ ok: true, state: 'pending', requestId: string, holder: Owner, expiresAt: number } | { ok: false, code: 'free' | 'self' }} RequestResult
+ * @typedef {{ ok: true, state: 'transferred' | 'declined' } | { ok: false, code: 'expired' | 'stale' | 'not-holder' }} ReplyResult
+ */
+
+/**
+ * @param {Lease} lease
+ * @returns {LeaseView}
+ */
+function view(lease) {
+  return {
+    path: lease.path,
+    owner: { ...lease.owner },
+    scope: lease.scope,
+    acquiredAt: lease.acquiredAt,
+    expiresAt: lease.expiresAt,
+    holdUntil: lease.holdUntil,
+  }
+}
+
+/**
+ * Create one arbitration kernel.
+ *
+ * @param {object} [options]
+ * @param {() => number} [options.now] injected clock (epoch ms)
+ * @param {number} [options.ttlMs] default lease time-to-live
+ * @param {number} [options.requestWindowMs] bounded negotiation window
+ * @param {number} [options.holdMaxMinutes] retention bound in minutes
+ * @param {(connectionId: string, event: RequestEvent | SettledEvent) => void} [options.onEvent] event sink; a missing connection or a throwing sink never affects arbitration
+ */
+export function createBroker({
+  now = Date.now,
+  ttlMs = 120_000,
+  requestWindowMs = 120_000,
+  holdMaxMinutes = 60,
+  onEvent = () => {},
+} = {}) {
+  /** @type {Map<string, Lease>} */
+  const leases = new Map()
+  /** @type {Map<string, PendingRequest>} */
+  const pending = new Map()
+  /** @type {Map<string, string>} requester+path → requestId, at most one per pair */
+  const pendingKeys = new Map()
+  /** @type {Set<string>} */
+  const connections = new Set()
+  let requestSeq = 0
+
+  /** @param {Lease} lease */
+  function validUntil(lease) {
+    return Math.max(lease.expiresAt, lease.holdUntil ?? 0)
+  }
+
+  /** @param {Lease} lease */
+  function isValid(lease) {
+    return now() < validUntil(lease)
+  }
+
+  /** @param {string} path @param {string} fromId */
+  function requestKey(path, fromId) {
+    return `${fromId}\u0000${path}`
+  }
+
+  /** Drop a mailbox entry and its (requester, path) index slot. @param {string} requestId */
+  function dropRequest(requestId) {
+    const record = pending.get(requestId)
+    if (!record) return
+    pending.delete(requestId)
+    const key = requestKey(record.path, record.from.id)
+    if (pendingKeys.get(key) === requestId) pendingKeys.delete(key)
+  }
+
+  /**
+   * Deliver one event. Delivery is best effort by contract: an unknown
+   * connection is a silent drop and a throwing sink cannot break arbitration.
+   * @param {string} connectionId
+   * @param {RequestEvent | SettledEvent} event
+   */
+  function deliver(connectionId, event) {
+    if (!connections.has(connectionId)) return
+    try {
+      onEvent(connectionId, event)
+    } catch {
+      // The sink is a transport; it must never be able to corrupt the table.
+    }
+  }
+
+  /**
+   * Announce the end of a request to the requester.
+   * @param {PendingRequest} record
+   * @param {'transferred' | 'declined' | 'expired'} state
+   */
+  function settle(record, state) {
+    deliver(record.connectionId, { event: 'settled', requestId: record.requestId, path: record.path, state })
+  }
+
+  /** @param {string[]} paths */
+  function normalize(paths) {
+    return [...new Set(paths)].sort()
+  }
+
+  /** Register a connection. @param {string} connectionId */
+  function connect(connectionId) {
+    connections.add(connectionId)
+  }
+
+  /**
+   * Forget a connection: every lease it holds is released immediately (no
+   * expiry wait), and every mailbox entry it takes part in is dropped. A
+   * request whose holder went away settles as `expired` for a requester that is
+   * still connected; a request owned by the departing connection simply dies
+   * with it.
+   * @param {string} connectionId
+   */
+  function disconnect(connectionId) {
+    connections.delete(connectionId)
+    for (const [path, lease] of [...leases]) {
+      if (lease.connectionId === connectionId) leases.delete(path)
+    }
+    for (const [requestId, record] of [...pending]) {
+      if (record.connectionId === connectionId) {
+        dropRequest(requestId)
+        continue
+      }
+      if (record.holderConnectionId === connectionId) {
+        dropRequest(requestId)
+        settle(record, 'expired')
+      }
+    }
+  }
+
+  /**
+   * Acquire a whole path set atomically. Paths are evaluated in sorted order so
+   * two overlapping requests cannot deadlock and the reply is deterministic.
+   * One live foreign holder refuses the entire batch — nothing is granted.
+   * @param {AcquireInput} input
+   * @returns {AcquireResult}
+   */
+  function acquire({ connectionId, owner, scope, paths, ttlMs: requestTtlMs }) {
+    const at = now()
+    const ttl = requestTtlMs !== undefined ? requestTtlMs : ttlMs
+    /** @type {Conflict[]} */
+    const conflicts = []
+    /** @type {string[]} */
+    const fresh = []
+    /** @type {Lease[]} */
+    const adopt = []
+    for (const path of normalize(paths)) {
+      const lease = leases.get(path)
+      if (!lease || !isValid(lease)) {
+        fresh.push(path)
+        continue
+      }
+      if (lease.owner.id === owner.id && lease.connectionId === connectionId) {
+        adopt.push(lease)
+        continue
+      }
+      conflicts.push({ path, holder: { ...lease.owner }, expiresAt: lease.expiresAt, holdUntil: lease.holdUntil })
+    }
+    if (conflicts.length > 0) return { ok: false, code: 'held', conflicts }
+    /** @type {LeaseView[]} */
+    const granted = []
+    for (const lease of adopt) {
+      // Same owner, same connection: adopt. `acquiredAt` and `holdUntil` are
+      // preserved (only the sliding validity moves); session/label/scope are
+      // refreshed because this is the latest touch of that lineage.
+      lease.owner = { ...owner }
+      lease.scope = scope
+      lease.expiresAt = at + ttl
+      granted.push(view(lease))
+    }
+    for (const path of fresh) {
+      /** @type {Lease} */
+      const lease = {
+        path,
+        connectionId,
+        owner: { ...owner },
+        scope,
+        acquiredAt: at,
+        expiresAt: at + ttl,
+        holdUntil: null,
+      }
+      leases.set(path, lease)
+      granted.push(view(lease))
+    }
+    granted.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+    return { ok: true, granted }
+  }
+
+  /**
+   * Release whatever this owner still holds in the set. `notOwned` is NOT an
+   * error — after a broker restart every path is simply free, and the client's
+   * release list is its own business. Repeating a release is therefore a no-op
+   * that reports `notOwned`.
+   * @param {ReleaseInput} input
+   * @returns {ReleaseResult}
+   */
+  function release({ connectionId, owner, paths }) {
+    /** @type {string[]} */
+    const released = []
+    /** @type {string[]} */
+    const notOwned = []
+    for (const path of normalize(paths)) {
+      const lease = leases.get(path)
+      if (lease && lease.connectionId === connectionId && lease.owner.id === owner.id) {
+        leases.delete(path)
+        released.push(path)
+      } else {
+        notOwned.push(path)
+      }
+    }
+    return { ok: true, released, notOwned }
+  }
+
+  /**
+   * Extend validity to a wall-clock deadline. All-or-nothing: one path this
+   * owner does not (still) hold refuses the whole batch. The bound is a product
+   * constant, never a budget: reaching it has no consequence other than the
+   * refusal itself.
+   * @param {HoldInput} input
+   * @returns {HoldResult}
+   */
+  function hold({ connectionId, owner, paths, minutes }) {
+    if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0) return { ok: false, code: 'bad-request' }
+    if (minutes > holdMaxMinutes) return { ok: false, code: 'limit', maxMinutes: holdMaxMinutes }
+    const at = now()
+    const targets = normalize(paths)
+    /** @type {string[]} */
+    const missing = []
+    for (const path of targets) {
+      const lease = leases.get(path)
+      if (!lease || lease.connectionId !== connectionId || lease.owner.id !== owner.id || !isValid(lease)) missing.push(path)
+    }
+    if (missing.length > 0) return { ok: false, code: 'not-owned', paths: missing }
+    const deadline = at + minutes * 60_000
+    /** @type {{ path: string, expiresAt: number, holdUntil: number | null }[]} */
+    const held = []
+    for (const path of targets) {
+      const lease = /** @type {Lease} */ (leases.get(path))
+      // Only ever later: an earlier deadline never shortens an existing one.
+      lease.holdUntil = Math.max(lease.holdUntil ?? 0, deadline)
+      held.push({ path, expiresAt: lease.expiresAt, holdUntil: lease.holdUntil })
+    }
+    return { ok: true, held }
+  }
+
+  /**
+   * Read-only projection. Filters stack (AND). Lapsed rows are not reported:
+   * they are free regardless of what is still in the table, and `sweep`
+   * reclaims the memory. Returned leases are copies.
+   * @param {StatusFilter} [filter]
+   * @returns {StatusResult}
+   */
+  function status(filter = {}) {
+    /** @type {LeaseView[]} */
+    const out = []
+    for (const lease of leases.values()) {
+      if (!isValid(lease)) continue
+      if (filter.scope !== undefined && lease.scope !== filter.scope) continue
+      if (filter.session !== undefined && lease.owner.session !== filter.session) continue
+      if (filter.path !== undefined && lease.path !== filter.path) continue
+      out.push(view(lease))
+    }
+    out.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+    return { ok: true, leases: out }
+  }
+
+  /**
+   * Ask the holder of a path to hand it over. At most one pending request per
+   * (requester id, path): a repeat reuses the same `requestId` and the same
+   * window instead of opening a second mailbox entry — unless ownership changed
+   * hands in between, in which case the stale entry is replaced so the request
+   * reaches the actual holder.
+   * @param {RequestInput} input
+   * @returns {RequestResult}
+   */
+  function request({ connectionId, from, path }) {
+    const at = now()
+    const lease = leases.get(path)
+    if (!lease || !isValid(lease)) return { ok: false, code: 'free' }
+    if (lease.owner.id === from.id) return { ok: false, code: 'self' }
+    const key = requestKey(path, from.id)
+    const knownId = pendingKeys.get(key)
+    const known = knownId !== undefined ? pending.get(knownId) : undefined
+    if (known && known.holderId === lease.owner.id) {
+      return { ok: true, state: 'pending', requestId: known.requestId, holder: { ...lease.owner }, expiresAt: known.expiresAt }
+    }
+    if (known) dropRequest(known.requestId)
+    const requestId = `req-${++requestSeq}`
+    /** @type {PendingRequest} */
+    const record = {
+      requestId,
+      path,
+      from: { ...from },
+      connectionId,
+      holderConnectionId: lease.connectionId,
+      holderId: lease.owner.id,
+      expiresAt: at + requestWindowMs,
+    }
+    pending.set(requestId, record)
+    pendingKeys.set(key, requestId)
+    deliver(lease.connectionId, { event: 'request', requestId, path, from: { ...from }, expiresAt: record.expiresAt })
+    return { ok: true, state: 'pending', requestId, holder: { ...lease.owner }, expiresAt: record.expiresAt }
+  }
+
+  /**
+   * Answer a pending request as the holder.
+   *
+   * Precedence, in this order — the order is what makes all four documented
+   * outcomes reachable: unknown/elapsed request → `expired`; ownership gone or
+   * changed hands → `stale` (no ownership change); reply not from the holding
+   * connection/owner → `not-holder` and the request stays pending (a stranger
+   * must not be able to consume someone else's request); otherwise `keep`
+   * declines, `release` transfers in place.
+   * @param {ReplyInput} input
+   * @returns {ReplyResult}
+   */
+  function reply({ connectionId, owner, requestId, decision }) {
+    const at = now()
+    const record = pending.get(requestId)
+    if (!record) return { ok: false, code: 'expired' }
+    if (at >= record.expiresAt) {
+      dropRequest(requestId)
+      settle(record, 'expired')
+      return { ok: false, code: 'expired' }
+    }
+    const lease = leases.get(record.path)
+    if (!lease || !isValid(lease)) {
+      dropRequest(requestId)
+      settle(record, 'expired')
+      return { ok: false, code: 'stale' }
+    }
+    if (lease.owner.id !== record.holderId) {
+      dropRequest(requestId)
+      settle(record, 'expired')
+      return { ok: false, code: 'stale' }
+    }
+    if (lease.connectionId !== connectionId || lease.owner.id !== owner.id) return { ok: false, code: 'not-holder' }
+    dropRequest(requestId)
+    if (decision === 'keep') {
+      settle(record, 'declined')
+      return { ok: true, state: 'declined' }
+    }
+    lease.owner = { ...record.from }
+    lease.connectionId = record.connectionId
+    lease.acquiredAt = at
+    lease.expiresAt = at + ttlMs
+    lease.holdUntil = null
+    settle(record, 'transferred')
+    return { ok: true, state: 'transferred' }
+  }
+
+  /**
+   * Reclaim memory for lapsed leases and elapsed requests. Purely an
+   * optimisation for long-lived brokers — validity is decided by the clock, not
+   * by this pass — except that an elapsed request is the only moment the
+   * requester learns its request expired.
+   * @returns {{ droppedLeases: number, droppedRequests: number }}
+   */
+  function sweep() {
+    const at = now()
+    let droppedLeases = 0
+    let droppedRequests = 0
+    for (const [path, lease] of [...leases]) {
+      if (at >= validUntil(lease)) {
+        leases.delete(path)
+        droppedLeases += 1
+      }
+    }
+    for (const [requestId, record] of [...pending]) {
+      if (at >= record.expiresAt) {
+        dropRequest(requestId)
+        settle(record, 'expired')
+        droppedRequests += 1
+      }
+    }
+    return { droppedLeases, droppedRequests }
+  }
+
+  return Object.freeze({ connect, disconnect, acquire, release, hold, status, request, reply, sweep })
+}

package/src/lsp/admin.js

@@ -3,7 +3,7 @@
 // the community catalog). Plain ESM, ctx-only; `connection`/`subprocess`
 // resolve through ctx.get so the module mounts harmlessly in compositions
 // without them (headless).
-import { buildRegistry, DEFAULT_SERVERS, displayInstallCommand, installSpecFor, languageIdsForFamily } from './registry.js'
+import { buildRegistry, displayInstallCommand, installSpecFor, languageIdsForFamily, serverForPlatform } from './registry.js'
 import { npmGlobalPrefix, resolveExecutable as extendedResolveExecutable, runBounded, spawnArgv } from '../process/index.js'
 import { jsonResponse, readJsonBody } from '../shared/http-json.js'
 
@@ -39,20 +39,27 @@ export async function probeVersion(subprocess, executable, args = ['--version'],
   return first ?? null
 }
 
-/** Per-family status rows over the community catalog. */
+/**
+ * Per-family status rows over the community catalog. `options.platform`
+ * (default: the host) resolves each family's platform row first, so every
+ * displayed value — command, version probe, install command, hint — belongs to
+ * the platform being reported (D2/D5).
+ */
 export async function lspStatusFor(registry, subprocess, options = {}) {
   const probeTimeoutMs = options.probeTimeoutMs ?? VERSION_PROBE_TIMEOUT_MS
   const dirs = options.dirs ?? undefined
+  const platform = options.platform ?? process.platform
   const servers = []
   for (const [family, entry] of Object.entries(registry)) {
+    const resolved = serverForPlatform(entry, platform)
     let installed = false
     let version = null
     try {
-      const executable = await extendedResolveExecutable(subprocess, entry.command, dirs)
+      const executable = await extendedResolveExecutable(subprocess, resolved.command, dirs)
       installed = Boolean(executable)
       if (executable) {
         try {
-          version = await probeVersion(subprocess, executable, entry.versionArgs ?? ['--version'], probeTimeoutMs)
+          version = await probeVersion(subprocess, executable, resolved.versionArgs ?? ['--version'], probeTimeoutMs)
         } catch {
           version = null
         }
@@ -61,7 +68,7 @@ export async function lspStatusFor(registry, subprocess, options = {}) {
       // unresolvable command = not installed
     }
     let installerAvailable = false
-    const installerSpec = installSpecFor(entry)
+    const installerSpec = installSpecFor(resolved, platform)
     if (installerSpec) {
       try {
         installerAvailable = Boolean(await extendedResolveExecutable(subprocess, installerSpec.command, dirs))
@@ -72,11 +79,11 @@ export async function lspStatusFor(registry, subprocess, options = {}) {
     servers.push({
       family,
       languageIds: languageIdsForFamily(family),
-      command: entry.command,
+      command: resolved.command,
       installed,
       version,
-      installCommand: displayInstallCommand(entry),
-      installHint: entry.installHint ?? '',
+      installCommand: displayInstallCommand(resolved, platform),
+      installHint: resolved.installHint ?? '',
       installerAvailable,
     })
   }
@@ -87,13 +94,15 @@ export async function lspStatusFor(registry, subprocess, options = {}) {
  * Run one family's install command: argv-only (no shell), output captured,
  * bounded by a timeout. Resolves `{ output, exitCode, timedOut }`; throws a
  * structured Error for unknown families, missing installers, or a missing
- * installer binary. `dirs` overrides the extra bin-directory scan (tests).
+ * installer binary. `dirs` overrides the extra bin-directory scan (tests);
+ * `platform` selects the family's platform row and its install spec (D2).
  */
-export async function runInstall(registry, subprocess, family, timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS, dirs = undefined) {
+export async function runInstall(registry, subprocess, family, timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS, dirs = undefined, platform = process.platform) {
   const entry = registry[family]
   if (!entry) throw new Error(`lsp: unknown language family '${family}'`)
-  const spec = installSpecFor(entry)
-  if (!spec) throw new Error(`lsp: no installer for '${family}' on this platform — ${entry.installHint ?? 'see the install hint'}`)
+  const resolved = serverForPlatform(entry, platform)
+  const spec = installSpecFor(resolved, platform)
+  if (!spec) throw new Error(`lsp: no installer for '${family}' on this platform — ${resolved.installHint ?? 'see the install hint'}`)
   const executable = await extendedResolveExecutable(subprocess, spec.command, dirs).catch(() => undefined)
   if (!executable) throw new Error(`lsp: installer '${spec.command}' not found on PATH — install it first`)
   // npm installs pin a user-writable prefix: the resolved npm may belong to
@@ -127,7 +136,9 @@ export function registerLspAdminEndpoints(ctx, options = {}) {
     ctx.logger?.warn?.('weir-lsp-admin: connection/subprocess unavailable — LSP management endpoints not registered')
     return () => {}
   }
-  const registryProvider = typeof options.registry === 'function' ? options.registry : () => DEFAULT_SERVERS
+  // The catalog is platform-scoped: an absent provider builds the registry for
+  // the running host (rows resolved), never the raw unresolved DEFAULT_SERVERS.
+  const registryProvider = typeof options.registry === 'function' ? options.registry : () => buildRegistry()
   const installTimeoutMs = options.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS
   const dirs = options.dirs ?? undefined
   const disposers = []

package/src/lsp/index.js

@@ -81,7 +81,10 @@ function apply(ctx, config = {}) {
     manager = createLspManager({
       subprocess: ctx.subprocess,
       fs: ctx.fs,
-      registry: buildRegistry(option('servers', config.servers)),
+      // `config.platform` is the test seam: the registry resolves the running
+      // host's rows unless a caller pins the platform (D2 — consumers below
+      // only ever see flat, already-resolved entries).
+      registry: buildRegistry(option('servers', config.servers), config.platform ?? process.platform),
       // config.extraBinDirs overrides the extended-resolution scan dirs
       // (hermetic tests; power users with exotic install locations)
       resolveExecutable: (command) => extendedResolveExecutable(ctx.subprocess, command, config.extraBinDirs),
@@ -244,7 +247,7 @@ function apply(ctx, config = {}) {
         diagnosticsWaitMs: option('diagnosticsWaitMs', config.diagnosticsWaitMs),
       }
       manager.setOptions(Object.fromEntries(Object.entries(next).filter(([, value]) => value !== undefined)))
-      manager.setRegistry(buildRegistry(option('servers', config.servers)))
+      manager.setRegistry(buildRegistry(option('servers', config.servers), config.platform ?? process.platform))
     }
   })
   applyGate()

package/src/lsp/registry.js

@@ -64,6 +64,14 @@ export const LANGUAGE_FAMILY = {
   cpp: 'cpp',
 }
 
+/**
+ * Built-in catalog. An entry may carry `platforms: { darwin?, linux?, win32?,
+ * default? }`; every row has the entry shape (all fields optional) and
+ * overrides only the fields it declares for that platform (D1). A family whose
+ * data is identical on every platform declares it once as the shared base
+ * (npm/pipx/go/rustup); the rest keep a platform-NEUTRAL base plus one row per
+ * platform, so no platform ever sees another platform's installer (D5).
+ */
 export const DEFAULT_SERVERS = {
   typescript: {
     command: 'typescript-language-server',
@@ -155,19 +163,41 @@ export const DEFAULT_SERVERS = {
     command: 'lua-language-server',
     args: [],
     manifests: ['*.lua'],
-    installHint: 'brew install lua-language-server (macOS); see https://luals.github.io for other platforms',
-    install: {
-      darwin: { command: 'brew', args: ['install', 'lua-language-server'] },
+    installHint: 'install LuaLS from https://luals.github.io',
+    platforms: {
+      darwin: {
+        installHint: 'brew install lua-language-server',
+        install: { command: 'brew', args: ['install', 'lua-language-server'] },
+      },
+      linux: {
+        // no package-managed LuaLS on Linux: hint only, pointing at the release
+        // page (a one-click install would be a guess, not a recipe)
+        installHint: 'no package-managed LuaLS on Linux — download it from https://github.com/LuaLS/lua-language-server/releases',
+      },
+      win32: {
+        installHint: 'winget install --id LuaLS.lua-language-server -e --accept-source-agreements --accept-package-agreements',
+        install: { command: 'winget', args: ['install', '--id', 'LuaLS.lua-language-server', '-e', '--accept-source-agreements', '--accept-package-agreements'] },
+      },
     },
   },
   cpp: {
     command: 'clangd',
     args: [],
     manifests: ['*.c', '*.cpp', 'compile_commands.json'],
-    installHint: 'brew install llvm (macOS); sudo apt-get install clangd (Debian/Ubuntu)',
-    install: {
-      darwin: { command: 'brew', args: ['install', 'llvm'] },
-      linux: { command: 'sudo', args: ['apt-get', 'install', '-y', 'clangd'] },
+    installHint: 'install clangd from https://clangd.llvm.org/installation',
+    platforms: {
+      darwin: {
+        installHint: 'brew install llvm',
+        install: { command: 'brew', args: ['install', 'llvm'] },
+      },
+      linux: {
+        installHint: 'sudo apt-get install clangd',
+        install: { command: 'sudo', args: ['apt-get', 'install', '-y', 'clangd'] },
+      },
+      win32: {
+        installHint: 'winget install --id LLVM.LLVM -e --accept-source-agreements --accept-package-agreements',
+        install: { command: 'winget', args: ['install', '--id', 'LLVM.LLVM', '-e', '--accept-source-agreements', '--accept-package-agreements'] },
+      },
     },
   },
 }
@@ -192,26 +222,62 @@ export function languageIdsForFamily(family) {
   return Object.entries(LANGUAGE_FAMILY).filter(([, value]) => value === family).map(([id]) => id)
 }
 
-/** Platform-resolved install spec for a registry entry, or undefined. */
+/**
+ * Resolve one entry for a platform: `{...entry, ...platforms[platform]}` with
+ * the `platforms` key removed (D1/D2). An entry without a `platforms` map is
+ * returned unchanged — the platform is never guessed. A platform with no row
+ * (and no `default` row) keeps the entry's base fields, which are
+ * platform-neutral by contract — never another platform's recipe (D5).
+ */
+export function serverForPlatform(entry, platform = process.platform) {
+  const platforms = entry?.platforms
+  if (!platforms || typeof platforms !== 'object' || Array.isArray(platforms)) return entry
+  const row = platforms[platform] ?? platforms.default
+  const resolved = { ...entry, ...(row && typeof row === 'object' ? row : {}) }
+  delete resolved.platforms
+  return resolved
+}
+
+/**
+ * Platform-resolved install spec for a registry entry, or undefined. The entry
+ * is resolved first when it declares `platforms`. A single spec is identified
+ * by `install.command` being a string (a platform map never has a `command`
+ * key — D7); anything else is the legacy platform map, kept so existing user
+ * configs keep resolving.
+ */
 export function installSpecFor(entry, platform = process.platform) {
-  const install = entry?.install
+  const resolved = entry?.platforms ? serverForPlatform(entry, platform) : entry
+  const install = resolved?.install
   if (!install) return undefined
-  if (Array.isArray(install.args)) return install // single-spec form
+  if (typeof install.command === 'string') return install // single-spec form
   return install[platform] ?? install.default
 }
 
-/** Display form of the install command for a registry entry. */
+/**
+ * Display form of the install command for a registry entry. Where the platform
+ * declares no install spec the fallback is the RESOLVED entry's `installHint`
+ * — never another platform's command.
+ */
 export function displayInstallCommand(entry, platform = process.platform) {
-  const spec = installSpecFor(entry, platform)
-  if (!spec) return entry?.installHint ?? ''
+  const resolved = entry?.platforms ? serverForPlatform(entry, platform) : entry
+  const spec = installSpecFor(resolved, platform)
+  if (!spec) return resolved?.installHint ?? ''
   return [spec.command, ...(spec.args ?? [])].join(' ')
 }
 
-/** Merge user `lsp.servers` config over the defaults (per-language overlay). */
-export function buildRegistry(configServers) {
-  const registry = { ...DEFAULT_SERVERS }
+/**
+ * Merge user `lspServers` config over the platform-resolved catalog. Built-ins
+ * resolve first; each user override is then merged onto the resolved built-in
+ * and resolved again, so a user row overrides only the fields it declares and
+ * a user platform row wins over the built-in one (D2/D6).
+ */
+export function buildRegistry(configServers, platform = process.platform) {
+  const registry = {}
+  for (const [language, entry] of Object.entries(DEFAULT_SERVERS)) {
+    registry[language] = serverForPlatform(entry, platform)
+  }
   for (const [language, entry] of Object.entries(configServers ?? {})) {
-    registry[language] = { ...registry[language], ...entry }
+    registry[language] = serverForPlatform({ ...registry[language], ...entry }, platform)
   }
   return registry
 }