deadbyte-mcp 0.8.9 → 0.9.0

package/src/semantic-lsp-backend.mjs

@@ -0,0 +1,183 @@
+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:{},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}}));
+    return {status:'ok',root_id:rootId,path:ctx.relativePath,engine:id,diagnostics:diagnosticsOut,truncated:items.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 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});
+}

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)});
+}

package/src/tool-surface-ledger.mjs

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+
+const SURFACE_SCHEMA='deadbyte.tool-surface.v1';
+
+function canonicalValue(value,seen=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean') return value;
+  if(typeof value==='number'){
+    if(!Number.isFinite(value)) throw new Error('schema contains unsupported non-finite JSON number');
+    return Object.is(value,-0)?0:value;
+  }
+  if(typeof value==='undefined') throw new Error('schema contains unsupported undefined JSON value');
+  if(typeof value==='function') throw new Error('schema contains unsupported function JSON value');
+  if(typeof value==='symbol') throw new Error('schema contains unsupported symbol JSON value');
+  if(typeof value==='bigint') throw new Error('schema contains unsupported bigint JSON value');
+  if(typeof value!=='object') throw new Error(`schema contains unsupported JSON value type: ${typeof value}`);
+  if(seen.has(value)) throw new Error('schema contains circular JSON value');
+  seen.add(value);
+  try{
+    if(Array.isArray(value)){
+      const out=[];
+      for(let index=0;index<value.length;index+=1){
+        if(!Object.prototype.hasOwnProperty.call(value,index)) throw new Error('schema contains sparse JSON array');
+        out.push(canonicalValue(value[index],seen));
+      }
+      return out;
+    }
+    const proto=Object.getPrototypeOf(value);
+    if(proto!==Object.prototype&&proto!==null) throw new Error('schema contains unsupported non-plain JSON object');
+    const out={};
+    for(const key of Object.keys(value).sort((a,b)=>a.localeCompare(b,'en'))){
+      out[key]=canonicalValue(value[key],seen);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function canonicalJson(value){return JSON.stringify(canonicalValue(value));}
+function sha256(value){return createHash('sha256').update(value,'utf8').digest('hex');}
+
+export function canonicalSchemaHash(schema){return sha256(canonicalJson(schema));}
+
+export function snapshotToolSurface(toolDescriptors){
+  if(!Array.isArray(toolDescriptors)) throw new Error('tool descriptors must be an array');
+  const names=new Set();
+  const tools=toolDescriptors.map(descriptor=>{
+    if(!descriptor||typeof descriptor!=='object'||Array.isArray(descriptor)) throw new Error('tool descriptor must be an object');
+    const name=descriptor.name;
+    if(typeof name!=='string'||name.length<1) throw new Error('tool descriptor name must be non-empty');
+    if(names.has(name)) throw new Error(`duplicate tool: ${name}`);
+    names.add(name);
+    return {
+      name,
+      input_sha256:canonicalSchemaHash(descriptor.inputSchema),
+      output_sha256:canonicalSchemaHash(descriptor.outputSchema)
+    };
+  }).sort((a,b)=>a.name.localeCompare(b.name,'en'));
+  const body={schema:SURFACE_SCHEMA,tools};
+  return {...body,surface_sha256:sha256(canonicalJson(body))};
+}
+
+export function snapshotToolsListResult(result){
+  if(!result||typeof result!=='object'||!Array.isArray(result.tools)) throw new Error('MCP tools/list result tools must be an array');
+  return snapshotToolSurface(result.tools.map(tool=>{
+    if(!tool||typeof tool!=='object'||Array.isArray(tool)) throw new Error('MCP tools/list tool must be an object');
+    if(!tool.inputSchema||typeof tool.inputSchema!=='object'||Array.isArray(tool.inputSchema)) throw new Error(`tool ${tool.name??'<unknown>'} missing inputSchema`);
+    if(!tool.outputSchema||typeof tool.outputSchema!=='object'||Array.isArray(tool.outputSchema)) throw new Error(`tool ${tool.name??'<unknown>'} missing outputSchema`);
+    return {name:tool.name,inputSchema:tool.inputSchema,outputSchema:tool.outputSchema};
+  }));
+}
+
+function assertSnapshot(snapshot,label){
+  if(!snapshot||snapshot.schema!==SURFACE_SCHEMA||!Array.isArray(snapshot.tools)) throw new Error(`${label} tool surface snapshot invalid`);
+}
+
+export function diffToolSurface(baseline,current){
+  assertSnapshot(baseline,'baseline'); assertSnapshot(current,'current');
+  const before=new Map(baseline.tools.map(tool=>[tool.name,tool]));
+  const after=new Map(current.tools.map(tool=>[tool.name,tool]));
+  const unchanged=[]; const added=[]; const removed=[]; const schemaChanged=[];
+  for(const name of [...new Set([...before.keys(),...after.keys()])].sort((a,b)=>a.localeCompare(b,'en'))){
+    const left=before.get(name); const right=after.get(name);
+    if(!left){added.push(name);continue;}
+    if(!right){removed.push(name);continue;}
+    if(left.input_sha256===right.input_sha256&&left.output_sha256===right.output_sha256) unchanged.push(name);
+    else schemaChanged.push(name);
+  }
+  return {unchanged,added,removed,schema_changed:schemaChanged};
+}
+
+export const TOOL_SURFACE_SCHEMA=SURFACE_SCHEMA;

package/src/version.mjs

@@ -1,4 +1,4 @@
-export const DEADBYTE_VERSION = '0.8.9';
+export const DEADBYTE_VERSION = '0.9.0';
 export const MCP_PROTOCOL_VERSION = '2026-07-28';
 export const RECEIPT_SCHEMA_V1 = 'deadbyte.receipt.v1';
 export const RECEIPT_SCHEMA_V2 = 'deadbyte.receipt.v2';

package/test/audit-verify.test.mjs

@@ -19,7 +19,7 @@ async function fixture(){
 }
 async function lines(file){return (await readFile(file,'utf8')).trim().split(/\r?\n/);}
 
-test('independent verifier accepts a clean signed multi-segment audit chain',async()=>{const f=await fixture();try{const result=await verifyAuditChain({stateRoot:f.root,verifyKeyPath:f.key.publicKeyPath});assert.equal(result.ok,true);assert.equal(result.event_count,4);assert.equal(result.request_count,2);assert.equal(result.result_count,2);assert.equal(result.segment_count,2);assert.equal(result.checkpoint_count,2);assert.equal(result.last_seq,4);assert.match(result.head_sha256,/^[0-9a-f]{64}$/);}finally{await rm(f.root,{recursive:true,force:true});}});
+test('independent verifier accepts a clean signed multi-segment audit chain',async()=>{const f=await fixture();try{const result=await verifyAuditChain({stateRoot:f.root,verifyKeyPath:f.key.publicKeyPath});assert.equal(result.ok,true);assert.equal(result.event_count,4);assert.equal(result.request_count,2);assert.equal(result.result_count,2);assert.equal(result.segment_count,2);assert.equal(result.checkpoint_count,2);assert.equal(result.last_seq,4);assert.match(result.head_sha256,/^[0-9a-f]{64}$/);assert.deepEqual(result.tool_usage,[{tool:'one',requests:1,results:1,errors:0},{tool:'two',requests:1,results:1,errors:0}]);}finally{await rm(f.root,{recursive:true,force:true});}});
 
 test('verifier detects an edited event line',async()=>{const f=await fixture();try{const file=path.join(f.root,'audit','segment-00000001.jsonl');const row=await lines(file);const first=JSON.parse(row[0]);first.tool='tampered';row[0]=JSON.stringify(first);await writeFile(file,row.join('\n')+'\n');const result=await verifyAuditChain({stateRoot:f.root,verifyKeyPath:f.key.publicKeyPath});assert.equal(result.ok,false);assert.match(result.reason,/event hash mismatch/i);}finally{await rm(f.root,{recursive:true,force:true});}});
 

package/test/autonomous-action-reconcile.test.mjs

@@ -0,0 +1,106 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { actionIdentity, reconcileStartedAction } from '../src/autonomous-action-reconcile.mjs';
+
+const H = c => c.repeat(64);
+
+const identityInput = {
+  goalId:H('1'),
+  planId:H('2'),
+  planVersion:3,
+  stepId:'fix',
+  mutationEpoch:4,
+  decisionEventSha:H('5'),
+  action:{kind:'patch',operations:[{kind:'replace',path:'x.txt',expected_sha256:H('6'),old_string:'x',new_string:'y',expected_replacements:1}]}
+};
+
+test('action identity is deterministic and changes when plan version changes', () => {
+  const a = actionIdentity(identityInput);
+  const b = actionIdentity(structuredClone(identityInput));
+  assert.deepEqual(a,b);
+  assert.match(a.action_id,/^[0-9a-f]{64}$/);
+  assert.match(a.request_sha256,/^[0-9a-f]{64}$/);
+  const changed = actionIdentity({...identityInput,planVersion:4});
+  assert.notEqual(changed.action_id,a.action_id);
+  assert.notEqual(changed.request_sha256,a.request_sha256);
+});
+
+function patchStarted() {
+  return {
+    type:'action_started',event_sha256:H('7'),payload:{
+      action_id:H('8'),request_sha256:H('9'),
+      action:{kind:'patch',diff_id:H('a')}
+    }
+  };
+}
+
+test('verified mutation receipt classifies as executed without replay', async () => {
+  const result = await reconcileStartedAction({
+    startedEvent:patchStarted(),journal:[],
+    runtimes:{nativeDiffRuntime:{async verify({diffId}){
+      assert.equal(diffId,H('a'));
+      return {ok:true,current_state_matches:true,receipt_sha256:H('b'),journal_head_sha256:H('c')};
+    }}}
+  });
+  assert.equal(result.classification,'executed_verified');
+  assert.equal(result.replay_allowed,false);
+  assert.equal(result.evidence.receipt_sha256,H('b'));
+});
+
+test('missing mutation evidence is not executed and may retry with the same identity', async () => {
+  const result = await reconcileStartedAction({
+    startedEvent:patchStarted(),journal:[],
+    runtimes:{nativeDiffRuntime:{async verify(){return {ok:false,reason:'native diff receipt missing'};}}}
+  });
+  assert.equal(result.classification,'not_executed');
+  assert.equal(result.replay_allowed,true);
+});
+
+test('conflicting or unverifiable mutation evidence is ambiguous and never replayed', async () => {
+  const badSignature = await reconcileStartedAction({
+    startedEvent:patchStarted(),journal:[],
+    runtimes:{nativeDiffRuntime:{async verify(){return {ok:false,reason:'receipt signature mismatch'};}}}
+  });
+  assert.equal(badSignature.classification,'ambiguous');
+  assert.equal(badSignature.replay_allowed,false);
+
+  const staleState = await reconcileStartedAction({
+    startedEvent:patchStarted(),journal:[],
+    runtimes:{nativeDiffRuntime:{async verify(){return {ok:true,current_state_matches:false,receipt_sha256:H('b')};}}}
+  });
+  assert.equal(staleState.classification,'ambiguous');
+  assert.equal(staleState.replay_allowed,false);
+});
+
+test('verified profile failure is recovered as executed_failed_verified', async () => {
+  const started = {type:'action_started',event_sha256:H('1'),payload:{
+    action_id:H('2'),request_sha256:H('3'),
+    action:{kind:'profile',receipt_id:'a'.repeat(24),expect_exit_code:0}
+  }};
+  const result = await reconcileStartedAction({
+    startedEvent:started,journal:[],
+    runtimes:{codingRuntime:{async verifyReceiptDetailed(receiptId){
+      assert.equal(receiptId,'a'.repeat(24));
+      return {ok:true,request_sha256:H('3'),receipt_sha256:H('4'),receipt:{receipt_id:receiptId,operation:'coding_command_run',exit_code:1,timed_out:false}};
+    }}}
+  });
+  assert.equal(result.classification,'executed_failed_verified');
+  assert.equal(result.replay_allowed,false);
+  assert.equal(result.evidence.receipt_sha256,H('4'));
+});
+
+test('receipt substitution or stale request identity is ambiguous', async () => {
+  const started = {type:'action_started',event_sha256:H('1'),payload:{
+    action_id:H('2'),request_sha256:H('3'),
+    action:{kind:'profile',receipt_id:'a'.repeat(24),expect_exit_code:0}
+  }};
+  const result = await reconcileStartedAction({
+    startedEvent:started,journal:[],
+    runtimes:{codingRuntime:{async verifyReceiptDetailed(){
+      return {ok:true,request_sha256:H('f'),receipt_sha256:H('4'),receipt:{receipt_id:'a'.repeat(24),operation:'coding_command_run',exit_code:0,timed_out:false}};
+    }}}
+  });
+  assert.equal(result.classification,'ambiguous');
+  assert.match(result.reason,/request/i);
+  assert.equal(result.replay_allowed,false);
+});