deadbyte-mcp 0.8.10 → 0.10.0

package/src/semantic-backend-registry.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+const REQUIRED_METHODS=['outline','definition','references','replaceSymbol','diagnostics'];
+
+function normalizeExtension(value){
+  if(typeof value!=='string'||value.length<2||!value.startsWith('.')) throw new Error(`invalid semantic extension: ${String(value)}`);
+  return value.toLowerCase();
+}
+
+export function createSemanticBackendRegistry({backends}){
+  if(!Array.isArray(backends)||backends.length<1) throw new Error('semantic backend registry requires backends');
+  const ids=new Set();
+  const byExtension=new Map();
+  const normalized=[];
+  for(const backend of backends){
+    if(!backend||typeof backend!=='object'||Array.isArray(backend)) throw new Error('semantic backend must be an object');
+    if(typeof backend.id!=='string'||backend.id.length<1) throw new Error('semantic backend id missing');
+    if(ids.has(backend.id)) throw new Error(`duplicate semantic backend id: ${backend.id}`);
+    ids.add(backend.id);
+    if(!(backend.extensions instanceof Set)||backend.extensions.size<1) throw new Error(`semantic backend ${backend.id} extensions missing`);
+    for(const method of REQUIRED_METHODS) if(typeof backend[method]!=='function') throw new Error(`semantic backend ${backend.id} missing method ${method}`);
+    const extensions=[...backend.extensions].map(normalizeExtension).sort();
+    for(const ext of extensions){
+      if(byExtension.has(ext)) throw new Error(`semantic extension ${ext} already owned by ${byExtension.get(ext).id}`);
+      byExtension.set(ext,backend);
+    }
+    normalized.push({id:backend.id,extensions});
+  }
+  normalized.sort((a,b)=>a.id.localeCompare(b.id,'en'));
+  return Object.freeze({
+    backendForPath(relativePath){
+      const ext=path.extname(String(relativePath)).toLowerCase();
+      const backend=byExtension.get(ext);
+      if(!backend) throw new Error(`unsupported semantic language: ${ext||'<none>'}`);
+      return backend;
+    },
+    languages(){return normalized.map(item=>({id:item.id,extensions:[...item.extensions]}));}
+  });
+}

package/src/semantic-code.mjs

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import * as ts from 'typescript';
+import { createSemanticBackendRegistry } from './semantic-backend-registry.mjs';
+
+const SOURCE_EXTENSIONS=new Set(['.ts','.tsx','.mts','.cts','.js','.jsx','.mjs','.cjs']);
+const MAX_PROJECT_ENTRIES=2000;
+const MAX_SOURCE_FILES=1000;
+
+function digest(value){return createHash('sha256').update(JSON.stringify(value)).digest('hex');}
+function relNormalized(value){return value.replaceAll('\\','/').replace(/^\.\//,'');}
+function inside(root,target){const rel=path.relative(root,target);return rel===''||(!rel.startsWith(`..${path.sep}`)&&rel!=='..'&&!path.isAbsolute(rel));}
+function denied(root,absolute){
+  if(!inside(root.real_path,absolute)) return true;
+  const rel=relNormalized(path.relative(root.real_path,absolute)).toLowerCase();
+  return root.deny_paths.some(item=>rel===item||rel.startsWith(`${item}/`));
+}
+function sourceExtension(file){return SOURCE_EXTENSIONS.has(path.extname(file).toLowerCase());}
+function defaultOptions(){return {target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.NodeNext,moduleResolution:ts.ModuleResolutionKind.NodeNext,allowJs:true,checkJs:true,strict:false,noEmit:true,jsx:ts.JsxEmit.Preserve,resolveJsonModule:true,skipLibCheck:true};}
+function parseOptions(configText,rootPath){
+  if(!configText) return defaultOptions();
+  const parsed=ts.parseConfigFileTextToJson(path.join(rootPath,'tsconfig.json'),configText);
+  if(parsed.error) return defaultOptions();
+  const converted=ts.convertCompilerOptionsFromJson(parsed.config?.compilerOptions??{},rootPath);
+  return {...defaultOptions(),...converted.options,noEmit:true};
+}
+function lineColumn(source,pos){const p=source.getLineAndCharacterOfPosition(Math.max(0,Math.min(pos,source.getFullWidth())));return {line:p.line,column:p.character};}
+function locationFromSpan(project,fileName,textSpan,name='',kind='unknown'){
+  const absolute=path.resolve(fileName);
+  if(!inside(project.root.real_path,absolute)||denied(project.root,absolute)) return null;
+  const source=project.service.getProgram()?.getSourceFile(absolute);
+  if(!source) return null;
+  const start=lineColumn(source,textSpan.start); const end=lineColumn(source,textSpan.start+textSpan.length);
+  return {path:relNormalized(path.relative(project.root.real_path,absolute)),name:String(name||''),kind:String(kind||'unknown'),start_line:start.line,start_column:start.column,end_line:end.line,end_column:end.column};
+}
+async function buildProject(codingRuntime,rootId){
+  const status=await codingRuntime.sessionStatus();
+  if(!status.armed) throw new Error(`coding plane is disarmed: ${status.reason}`);
+  if(!status.root_ids.includes(rootId)) throw new Error(`coding root '${rootId}' is outside active lease`);
+  const root=codingRuntime.policy.roots[rootId];
+  if(!root||root.read!==true) throw new Error(`coding root '${rootId}' does not allow read`);
+  const tree=await codingRuntime.tree({rootId,path:'.',maxDepth:12,maxEntries:MAX_PROJECT_ENTRIES});
+  if(tree.truncated) throw new Error(`semantic project exceeds ${MAX_PROJECT_ENTRIES} entry bound; use a narrower coding root`);
+  const relativeFiles=tree.entries.filter(item=>item.type==='file'&&sourceExtension(item.path)).map(item=>item.path);
+  if(relativeFiles.length>MAX_SOURCE_FILES) throw new Error(`semantic project exceeds ${MAX_SOURCE_FILES} source file bound`);
+  const files=relativeFiles.map(rel=>path.join(root.real_path,...rel.split('/')));
+  let configText='';
+  if(tree.entries.some(item=>item.type==='file'&&item.path==='tsconfig.json')) configText=await readFile(path.join(root.real_path,'tsconfig.json'),'utf8');
+  const options=parseOptions(configText,root.real_path);
+  const versions=new Map(files.map(file=>[path.resolve(file),'1']));
+  const tsLibRoot=path.dirname(ts.getDefaultLibFilePath(options));
+  const allowedRead=file=>{
+    const absolute=path.resolve(file);
+    if(inside(tsLibRoot,absolute)) return true;
+    return inside(root.real_path,absolute)&&!denied(root,absolute);
+  };
+  const host={
+    getScriptFileNames:()=>files,
+    getScriptVersion:file=>versions.get(path.resolve(file))??'1',
+    getScriptSnapshot:file=>{if(!allowedRead(file))return undefined;const text=ts.sys.readFile(file);return text===undefined?undefined:ts.ScriptSnapshot.fromString(text);},
+    getCurrentDirectory:()=>root.real_path,
+    getCompilationSettings:()=>options,
+    getDefaultLibFileName:opts=>ts.getDefaultLibFilePath(opts),
+    fileExists:file=>allowedRead(file)&&ts.sys.fileExists(file),
+    readFile:file=>allowedRead(file)?ts.sys.readFile(file):undefined,
+    readDirectory:(dir,extensions,excludes,includes,depth)=>inside(root.real_path,path.resolve(dir))?ts.sys.readDirectory(dir,extensions,excludes,includes,depth):[],
+    directoryExists:dir=>allowedRead(path.join(dir,'_probe'))&&ts.sys.directoryExists?.(dir),
+    getDirectories:dir=>inside(root.real_path,path.resolve(dir))?(ts.sys.getDirectories?.(dir)??[]):[],
+    useCaseSensitiveFileNames:()=>ts.sys.useCaseSensitiveFileNames,
+    getNewLine:()=>ts.sys.newLine
+  };
+  const service=ts.createLanguageService(host,ts.createDocumentRegistry());
+  return {root,files,service,options};
+}
+function targetFile(project,relativePath){
+  const absolute=path.resolve(project.root.real_path,...relNormalized(relativePath).split('/'));
+  if(!inside(project.root.real_path,absolute)||denied(project.root,absolute)||!sourceExtension(absolute)) throw new Error('semantic target must be an allowed JS/TS source file');
+  const source=project.service.getProgram()?.getSourceFile(absolute);
+  if(!source) throw new Error(`semantic source unavailable: ${relativePath}`);
+  return {absolute,source};
+}
+function offsetAt(source,line,column){
+  if(!Number.isInteger(line)||line<0||!Number.isInteger(column)||column<0) throw new Error('line and column must be non-negative integers');
+  if(line>=source.getLineStarts().length) throw new Error('line is outside source file');
+  const lineStart=source.getPositionOfLineAndCharacter(line,0);
+  const lineEnd=line+1<source.getLineStarts().length?source.getPositionOfLineAndCharacter(line+1,0):source.getFullWidth();
+  const pos=lineStart+column;
+  if(pos>lineEnd) throw new Error('column is outside source line');
+  return pos;
+}
+function flattenNavigation(project,target,fileSha,maxSymbols){
+  const tree=project.service.getNavigationTree(target.absolute);
+  const out=[];
+  const visit=(item,container='')=>{
+    if(out.length>=maxSymbols) return;
+    const span=item.spans?.[0];
+    if(span&&item.text&&item.text!=='<global>'){
+      const loc=locationFromSpan(project,target.absolute,span,item.text,item.kind);
+      if(loc){
+        const nameSpan=item.nameSpan??span; const nameLoc=locationFromSpan(project,target.absolute,nameSpan,item.text,item.kind)??loc;
+        const symbolId=digest({schema:'deadbyte.semantic-symbol.v1',backend:'typescript',path:loc.path,file_sha256:fileSha,name:item.text,kind:item.kind,start:span.start,length:span.length});
+        out.push({...loc,symbol_id:symbolId,container_name:container,name_start_line:nameLoc.start_line,name_start_column:nameLoc.start_column,_span:span});
+      }
+    }
+    for(const child of item.childItems??[]) visit(child,item.text&&item.text!=='<global>'?item.text:container);
+  };
+  visit(tree,'');
+  return {symbols:out.slice(0,maxSymbols),truncated:out.length>=maxSymbols};
+}
+function diagnosticCategory(category){return ts.DiagnosticCategory[category]?.toLowerCase?.()??'unknown';}
+
+export function createTypeScriptSemanticBackend({codingRuntime}){
+  if(!codingRuntime) throw new Error('TypeScript semantic backend requires coding runtime');
+  async function outline({rootId,relativePath,maxSymbols=200}){
+    if(!Number.isInteger(maxSymbols)||maxSymbols<1||maxSymbols>500) throw new Error('max_symbols must be in [1, 500]');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const flat=flattenNavigation(project,target,file.sha256,maxSymbols);
+    return {status:'ok',root_id:rootId,path:relativePath,file_sha256:file.sha256,engine:`typescript-${ts.version}`,symbols:flat.symbols.map(({_span,...x})=>x),truncated:flat.truncated};
+  }
+  async function definition({rootId,relativePath,line,column,maxResults=50}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>200) throw new Error('max_results must be in [1, 200]');
+    await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const defs=project.service.getDefinitionAtPosition(target.absolute,pos)??[];
+    const locations=defs.map(item=>locationFromSpan(project,item.fileName,item.textSpan,item.name,item.kind)).filter(Boolean).slice(0,maxResults);
+    return {status:'ok',root_id:rootId,path:relativePath,line,column,engine:`typescript-${ts.version}`,locations,truncated:defs.length>maxResults};
+  }
+  async function references({rootId,relativePath,line,column,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const refs=project.service.getReferencesAtPosition(target.absolute,pos)??[];
+    const locations=refs.map(item=>locationFromSpan(project,item.fileName,item.textSpan,'','reference')).filter(Boolean).slice(0,maxResults);
+    return {status:'ok',root_id:rootId,path:relativePath,line,column,engine:`typescript-${ts.version}`,locations,truncated:refs.length>maxResults};
+  }
+  async function replaceSymbol({rootId,relativePath,symbolId,newBody,expectedSha256}){
+    if(typeof newBody!=='string'||newBody.length>524288) throw new Error('new_body exceeds 524288 characters');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    if(file.sha256!==expectedSha256) throw new Error(`semantic replace precondition mismatch: expected ${expectedSha256}, found ${file.sha256}`);
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const flat=flattenNavigation(project,target,file.sha256,500);
+    const symbol=flat.symbols.find(item=>item.symbol_id===symbolId);
+    if(!symbol) throw new Error('semantic symbol_id is stale or unknown for current file');
+    const oldBody=target.source.text.slice(symbol._span.start,symbol._span.start+symbol._span.length);
+    const result=await codingRuntime.textReplace({rootId,relativePath,oldString:oldBody,newString:newBody,expectedSha256,expectedReplacements:1});
+    return {...result,symbol_id:symbolId,symbol_name:symbol.name,engine:`typescript-${ts.version}`};
+  }
+  async function diagnostics({rootId,relativePath,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const all=[...project.service.getSyntacticDiagnostics(target.absolute),...project.service.getSemanticDiagnostics(target.absolute)];
+    const diagnosticsOut=all.slice(0,maxResults).map(item=>{
+      const span=Number.isInteger(item.start)&&Number.isInteger(item.length)?{start:item.start,length:item.length}:{start:0,length:0};
+      const loc=locationFromSpan(project,target.absolute,span,'','diagnostic');
+      return {message:ts.flattenDiagnosticMessageText(item.messageText,'\n'),code:String(item.code),severity:diagnosticCategory(item.category),...(loc?{location:loc}:{})};
+    });
+    const stable={root_id:rootId,path:relativePath,file_sha256:file.sha256,engine:`typescript-${ts.version}`,diagnostics:diagnosticsOut,truncated:all.length>maxResults};
+    return {status:'ok',...stable,result_sha256:digest({schema:'deadbyte.semantic-diagnostics.v1',...stable})};
+  }
+  async function implementations({rootId,relativePath,line,column,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const raw=project.service.getImplementationAtPosition(target.absolute,pos)??[];
+    const locations=raw.map(item=>locationFromSpan(project,item.fileName,item.textSpan,item.name??'',item.kind??'implementation')).filter(Boolean).slice(0,maxResults);
+    const stable={root_id:rootId,path:relativePath,line,column,file_sha256:file.sha256,engine:`typescript-${ts.version}`,locations,truncated:raw.length>maxResults};
+    return {status:'ok',...stable,result_sha256:digest({schema:'deadbyte.semantic-implementations.v1',...stable})};
+  }
+  async function renameEdits({rootId,relativePath,line,column,newName}){
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const info=project.service.getRenameInfo(target.absolute,pos,{allowRenameOfImportPath:false});
+    if(!info?.canRename) throw new Error(`semantic rename unavailable: ${info?.localizedErrorMessage??'symbol cannot be renamed'}`);
+    const raw=project.service.findRenameLocations(target.absolute,pos,false,false,true)??[];
+    if(raw.length<1) throw new Error('semantic rename produced no locations');
+    const edits=[];
+    for(const item of raw){
+      const loc=locationFromSpan(project,item.fileName,item.textSpan,'','rename');
+      if(!loc) continue;
+      edits.push({path:loc.path,start:item.textSpan.start,length:item.textSpan.length,new_text:`${item.prefixText??''}${newName}${item.suffixText??''}`});
+    }
+    if(edits.length<1) throw new Error('semantic rename produced no allowed edits');
+    edits.sort((a,b)=>a.path.localeCompare(b.path,'en')||a.start-b.start||a.length-b.length);
+    return {status:'ok',root_id:rootId,path:relativePath,engine:`typescript-${ts.version}`,target_file_sha256:file.sha256,edits};
+  }
+  return Object.freeze({id:'typescript',extensions:new Set(SOURCE_EXTENSIONS),outline,definition,references,replaceSymbol,diagnostics,implementations,renameEdits});
+}
+
+export function createSemanticCodeRuntime({codingRuntime,backends=[],nativeDiffRuntime=null}){
+  if(!codingRuntime) throw new Error('semantic runtime requires coding runtime');
+  if(!Array.isArray(backends)) throw new Error('semantic runtime backends must be an array');
+  const typescript=createTypeScriptSemanticBackend({codingRuntime});
+  const registry=createSemanticBackendRegistry({backends:[typescript,...backends]});
+  const backendFor=args=>registry.backendForPath(args.relativePath);
+  const route=(method,args)=>{
+    const backend=backendFor(args);
+    if(typeof backend[method]!=='function') return {status:'unsupported',capability:method,engine:backend.id};
+    return backend[method](args);
+  };
+  async function renamePreview({rootId,relativePath,line,column,newName}){
+    if(typeof newName!=='string'||!/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/.test(newName)) throw new Error('semantic rename new name must be a valid bounded identifier');
+    if(!nativeDiffRuntime||typeof nativeDiffRuntime.preview!=='function') throw new Error('semantic rename preview requires Native Diff runtime');
+    const backend=backendFor({relativePath});
+    if(typeof backend.renameEdits!=='function') return {status:'unsupported',capability:'rename_preview',engine:backend.id};
+    const plan=await backend.renameEdits({rootId,relativePath,line,column,newName});
+    if(plan?.status==='unsupported') return plan;
+    if(!plan||plan.status!=='ok'||!Array.isArray(plan.edits)||plan.edits.length<1) throw new Error('semantic rename backend returned no normalized edits');
+    const groups=new Map();
+    for(const edit of plan.edits){
+      if(!edit||typeof edit.path!=='string'||!Number.isInteger(edit.start)||edit.start<0||!Number.isInteger(edit.length)||edit.length<0||typeof edit.new_text!=='string') throw new Error('semantic rename edit malformed');
+      const list=groups.get(edit.path)??[]; list.push(edit); groups.set(edit.path,list);
+    }
+    const operations=[]; const preimages=[]; let editCount=0;
+    for(const filePath of [...groups.keys()].sort((a,b)=>a.localeCompare(b,'en'))){
+      const file=await codingRuntime.fileRead({rootId,relativePath:filePath,encoding:'utf8'});
+      const edits=[...groups.get(filePath)].sort((a,b)=>a.start-b.start||a.length-b.length);
+      let priorEnd=-1;
+      for(const edit of edits){
+        if(edit.start<priorEnd) throw new Error(`semantic rename overlapping edits in ${filePath}`);
+        if(edit.start+edit.length>file.content.length) throw new Error(`semantic rename edit outside ${filePath}`);
+        priorEnd=edit.start+edit.length;
+      }
+      let next=file.content;
+      for(const edit of [...edits].sort((a,b)=>b.start-a.start)) next=next.slice(0,edit.start)+edit.new_text+next.slice(edit.start+edit.length);
+      operations.push({kind:'write',path:filePath,content:next,encoding:'utf8',expected_sha256:file.sha256});
+      preimages.push({path:filePath,sha256:file.sha256});
+      editCount+=edits.length;
+    }
+    const diff=await nativeDiffRuntime.preview({rootId,title:`semantic rename ${relativePath} -> ${newName}`,operations});
+    return {status:'ready',diff_id:diff.diff_id,affected_files:operations.length,edit_count:editCount,
+      backend:plan.engine??backend.id,preimages};
+  }
+  return Object.freeze({
+    outline:async args=>route('outline',args),
+    definition:async args=>route('definition',args),
+    references:async args=>route('references',args),
+    replaceSymbol:async args=>route('replaceSymbol',args),
+    diagnostics:async args=>route('diagnostics',args),
+    implementations:async args=>route('implementations',args),
+    renamePreview,
+    languages:()=>registry.languages()
+  });
+}

package/src/semantic-lsp-backend.mjs

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createLspStdioClient } from './lsp-stdio-client.mjs';
+
+const SYMBOL_KIND={1:'file',2:'module',3:'namespace',4:'package',5:'class',6:'method',7:'property',8:'field',9:'constructor',10:'enum',11:'interface',12:'function',13:'variable',14:'constant',15:'string',16:'number',17:'boolean',18:'array',19:'object',20:'key',21:'null',22:'enum_member',23:'struct',24:'event',25:'operator',26:'type_parameter'};
+const SEVERITY={1:'error',2:'warning',3:'information',4:'hint'};
+const MAX_WORKSPACE_ENTRIES=512;
+const MAX_WORKSPACE_DOCUMENTS=128;
+const relNormalized=value=>value.replaceAll('\\','/').replace(/^\.\//,'');
+const digest=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function inside(root,target){const rel=path.relative(root,target);return rel===''||(!rel.startsWith(`..${path.sep}`)&&rel!=='..'&&!path.isAbsolute(rel));}
+function denied(root,absolute){
+  if(!inside(root.real_path,absolute)) return true;
+  const rel=relNormalized(path.relative(root.real_path,absolute)).toLowerCase();
+  return (root.deny_paths??[]).some(item=>rel===String(item).toLowerCase()||rel.startsWith(`${String(item).toLowerCase()}/`));
+}
+function kindName(kind){return SYMBOL_KIND[Number(kind)]??String(kind??'unknown');}
+function validPosition(value){return value&&Number.isInteger(value.line)&&value.line>=0&&Number.isInteger(value.character)&&value.character>=0;}
+function validRange(value){return value&&validPosition(value.start)&&validPosition(value.end);}
+function positionToOffset(text,position){
+  if(!validPosition(position)) throw new Error('LSP position invalid');
+  let line=0,start=0;
+  while(line<position.line){const next=text.indexOf('\n',start);if(next<0)throw new Error('LSP position line outside file');start=next+1;line+=1;}
+  const lineEnd=text.indexOf('\n',start);const end=lineEnd<0?text.length:lineEnd;
+  const offset=start+position.character;
+  if(offset>end) throw new Error('LSP position character outside line');
+  return offset;
+}
+function rangeLocation(root,uri,range,{name='',kind='unknown'}={}){
+  if(typeof uri!=='string'||!uri.startsWith('file:')||!validRange(range)) return null;
+  let absolute;
+  try { absolute=path.resolve(fileURLToPath(uri)); } catch { return null; }
+  if(!inside(root.real_path,absolute)||denied(root,absolute)) return null;
+  return {path:relNormalized(path.relative(root.real_path,absolute)),name:String(name),kind:String(kind),start_line:range.start.line,start_column:range.start.character,end_line:range.end.line,end_column:range.end.character};
+}
+async function rootContext(codingRuntime,rootId,relativePath){
+  const status=await codingRuntime.sessionStatus();
+  if(!status.armed) throw new Error(`coding plane is disarmed: ${status.reason}`);
+  if(!status.root_ids.includes(rootId)) throw new Error(`coding root '${rootId}' is outside active lease`);
+  const root=codingRuntime.policy.roots[rootId];
+  if(!root||root.read!==true) throw new Error(`coding root '${rootId}' does not allow read`);
+  const normalized=relNormalized(relativePath);
+  const absolute=path.resolve(root.real_path,...normalized.split('/'));
+  if(!inside(root.real_path,absolute)) throw new Error('semantic target escapes coding root');
+  if(denied(root,absolute)) throw new Error(`semantic target denied by coding policy: ${normalized}`);
+  const file=await codingRuntime.fileRead({rootId,relativePath:normalized,encoding:'utf8'});
+  if(typeof file.content!=='string'||typeof file.sha256!=='string') throw new Error('semantic target read missing content identity');
+  return {root,rootId,relativePath:normalized,absolute,file,uri:pathToFileURL(absolute).href,rootUri:pathToFileURL(root.real_path+path.sep).href};
+}
+function flattenDocumentSymbols(result,ctx,backendId,maxSymbols){
+  if(!Array.isArray(result)) return {symbols:[],truncated:false};
+  const out=[];
+  const visit=(item,container='')=>{
+    if(out.length>=maxSymbols||!item||typeof item!=='object') return;
+    if(item.location?.uri&&validRange(item.location.range)){
+      const kind=kindName(item.kind);const loc=rangeLocation(ctx.root,item.location.uri,item.location.range,{name:item.name??'',kind});
+      if(loc){const selection=item.location.range;const symbolId=digest({schema:'deadbyte.semantic-symbol.v1',backend:backendId,path:loc.path,file_sha256:ctx.file.sha256,name:loc.name,kind,range:item.location.range});out.push({...loc,symbol_id:symbolId,container_name:String(item.containerName??container),name_start_line:selection.start.line,name_start_column:selection.start.character,_range:item.location.range});}
+      return;
+    }
+    if(typeof item.name==='string'&&validRange(item.range)){
+      const kind=kindName(item.kind);const loc={path:ctx.relativePath,name:item.name,kind,start_line:item.range.start.line,start_column:item.range.start.character,end_line:item.range.end.line,end_column:item.range.end.character};
+      const selection=validRange(item.selectionRange)?item.selectionRange:item.range;
+      const symbolId=digest({schema:'deadbyte.semantic-symbol.v1',backend:backendId,path:loc.path,file_sha256:ctx.file.sha256,name:item.name,kind,range:item.range});
+      out.push({...loc,symbol_id:symbolId,container_name:container,name_start_line:selection.start.line,name_start_column:selection.start.character,_range:item.range});
+      for(const child of item.children??[]) visit(child,item.name);
+    }
+  };
+  for(const item of result) visit(item,'');
+  return {symbols:out.slice(0,maxSymbols),truncated:out.length>=maxSymbols};
+}
+function normalizeLocations(result,ctx,maxResults){
+  const raw=result==null?[]:(Array.isArray(result)?result:[result]);
+  const locations=[];
+  for(const item of raw){
+    let uri=null,range=null;
+    if(item?.uri&&validRange(item.range)){uri=item.uri;range=item.range;}
+    else if(item?.targetUri&&validRange(item.targetSelectionRange??item.targetRange)){uri=item.targetUri;range=item.targetSelectionRange??item.targetRange;}
+    const loc=rangeLocation(ctx.root,uri,range,{name:'',kind:'reference'});if(loc)locations.push(loc);
+  }
+  return {locations:locations.slice(0,maxResults),truncated:locations.length>maxResults};
+}
+
+export function createSemanticLspBackend({id,extensions,codingRuntime,server}){
+  if(typeof id!=='string'||id.length<1) throw new Error('semantic LSP backend id missing');
+  if(!Array.isArray(extensions)||extensions.length<1) throw new Error(`semantic LSP backend ${id} extensions missing`);
+  if(!codingRuntime) throw new Error(`semantic LSP backend ${id} requires coding runtime`);
+  if(!server||typeof server!=='object') throw new Error(`semantic LSP backend ${id} server config missing`);
+  const extensionSet=new Set(extensions.map(ext=>String(ext).toLowerCase()));
+  const languageId=String(server.language_id??id);
+  const startupSettleMs=server.startup_settle_ms===undefined?0:Number(server.startup_settle_ms);
+  if(!Number.isInteger(startupSettleMs)||startupSettleMs<0||startupSettleMs>5000) throw new Error(`semantic LSP backend ${id} startup_settle_ms invalid`);
+  const nullResultRetryMs=server.null_result_retry_ms===undefined?0:Number(server.null_result_retry_ms);
+  const nullResultMaxAttempts=server.null_result_max_attempts===undefined?1:Number(server.null_result_max_attempts);
+  const retryEmptyResults=server.retry_empty_results===undefined?false:server.retry_empty_results;
+  if(!Number.isInteger(nullResultRetryMs)||nullResultRetryMs<0||nullResultRetryMs>1000) throw new Error(`semantic LSP backend ${id} null_result_retry_ms invalid`);
+  if(!Number.isInteger(nullResultMaxAttempts)||nullResultMaxAttempts<1||nullResultMaxAttempts>20) throw new Error(`semantic LSP backend ${id} null_result_max_attempts invalid`);
+  if(typeof retryEmptyResults!=='boolean') throw new Error(`semantic LSP backend ${id} retry_empty_results invalid`);
+  if(nullResultMaxAttempts>1&&nullResultRetryMs<1) throw new Error(`semantic LSP backend ${id} null_result_retry_ms required when retrying null results`);
+  const workspaceDocuments=async ctx=>{
+    const target={relativePath:ctx.relativePath,uri:ctx.uri,text:ctx.file.content};
+    if(typeof codingRuntime.tree!=='function') return [target];
+    const tree=await codingRuntime.tree({rootId:ctx.rootId,path:'.',maxDepth:12,maxEntries:MAX_WORKSPACE_ENTRIES});
+    if(tree.truncated) throw new Error(`semantic LSP workspace exceeds ${MAX_WORKSPACE_ENTRIES} entry bound`);
+    const relativeFiles=tree.entries.filter(item=>item.type==='file'&&extensionSet.has(path.extname(item.path).toLowerCase())).map(item=>relNormalized(item.path));
+    if(relativeFiles.length>MAX_WORKSPACE_DOCUMENTS) throw new Error(`semantic LSP workspace exceeds ${MAX_WORKSPACE_DOCUMENTS} source document bound`);
+    const documents=[];
+    for(const relativePath of relativeFiles){
+      if(relativePath===ctx.relativePath){documents.push(target);continue;}
+      const absolute=path.resolve(ctx.root.real_path,...relativePath.split('/'));
+      if(!inside(ctx.root.real_path,absolute)||denied(ctx.root,absolute)) continue;
+      const file=await codingRuntime.fileRead({rootId:ctx.rootId,relativePath,encoding:'utf8'});
+      if(typeof file.content!=='string') throw new Error(`semantic LSP preload missing UTF-8 content: ${relativePath}`);
+      documents.push({relativePath,uri:pathToFileURL(absolute).href,text:file.content});
+    }
+    if(!documents.some(item=>item.relativePath===ctx.relativePath)) documents.unshift(target);
+    return documents;
+  };
+  const open=async ctx=>{
+    const client=createLspStdioClient({executablePath:server.executable_path,expectedSha256:server.executable_sha256,args:server.args??[],cwd:ctx.root.real_path,env:server.env??{},dependencies:server.dependencies??[],requestTimeoutMs:server.request_timeout_ms??10000,maxMessageBytes:server.max_message_bytes??4*1024*1024});
+    try{
+      await client.initialize({processId:null,rootPath:ctx.root.real_path,rootUri:ctx.rootUri,workspaceFolders:[{uri:ctx.rootUri,name:path.basename(ctx.root.real_path)}],capabilities:{workspace:{workspaceFolders:true},textDocument:{documentSymbol:{hierarchicalDocumentSymbolSupport:true},definition:{},references:{},implementation:{},rename:{prepareSupport:false},diagnostic:{}}},initializationOptions:server.initialization_options??{}});
+      for(const document of await workspaceDocuments(ctx)) client.notify('textDocument/didOpen',{textDocument:{uri:document.uri,languageId,version:1,text:document.text}});
+      if(startupSettleMs>0) await new Promise(resolve=>setTimeout(resolve,startupSettleMs));
+      return client;
+    } catch(error){await client.shutdown().catch(()=>{});throw error;}
+  };
+  const withClient=async(ctx,fn)=>{const client=await open(ctx);try{return await fn(client);}finally{await client.shutdown().catch(()=>{});}};
+  const requestRead=async(client,method,params)=>{
+    let result=null;
+    for(let attempt=1;attempt<=nullResultMaxAttempts;attempt+=1){
+      result=await client.request(method,params);
+      const transientEmpty=retryEmptyResults&&Array.isArray(result)&&result.length===0;
+      if((result!==null&&!transientEmpty)||attempt===nullResultMaxAttempts) return result;
+      await new Promise(resolve=>setTimeout(resolve,nullResultRetryMs));
+    }
+    return result;
+  };
+  async function outline({rootId,relativePath,maxSymbols=200}){
+    if(!Number.isInteger(maxSymbols)||maxSymbols<1||maxSymbols>500) throw new Error('max_symbols must be in [1, 500]');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    const raw=await withClient(ctx,client=>requestRead(client,'textDocument/documentSymbol',{textDocument:{uri:ctx.uri}}));
+    const flat=flattenDocumentSymbols(raw,ctx,id,maxSymbols);
+    return {status:'ok',root_id:rootId,path:ctx.relativePath,file_sha256:ctx.file.sha256,engine:id,symbols:flat.symbols.map(({_range,...item})=>item),truncated:flat.truncated};
+  }
+  async function definition({rootId,relativePath,line,column,maxResults=50}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>200) throw new Error('max_results must be in [1, 200]');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    const raw=await withClient(ctx,client=>requestRead(client,'textDocument/definition',{textDocument:{uri:ctx.uri},position:{line,character:column}}));
+    const normalized=normalizeLocations(raw,ctx,maxResults);
+    return {status:'ok',root_id:rootId,path:ctx.relativePath,line,column,engine:id,...normalized};
+  }
+  async function references({rootId,relativePath,line,column,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    const raw=await withClient(ctx,client=>requestRead(client,'textDocument/references',{textDocument:{uri:ctx.uri},position:{line,character:column},context:{includeDeclaration:true}}));
+    const normalized=normalizeLocations(raw,ctx,maxResults);
+    return {status:'ok',root_id:rootId,path:ctx.relativePath,line,column,engine:id,...normalized};
+  }
+  async function diagnostics({rootId,relativePath,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    const raw=await withClient(ctx,client=>requestRead(client,'textDocument/diagnostic',{textDocument:{uri:ctx.uri}}));
+    const items=Array.isArray(raw?.items)?raw.items:[];
+    const diagnosticsOut=items.slice(0,maxResults).filter(item=>validRange(item?.range)).map(item=>({message:String(item.message??''),code:String(item.code??''),severity:SEVERITY[Number(item.severity)]??'unknown',location:{path:ctx.relativePath,name:'',kind:'diagnostic',start_line:item.range.start.line,start_column:item.range.start.character,end_line:item.range.end.line,end_column:item.range.end.character}}));
+    const stable={root_id:rootId,path:ctx.relativePath,file_sha256:ctx.file.sha256,engine:id,diagnostics:diagnosticsOut,truncated:items.length>maxResults};
+    return {status:'ok',...stable,result_sha256:digest({schema:'deadbyte.semantic-diagnostics.v1',...stable})};
+  }
+  async function implementations({rootId,relativePath,line,column,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    let raw;
+    try { raw=await withClient(ctx,client=>requestRead(client,'textDocument/implementation',{textDocument:{uri:ctx.uri},position:{line,character:column}})); }
+    catch(error){ if(/-32601|method not found/i.test(String(error))) return {status:'unsupported',capability:'implementations',engine:id}; throw error; }
+    const normalized=normalizeLocations(raw,ctx,maxResults);
+    const stable={root_id:rootId,path:ctx.relativePath,line,column,file_sha256:ctx.file.sha256,engine:id,...normalized};
+    return {status:'ok',...stable,result_sha256:digest({schema:'deadbyte.semantic-implementations.v1',...stable})};
+  }
+  async function renameEdits({rootId,relativePath,line,column,newName}){
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    let raw;
+    try { raw=await withClient(ctx,client=>requestRead(client,'textDocument/rename',{textDocument:{uri:ctx.uri},position:{line,character:column},newName})); }
+    catch(error){ if(/-32601|method not found/i.test(String(error))) return {status:'unsupported',capability:'rename_preview',engine:id}; throw error; }
+    const byUri=[];
+    if(raw?.changes&&typeof raw.changes==='object') for(const [uri,edits] of Object.entries(raw.changes)) byUri.push({uri,edits});
+    for(const change of raw?.documentChanges??[]){ if(change?.textDocument?.uri&&Array.isArray(change.edits)) byUri.push({uri:change.textDocument.uri,edits:change.edits}); }
+    const normalized=[];
+    for(const group of byUri){
+      let absolute; try{absolute=path.resolve(fileURLToPath(group.uri));}catch{continue;}
+      if(!inside(ctx.root.real_path,absolute)||denied(ctx.root,absolute)) continue;
+      const rel=relNormalized(path.relative(ctx.root.real_path,absolute));
+      const file=await codingRuntime.fileRead({rootId,relativePath:rel,encoding:'utf8'});
+      for(const edit of group.edits??[]){
+        if(!validRange(edit?.range)||typeof edit?.newText!=='string') throw new Error('semantic LSP rename edit malformed');
+        const start=positionToOffset(file.content,edit.range.start); const end=positionToOffset(file.content,edit.range.end);
+        if(end<start) throw new Error('semantic LSP rename range invalid');
+        normalized.push({path:rel,start,length:end-start,new_text:edit.newText});
+      }
+    }
+    if(normalized.length<1) throw new Error('semantic LSP rename produced no allowed edits');
+    normalized.sort((a,b)=>a.path.localeCompare(b.path,'en')||a.start-b.start||a.length-b.length);
+    return {status:'ok',root_id:rootId,path:ctx.relativePath,engine:id,target_file_sha256:ctx.file.sha256,edits:normalized};
+  }
+  async function replaceSymbol({rootId,relativePath,symbolId,newBody,expectedSha256}){
+    if(typeof newBody!=='string'||newBody.length>524288) throw new Error('new_body exceeds 524288 characters');
+    const ctx=await rootContext(codingRuntime,rootId,relativePath);
+    if(ctx.file.sha256!==expectedSha256) throw new Error(`semantic replace precondition mismatch: expected ${expectedSha256}, found ${ctx.file.sha256}`);
+    const raw=await withClient(ctx,client=>requestRead(client,'textDocument/documentSymbol',{textDocument:{uri:ctx.uri}}));
+    const flat=flattenDocumentSymbols(raw,ctx,id,500);
+    const symbol=flat.symbols.find(item=>item.symbol_id===symbolId);
+    if(!symbol) throw new Error('semantic symbol_id is stale or unknown for current file');
+    const start=positionToOffset(ctx.file.content,symbol._range.start);const end=positionToOffset(ctx.file.content,symbol._range.end);
+    if(end<start) throw new Error('semantic symbol range invalid');
+    const oldBody=ctx.file.content.slice(start,end);
+    const result=await codingRuntime.textReplace({rootId,relativePath:ctx.relativePath,oldString:oldBody,newString:newBody,expectedSha256,expectedReplacements:1});
+    return {...result,symbol_id:symbolId,symbol_name:symbol.name,engine:id};
+  }
+  return Object.freeze({id,extensions:extensionSet,outline,definition,references,replaceSymbol,diagnostics,implementations,renameEdits});
+}

package/src/semantic-lsp-config.mjs

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createSemanticLspBackend } from './semantic-lsp-backend.mjs';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+
+function plainObject(value){return value&&typeof value==='object'&&!Array.isArray(value);}
+
+export function parseSemanticLspConfig(value){
+  if(!plainObject(value)||value.schema!=='deadbyte.semantic-lsp-config.v1') throw new Error('semantic LSP config schema mismatch');
+  if(!Array.isArray(value.servers)) throw new Error('semantic LSP config servers must be an array');
+  if(value.servers.length>16) throw new Error('semantic LSP config server count exceeds 16');
+  const ids=new Set();
+  const extensions=new Map();
+  const servers=value.servers.map((raw,index)=>{
+    if(!plainObject(raw)) throw new Error(`semantic LSP server ${index} must be an object`);
+    const id=String(raw.id??'');
+    if(!ID.test(id)) throw new Error(`semantic LSP server ${index} id invalid`);
+    const languageId=String(raw.language_id??id);
+    if(!ID.test(languageId)) throw new Error(`semantic LSP server ${id} language_id invalid`);
+    if(ids.has(id)) throw new Error(`duplicate semantic LSP server id: ${id}`);
+    ids.add(id);
+    if(!Array.isArray(raw.extensions)||raw.extensions.length<1||raw.extensions.length>32) throw new Error(`semantic LSP server ${id} extensions missing`);
+    const normalizedExtensions=[];
+    for(const item of raw.extensions){
+      const ext=String(item??'').toLowerCase();
+      if(!/^\.[a-z0-9+_-]{1,16}$/.test(ext)) throw new Error(`semantic LSP server ${id} extension invalid: ${ext||'<empty>'}`);
+      const owner=extensions.get(ext);
+      if(owner&&owner!==id) throw new Error(`semantic extension ${ext} already owned by ${owner}`);
+      extensions.set(ext,id);
+      if(!normalizedExtensions.includes(ext)) normalizedExtensions.push(ext);
+    }
+    const executablePath=String(raw.executable_path??'');
+    if(!path.isAbsolute(executablePath)) throw new Error(`semantic LSP server ${id} executable_path must be absolute`);
+    const executableSha=String(raw.executable_sha256??'').toLowerCase();
+    if(!HEX64.test(executableSha)) throw new Error(`semantic LSP server ${id} executable SHA-256 invalid`);
+    const args=raw.args===undefined?[]:raw.args;
+    if(!Array.isArray(args)||args.length>64||args.some(item=>typeof item!=='string'||item.length>2048)) throw new Error(`semantic LSP server ${id} args invalid`);
+    const env=raw.env===undefined?{}:raw.env;
+    if(!plainObject(env)||Object.entries(env).some(([key,item])=>!ID.test(key)||typeof item!=='string'||item.length>4096)) throw new Error(`semantic LSP server ${id} env invalid`);
+    const dependencies=raw.dependencies===undefined?[]:raw.dependencies;
+    if(!Array.isArray(dependencies)||dependencies.length>32) throw new Error(`semantic LSP server ${id} dependencies invalid`);
+    const normalizedDependencies=dependencies.map((dependency,depIndex)=>{
+      if(!plainObject(dependency)) throw new Error(`semantic LSP server ${id} dependency ${depIndex} invalid`);
+      const dependencyPath=String(dependency.path??'');
+      if(!path.isAbsolute(dependencyPath)) throw new Error(`semantic LSP server ${id} dependency path must be absolute`);
+      const expectedSha256=String(dependency.expected_sha256??dependency.expectedSha256??'').toLowerCase();
+      if(!HEX64.test(expectedSha256)) throw new Error(`semantic LSP server ${id} dependency SHA-256 invalid`);
+      return {path:dependencyPath,expectedSha256};
+    });
+    const initializationOptions=raw.initialization_options===undefined?{}:raw.initialization_options;
+    if(!plainObject(initializationOptions)) throw new Error(`semantic LSP server ${id} initialization_options invalid`);
+    const requestTimeoutMs=raw.request_timeout_ms===undefined?10000:Number(raw.request_timeout_ms);
+    if(!Number.isInteger(requestTimeoutMs)||requestTimeoutMs<100||requestTimeoutMs>120000) throw new Error(`semantic LSP server ${id} request_timeout_ms invalid`);
+    const maxMessageBytes=raw.max_message_bytes===undefined?4*1024*1024:Number(raw.max_message_bytes);
+    if(!Number.isInteger(maxMessageBytes)||maxMessageBytes<256||maxMessageBytes>16*1024*1024) throw new Error(`semantic LSP server ${id} max_message_bytes invalid`);
+    const startupSettleMs=raw.startup_settle_ms===undefined?0:Number(raw.startup_settle_ms);
+    if(!Number.isInteger(startupSettleMs)||startupSettleMs<0||startupSettleMs>5000) throw new Error(`semantic LSP server ${id} startup_settle_ms invalid`);
+    const nullResultRetryMs=raw.null_result_retry_ms===undefined?0:Number(raw.null_result_retry_ms);
+    const nullResultMaxAttempts=raw.null_result_max_attempts===undefined?1:Number(raw.null_result_max_attempts);
+    const retryEmptyResults=raw.retry_empty_results===undefined?false:raw.retry_empty_results;
+    if(!Number.isInteger(nullResultRetryMs)||nullResultRetryMs<0||nullResultRetryMs>1000) throw new Error(`semantic LSP server ${id} null_result_retry_ms invalid`);
+    if(!Number.isInteger(nullResultMaxAttempts)||nullResultMaxAttempts<1||nullResultMaxAttempts>20) throw new Error(`semantic LSP server ${id} null_result_max_attempts invalid`);
+    if(typeof retryEmptyResults!=='boolean') throw new Error(`semantic LSP server ${id} retry_empty_results invalid`);
+    if(nullResultMaxAttempts>1&&nullResultRetryMs<1) throw new Error(`semantic LSP server ${id} null_result_retry_ms required when retrying null results`);
+    const required=raw.required===undefined?false:raw.required;
+    if(typeof required!=='boolean') throw new Error(`semantic LSP server ${id} required must be boolean`);
+    return {id,language_id:languageId,extensions:normalizedExtensions,executable_path:executablePath,executable_sha256:executableSha,args:[...args],env:{...env},dependencies:normalizedDependencies,initialization_options:initializationOptions,request_timeout_ms:requestTimeoutMs,max_message_bytes:maxMessageBytes,startup_settle_ms:startupSettleMs,null_result_retry_ms:nullResultRetryMs,null_result_max_attempts:nullResultMaxAttempts,retry_empty_results:retryEmptyResults,required};
+  });
+  return Object.freeze({schema:'deadbyte.semantic-lsp-config.v1',servers});
+}
+
+export function semanticConfigBindingFromEnv(env=process.env){
+  const configPath=String(env.DEADBYTE_SEMANTIC_LSP_CONFIG??'').trim();
+  const expectedConfigSha256=String(env.DEADBYTE_SEMANTIC_LSP_CONFIG_SHA256??'').trim().toLowerCase();
+  if(!configPath&&!expectedConfigSha256) return null;
+  if(configPath&&!expectedConfigSha256) throw new Error('DEADBYTE_SEMANTIC_LSP_CONFIG requires semantic LSP config SHA-256');
+  if(!configPath&&expectedConfigSha256) throw new Error('DEADBYTE_SEMANTIC_LSP_CONFIG_SHA256 requires semantic LSP config path');
+  if(!path.isAbsolute(configPath)) throw new Error('semantic LSP config path must be absolute');
+  if(!HEX64.test(expectedConfigSha256)) throw new Error('semantic LSP config SHA-256 invalid');
+  return Object.freeze({configPath,expectedConfigSha256});
+}
+
+export async function loadSemanticLspBackends({configPath,expectedConfigSha256,codingRuntime}){
+  if(typeof configPath!=='string'||!path.isAbsolute(configPath)) throw new Error('semantic LSP config path must be absolute');
+  if(!HEX64.test(expectedConfigSha256??'')) throw new Error('semantic LSP config SHA-256 invalid');
+  if(!codingRuntime) throw new Error('semantic LSP config requires coding runtime');
+  let configBytes,parsedJson;
+  try { configBytes=await readFile(configPath); parsedJson=JSON.parse(configBytes.toString('utf8')); }
+  catch(error){ throw new Error(`semantic LSP config read failed: ${error.message}`); }
+  const observedConfigSha256=sha256(configBytes);
+  if(observedConfigSha256!==expectedConfigSha256) throw new Error(`semantic LSP config SHA-256 mismatch: expected ${expectedConfigSha256}, found ${observedConfigSha256}`);
+  const config=parseSemanticLspConfig(parsedJson);
+  const backends=[];
+  const requiredIds=[];
+  for(const server of config.servers){
+    const executableBytes=await readFile(server.executable_path);
+    const executableSha=sha256(executableBytes);
+    if(executableSha!==server.executable_sha256) throw new Error(`semantic LSP executable SHA-256 mismatch for ${server.id}: expected ${server.executable_sha256}, found ${executableSha}`);
+    for(const dependency of server.dependencies){
+      const dependencyBytes=await readFile(dependency.path);
+      const dependencySha=sha256(dependencyBytes);
+      if(dependencySha!==dependency.expectedSha256) throw new Error(`semantic LSP dependency SHA-256 mismatch for ${server.id}: expected ${dependency.expectedSha256}, found ${dependencySha}`);
+    }
+    backends.push(createSemanticLspBackend({id:server.id,extensions:server.extensions,codingRuntime,server}));
+    if(server.required) requiredIds.push(server.id);
+  }
+  return Object.freeze({backends:Object.freeze(backends),required_ids:Object.freeze(requiredIds)});
+}