deadbyte-mcp 0.9.0 → 0.10.0

package/src/capability-ledger.mjs

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+
+export const CAPABILITY_LEDGER_SCHEMA='deadbyte.capability-ledger.v1';
+const AUTHORITIES=new Set(['none','process','coding','autonomous','host']);
+const PROFILE_ENV='DEADBYTE_CAPABILITY_PROFILE';
+const COMPACT_TOOL_LIMIT=42;
+
+function sha256(text){return createHash('sha256').update(text,'utf8').digest('hex');}
+function canonicalJson(value){
+  if(value===null||typeof value!=='object') return JSON.stringify(value);
+  if(Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  return `{${Object.keys(value).sort((a,b)=>a.localeCompare(b,'en')).map(key=>`${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+}
+function nonEmpty(value,label){if(typeof value!=='string'||value.length<1) throw new Error(`${label} must be non-empty`); return value;}
+function nullableRoute(value,label){if(value===null) return null; return nonEmpty(value,label);}
+function normalizedEntry(raw){
+  if(!raw||typeof raw!=='object'||Array.isArray(raw)) throw new Error('capability entry must be an object');
+  const authority=nonEmpty(raw.authority,'capability authority');
+  if(!AUTHORITIES.has(authority)) throw new Error(`unknown capability authority: ${authority}`);
+  const entry={
+    id:nonEmpty(raw.id,'capability id'),
+    full_tool:nonEmpty(raw.full_tool,'capability full_tool'),
+    compact_tool:nullableRoute(raw.compact_tool??null,'capability compact_tool'),
+    compact_op:nullableRoute(raw.compact_op??null,'capability compact_op'),
+    runtime_flag:raw.runtime_flag===null?null:nonEmpty(raw.runtime_flag,'capability runtime_flag'),
+    authority,
+    mutating:raw.mutating===true,
+    receipt_class:raw.receipt_class===null?null:nonEmpty(raw.receipt_class,'capability receipt_class'),
+    production:raw.production===true,
+    host_only:raw.host_only===true
+  };
+  if((entry.compact_tool===null)!==(entry.compact_op===null)) throw new Error(`capability ${entry.id} compact route requires both tool and op`);
+  if(entry.host_only&&entry.authority!=='host') throw new Error(`capability ${entry.id} host_only requires host authority`);
+  return Object.freeze(entry);
+}
+
+export function createCapabilityLedger(entries){
+  if(!Array.isArray(entries)) throw new Error('capability entries must be an array');
+  const seen=new Set();
+  const normalized=entries.map(normalizedEntry);
+  for(const item of normalized){
+    if(seen.has(item.id)) throw new Error(`duplicate capability id: ${item.id}`);
+    seen.add(item.id);
+  }
+  normalized.sort((a,b)=>a.id.localeCompare(b.id,'en'));
+  const frozenEntries=Object.freeze(normalized.slice());
+  const body={schema:CAPABILITY_LEDGER_SCHEMA,entries:frozenEntries};
+  return Object.freeze({...body,ledger_sha256:sha256(canonicalJson(body))});
+}
+
+export function capabilityProfileFromEnv(env=process.env){
+  const value=env?.[PROFILE_ENV]??'full';
+  if(value!=='full'&&value!=='compact') throw new Error(`${PROFILE_ENV} must be full or compact`);
+  return value;
+}
+
+function toolNames(snapshot,label){
+  if(!snapshot||typeof snapshot!=='object'||!Array.isArray(snapshot.tools)) throw new Error(`${label} tool surface snapshot invalid`);
+  const names=snapshot.tools.map(tool=>tool?.name);
+  if(names.some(name=>typeof name!=='string'||name.length<1)) throw new Error(`${label} tool surface contains invalid name`);
+  return new Set(names);
+}
+
+export function assertCapabilityClosure({ledger,fullToolSnapshot,compactToolSnapshot}){
+  if(!ledger||ledger.schema!==CAPABILITY_LEDGER_SCHEMA||!Array.isArray(ledger.entries)) throw new Error('capability ledger invalid');
+  const full=toolNames(fullToolSnapshot,'full');
+  const compact=toolNames(compactToolSnapshot,'compact');
+  if(compact.size>COMPACT_TOOL_LIMIT) throw new Error(`compact surface exceeds ${COMPACT_TOOL_LIMIT}-tool limit: ${compact.size}`);
+  for(const capability of ledger.entries){
+    if(!full.has(capability.full_tool)) throw new Error(`capability ${capability.id} full tool missing: ${capability.full_tool}`);
+    if(capability.production&&!capability.host_only){
+      if(!capability.compact_tool||!capability.compact_op) throw new Error(`capability ${capability.id} compact route missing`);
+      if(!compact.has(capability.compact_tool)) throw new Error(`capability ${capability.id} compact tool missing: ${capability.compact_tool}`);
+    }
+  }
+  return true;
+}
+
+const direct=(id,tool,runtime_flag,authority,{mutating=false,receipt_class='direct',production=true,host_only=false}={})=>({id,full_tool:tool,compact_tool:tool,compact_op:'direct',runtime_flag,authority,mutating,receipt_class,production,host_only});
+const gateway=(id,full_tool,compact_tool,compact_op,runtime_flag,authority,{mutating=false,receipt_class='direct',production=true}={})=>({id,full_tool,compact_tool,compact_op,runtime_flag,authority,mutating,receipt_class,production,host_only:false});
+
+export const R36_CAPABILITY_ENTRIES=Object.freeze([
+  direct('evidence.verify','evidence_verify',null,'none',{receipt_class:'verification'}),
+  gateway('machine.list','machine_list','machine_observe','machine_list','DEADBYTE_MACHINE_RUNTIME','none',{receipt_class:'machine'}),
+  gateway('machine.status','machine_status','machine_observe','machine_status','DEADBYTE_MACHINE_RUNTIME','none',{receipt_class:'machine'}),
+  gateway('machine.ping','machine_ping','machine_observe','machine_ping','DEADBYTE_MACHINE_RUNTIME','none',{receipt_class:'machine'}),
+  direct('machine.revoke','machine_revoke','DEADBYTE_MACHINE_RUNTIME','host',{mutating:true,receipt_class:'machine',production:false,host_only:true}),
+
+  gateway('process.start','process_session_start','process_session','start','DEADBYTE_PROCESS_RUNTIME','process',{mutating:true,receipt_class:'process'}),
+  gateway('process.read','process_session_read','process_session','read','DEADBYTE_PROCESS_RUNTIME','process',{receipt_class:'process'}),
+  gateway('process.status','process_session_status','process_session','status','DEADBYTE_PROCESS_RUNTIME','process',{receipt_class:'process'}),
+  gateway('process.list','process_session_list','process_session','list','DEADBYTE_PROCESS_RUNTIME','process',{receipt_class:'process'}),
+  gateway('process.action','process_session_action','process_session','action','DEADBYTE_PROCESS_RUNTIME','process',{mutating:true,receipt_class:'process'}),
+  gateway('process.terminate','process_session_terminate','process_session','terminate','DEADBYTE_PROCESS_RUNTIME','process',{mutating:true,receipt_class:'process'}),
+
+  direct('coding.session_status','coding_session_status','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  direct('coding.tree','coding_tree','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  gateway('coding.stat','coding_stat','coding_inspect','stat','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  gateway('coding.search','coding_search','coding_inspect','search','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  gateway('coding.files_read','coding_files_read','coding_inspect','files_read','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  gateway('semantic.outline','coding_symbol_outline','coding_inspect','symbol_outline','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'semantic'}),
+  gateway('semantic.definition','coding_symbol_definition','coding_inspect','symbol_definition','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'semantic'}),
+  gateway('semantic.references','coding_symbol_references','coding_inspect','symbol_references','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'semantic'}),
+  gateway('semantic.diagnostics','coding_symbol_diagnostics','coding_inspect','symbol_diagnostics','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'semantic'}),
+  gateway('semantic.implementations','coding_symbol_implementations','coding_inspect','symbol_implementations','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'semantic'}),
+  gateway('semantic.rename_preview','coding_symbol_rename_preview','coding_inspect','symbol_rename_preview','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'native_diff'}),
+  direct('semantic.replace','coding_symbol_replace','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'coding'}),
+  direct('coding.file_read','coding_file_read','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'coding'}),
+  direct('coding.file_write','coding_file_write','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'coding'}),
+  direct('coding.text_replace','coding_text_replace','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'coding'}),
+  direct('coding.command_run','coding_command_run','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'coding'}),
+  direct('coding.benchmark_run','coding_benchmark_run','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'coding'}),
+  direct('coding.receipt_verify','coding_receipt_verify','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'verification'}),
+  direct('coding.task_submit','coding_task_submit','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'task'}),
+  direct('coding.task_run','coding_task_run','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'task'}),
+  direct('coding.task_status','coding_task_status','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'task'}),
+  direct('coding.task_events','coding_task_events','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'task'}),
+  direct('coding.task_cancel','coding_task_cancel','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'task'}),
+  direct('coding.task_approve','coding_task_approve','DEADBYTE_CODING_RUNTIME','coding',{mutating:true,receipt_class:'task'}),
+  direct('coding.task_verify','coding_task_verify','DEADBYTE_CODING_RUNTIME','coding',{receipt_class:'verification'}),
+
+  gateway('machine_fs.stat','machine_fs_stat','machine_fs','stat','DEADBYTE_MACHINE_FS_RUNTIME','coding',{receipt_class:'machine_fs'}),
+  gateway('machine_fs.list','machine_fs_list','machine_fs','list','DEADBYTE_MACHINE_FS_RUNTIME','coding',{receipt_class:'machine_fs'}),
+  gateway('machine_fs.read','machine_fs_read','machine_fs','read','DEADBYTE_MACHINE_FS_RUNTIME','coding',{receipt_class:'machine_fs'}),
+  gateway('machine_fs.write','machine_fs_write','machine_fs','write','DEADBYTE_MACHINE_FS_RUNTIME','coding',{mutating:true,receipt_class:'machine_fs'}),
+  gateway('machine_fs.edit_exact','machine_fs_edit_exact','machine_fs','edit_exact','DEADBYTE_MACHINE_FS_RUNTIME','coding',{mutating:true,receipt_class:'machine_fs'}),
+  gateway('machine_fs.mkdir','machine_fs_mkdir','machine_fs','mkdir','DEADBYTE_MACHINE_FS_RUNTIME','coding',{mutating:true,receipt_class:'machine_fs'}),
+  gateway('machine_fs.move','machine_fs_move','machine_fs','move','DEADBYTE_MACHINE_FS_RUNTIME','coding',{mutating:true,receipt_class:'machine_fs'}),
+  gateway('machine_fs.delete','machine_fs_delete','machine_fs','delete','DEADBYTE_MACHINE_FS_RUNTIME','coding',{mutating:true,receipt_class:'machine_fs'}),
+
+  gateway('observation.search_start','machine_search_start','machine_observe','search_start','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+  gateway('observation.search_page','machine_search_page','machine_observe','search_page','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+  gateway('observation.search_status','machine_search_status','machine_observe','search_status','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+  gateway('observation.search_cancel','machine_search_cancel','machine_observe','search_cancel','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+  gateway('observation.process_list','machine_process_list','machine_observe','process_list','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+  gateway('observation.system_status','machine_system_status','machine_observe','system_status','DEADBYTE_OBSERVATION_RUNTIME','none',{receipt_class:'observation'}),
+
+  direct('autonomous.session_status','autonomous_session_status','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'autonomous'}),
+  direct('native_diff.preview','native_diff_preview','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'native_diff'}),
+  direct('native_diff.apply','native_diff_apply','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'native_diff'}),
+  direct('native_diff.verify','native_diff_verify','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'verification'}),
+  direct('autonomous.goal_submit','autonomous_goal_submit','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'autonomous'}),
+  direct('autonomous.goal_run','autonomous_goal_run','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'autonomous'}),
+  direct('autonomous.goal_status','autonomous_goal_status','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'autonomous'}),
+  direct('autonomous.goal_events','autonomous_goal_events','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'autonomous'}),
+  direct('autonomous.goal_cancel','autonomous_goal_cancel','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'autonomous'}),
+  direct('autonomous.goal_approve','autonomous_goal_approve','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'autonomous'}),
+  direct('autonomous.goal_verify','autonomous_goal_verify','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{receipt_class:'verification'}),
+  direct('autonomous.release_gate','autonomous_release_gate','DEADBYTE_AUTONOMOUS_RUNTIME','autonomous',{mutating:true,receipt_class:'release'}),
+
+  direct('host.file_read','host_file_read','DEADBYTE_PRIVILEGED_POLICY','host',{receipt_class:'host',production:false,host_only:true}),
+  direct('host.file_write','host_file_write','DEADBYTE_PRIVILEGED_POLICY','host',{mutating:true,receipt_class:'host',production:false,host_only:true}),
+  direct('host.exec','host_exec','DEADBYTE_PRIVILEGED_POLICY','host',{mutating:true,receipt_class:'host',production:false,host_only:true})
+]);
+export const R36_CAPABILITY_LEDGER=createCapabilityLedger(R36_CAPABILITY_ENTRIES);
+
+export const CAPABILITY_PROFILE_ENV=PROFILE_ENV;
+export const COMPACT_SURFACE_TOOL_LIMIT=COMPACT_TOOL_LIMIT;

package/src/coding-mcp-tools.mjs

@@ -4,7 +4,8 @@ import {
   codingBenchmarkRunOutputSchema, codingCommandRunOutputSchema,
   codingFileReadOutputSchema, codingFilesReadOutputSchema, codingFileWriteOutputSchema,
   codingReceiptVerifyOutputSchema, codingSearchOutputSchema, codingSessionStatusOutputSchema, codingStatOutputSchema,
-  codingSymbolOutlineOutputSchema, codingSymbolDefinitionOutputSchema, codingSymbolReferencesOutputSchema, codingSymbolReplaceOutputSchema,
+  codingSymbolOutlineOutputSchema, codingSymbolDefinitionOutputSchema, codingSymbolReferencesOutputSchema,
+  codingSymbolDiagnosticsOutputSchema, codingSymbolImplementationsOutputSchema, codingSymbolRenamePreviewOutputSchema, codingSymbolReplaceOutputSchema,
   codingTaskApproveOutputSchema, codingTaskCancelOutputSchema,
   codingTaskEventsOutputSchema, codingTaskRunOutputSchema,
   codingTaskStatusOutputSchema, codingTaskSubmitOutputSchema,
@@ -67,13 +68,16 @@ export function registerCodingTools(server, { codingRuntime, taskRuntime, semant
   }, async ({ root_id, path, hash }) => { try { return result(codingStatOutputSchema, await codingRuntime.stat({ rootId: root_id, relativePath: path, hash })); } catch (error) { return fail(codingStatOutputSchema, error); } });
 
   server.registerTool('coding_search', {
-    description: 'Deterministic literal content search using the existing coding tree/read authority.',
+    description: 'Deterministic bounded content/path search with literal or regex mode, signed cursor paging, and observed file identities.',
     inputSchema: z.strictObject({ root_id: rootId, path: relPath.default('.'), pattern: z.string().min(1).max(256),
-      mode: z.literal('literal').default('literal'), case_sensitive: z.boolean().default(false),
-      max_results: z.number().int().min(1).max(1000).default(200), max_file_bytes: z.number().int().min(1).max(4194304).default(262144) }),
+      target: z.enum(['content','path']).default('content'), mode: z.enum(['literal','regex']).default('literal'), case_sensitive: z.boolean().default(false),
+      max_results: z.number().int().min(1).max(1000).default(200), max_file_bytes: z.number().int().min(1).max(4194304).default(262144),
+      max_scan_bytes: z.number().int().min(1).max(67108864).default(4194304), page_size: z.number().int().min(1).max(500).default(100),
+      cursor: z.string().max(8192).nullable().default(null) }),
     outputSchema: codingSearchOutputSchema
-  }, async ({ root_id, path, pattern, mode, case_sensitive, max_results, max_file_bytes }) => {
-    try { return result(codingSearchOutputSchema, await codingRuntime.search({ rootId: root_id, path, pattern, mode, caseSensitive: case_sensitive, maxResults: max_results, maxFileBytes: max_file_bytes })); }
+  }, async ({ root_id, path, pattern, target, mode, case_sensitive, max_results, max_file_bytes, max_scan_bytes, page_size, cursor }) => {
+    try { return result(codingSearchOutputSchema, await codingRuntime.search({ rootId: root_id, path, pattern, target, mode, caseSensitive: case_sensitive,
+      maxResults: max_results, maxFileBytes: max_file_bytes, maxScanBytes: max_scan_bytes, pageSize: page_size, cursor })); }
     catch (error) { return fail(codingSearchOutputSchema, error); }
   });
 
@@ -95,6 +99,24 @@ export function registerCodingTools(server, { codingRuntime, taskRuntime, semant
     outputSchema: codingSymbolReferencesOutputSchema
   }, async ({ root_id, path, line, column, max_results }) => { try { return result(codingSymbolReferencesOutputSchema, await semanticRuntime.references({ rootId: root_id, relativePath: path, line, column, maxResults: max_results })); } catch (error) { return fail(codingSymbolReferencesOutputSchema, error); } });
 
+  server.registerTool('coding_symbol_diagnostics', {
+    description: 'Return bounded normalized semantic diagnostics with target and result identities.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath, max_results: z.number().int().min(1).max(500).default(200) }),
+    outputSchema: codingSymbolDiagnosticsOutputSchema
+  }, async ({ root_id, path, max_results }) => { try { const value=await semanticRuntime.diagnostics({ rootId:root_id, relativePath:path, maxResults:max_results }); return result(codingSymbolDiagnosticsOutputSchema,value,value.status==='failed'); } catch(error){ return fail(codingSymbolDiagnosticsOutputSchema,error); } });
+
+  server.registerTool('coding_symbol_implementations', {
+    description: 'Resolve bounded semantic implementations at a zero-based line/column. Unsupported backends report an explicit typed status.',
+    inputSchema: z.strictObject({ root_id:rootId, path:relPath, line:z.number().int().min(0), column:z.number().int().min(0), max_results:z.number().int().min(1).max(500).default(200) }),
+    outputSchema: codingSymbolImplementationsOutputSchema
+  }, async ({ root_id, path, line, column, max_results }) => { try { const value=await semanticRuntime.implementations({rootId:root_id,relativePath:path,line,column,maxResults:max_results}); return result(codingSymbolImplementationsOutputSchema,value,false); } catch(error){ return fail(codingSymbolImplementationsOutputSchema,error); } });
+
+  server.registerTool('coding_symbol_rename_preview', {
+    description: 'Preview one semantic rename as a content-addressed Native Diff. This tool never mutates source bytes.',
+    inputSchema: z.strictObject({ root_id:rootId, path:relPath, line:z.number().int().min(0), column:z.number().int().min(0), new_name:z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/) }),
+    outputSchema: codingSymbolRenamePreviewOutputSchema
+  }, async ({ root_id, path, line, column, new_name }) => { try { const value=await semanticRuntime.renamePreview({rootId:root_id,relativePath:path,line,column,newName:new_name}); return result(codingSymbolRenamePreviewOutputSchema,value,false); } catch(error){ return fail(codingSymbolRenamePreviewOutputSchema,error); } });
+
   server.registerTool('coding_symbol_replace', {
     description: 'Replace one current JS/TS symbol body by symbol_id under exact file SHA-256 precondition. The commit reuses the coding plane signed surgical-edit receipt path.',
     inputSchema: z.strictObject({ root_id: rootId, path: relPath, symbol_id: hex64, new_body: z.string().max(524288), expected_sha256: hex64 }),
@@ -102,21 +124,13 @@ export function registerCodingTools(server, { codingRuntime, taskRuntime, semant
   }, async ({ root_id, path, symbol_id, new_body, expected_sha256 }) => { try { return result(codingSymbolReplaceOutputSchema, await semanticRuntime.replaceSymbol({ rootId: root_id, relativePath: path, symbolId: symbol_id, newBody: new_body, expectedSha256: expected_sha256 })); } catch (error) { return fail(codingSymbolReplaceOutputSchema, error); } });
 
   server.registerTool('coding_files_read', {
-    description: 'Read up to 32 bounded files in one request using the same coding-policy lease and deny-path checks as coding_file_read.',
+    description: 'Read up to 32 bounded files under one coding lease and return an aggregate observation identity over ordered file metadata.',
     inputSchema: z.strictObject({ root_id: rootId, files: z.array(z.strictObject({ path: relPath, encoding: z.enum(['utf8','base64']).default('utf8') })).min(1).max(32),
       max_total_bytes: z.number().int().min(1).max(2097152).default(1048576) }),
     outputSchema: codingFilesReadOutputSchema
   }, async ({ root_id, files, max_total_bytes }) => {
-    try {
-      const values=[]; let total=0;
-      for(const item of files){
-        const read=await codingRuntime.fileRead({rootId:root_id,relativePath:item.path,encoding:item.encoding});
-        total+=read.bytes;
-        if(total>max_total_bytes) throw new Error(`coding multi-read exceeds ${max_total_bytes} byte total limit`);
-        values.push({path:item.path,encoding:item.encoding,bytes:read.bytes,sha256:read.sha256,content:read.content});
-      }
-      return result(codingFilesReadOutputSchema,{status:'ok',root_id,total_bytes:total,files:values});
-    } catch(error){ return fail(codingFilesReadOutputSchema,error); }
+    try { return result(codingFilesReadOutputSchema,await codingRuntime.filesRead({rootId:root_id,files,maxTotalBytes:max_total_bytes})); }
+    catch(error){ return fail(codingFilesReadOutputSchema,error); }
   });
 
   server.registerTool('coding_file_read', {

package/src/coding-output-contracts.mjs

@@ -70,18 +70,25 @@ export const codingTreeOutputSchema = statusContract({
 export const codingStatOutputSchema = statusContract({
   statuses: ['ok', 'failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
-    type: z.enum(['file','directory','symlink','other']).optional(), bytes: z.number().int().min(0).optional(),
-    mtime_utc: z.string().min(1).optional(), sha256: hex64.nullable().optional() },
-  successStatuses: ['ok'], successRequired: ['root_id','path','type','bytes','mtime_utc','sha256']
+    normalized_path: z.string().min(1).max(512).optional(), type: z.enum(['file','directory','symlink','other']).optional(),
+    bytes: z.number().int().min(0).optional(), mtime_utc: z.string().min(1).optional(), sha256: hex64.nullable().optional(),
+    reparse_state: z.enum(['none','symlink']).optional(), object_identity_sha256: hex64.optional(),
+    policy_root_id: z.string().min(1).max(64).optional(), observation_sha256: hex64.optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','normalized_path','type','bytes','mtime_utc','sha256','reparse_state','object_identity_sha256','policy_root_id','observation_sha256']
 });
 export const codingSearchOutputSchema = statusContract({
   statuses: ['ok', 'failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
-    pattern: z.string().min(1).max(256).optional(), mode: z.literal('literal').optional(), case_sensitive: z.boolean().optional(),
-    matches: z.array(z.strictObject({ path: z.string().min(1).max(512), line: z.number().int().min(1),
-      column: z.number().int().min(1), preview: z.string().max(512) })).max(1000).optional(),
-    files_scanned: z.number().int().min(0).optional(), bytes_scanned: z.number().int().min(0).optional(), truncated: z.boolean().optional() },
-  successStatuses: ['ok'], successRequired: ['root_id','path','pattern','mode','case_sensitive','matches','files_scanned','bytes_scanned','truncated']
+    pattern: z.string().min(1).max(256).optional(), target: z.enum(['content','path']).optional(),
+    mode: z.enum(['literal','regex']).optional(), case_sensitive: z.boolean().optional(),
+    matches: z.array(z.strictObject({ path: z.string().min(1).max(512), line: z.number().int().min(1).nullable(),
+      column: z.number().int().min(1).nullable(), preview: z.string().max(512), file_sha256: hex64.nullable() })).max(500).optional(),
+    files_scanned: z.number().int().min(0).optional(), bytes_scanned: z.number().int().min(0).optional(),
+    binary_files_skipped: z.number().int().min(0).optional(), truncated: z.boolean().optional(),
+    truncation_reason: z.enum(['tree_limit','scan_byte_limit','max_results']).nullable().optional(),
+    query_sha256: hex64.optional(), snapshot_sha256: hex64.optional(), page_sha256: hex64.optional(),
+    next_cursor: z.string().max(8192).nullable().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','pattern','target','mode','case_sensitive','matches','files_scanned','bytes_scanned','binary_files_skipped','truncated','truncation_reason','query_sha256','snapshot_sha256','page_sha256','next_cursor']
 });
 const semanticLocationSchema = z.strictObject({
   path: z.string().min(1).max(512), name: z.string().max(256), kind: z.string().min(1).max(64),
@@ -113,6 +120,36 @@ export const codingSymbolReferencesOutputSchema = statusContract({
     locations: z.array(semanticLocationSchema).max(500).optional(), truncated: z.boolean().optional() },
   successStatuses: ['ok'], successRequired: ['root_id','path','line','column','engine','locations','truncated']
 });
+export const codingSymbolDiagnosticsOutputSchema = z.strictObject({
+  status:z.enum(['ok','unsupported','failed']), error:z.string().optional(), capability:z.string().max(64).optional(),
+  root_id:z.string().min(1).max(64).optional(), path:z.string().min(1).max(512).optional(), file_sha256:hex64.optional(),
+  engine:z.string().min(1).max(128).optional(), diagnostics:z.array(z.strictObject({message:z.string().max(4096),code:z.string().max(256),severity:z.string().min(1).max(64),location:semanticLocationSchema.optional()})).max(500).optional(),
+  truncated:z.boolean().optional(), result_sha256:hex64.optional()
+}).superRefine((value,ctx)=>{
+  if(value.status==='failed'){requireFields(value,ctx,['error']);return;}
+  if(value.status==='unsupported'){requireFields(value,ctx,['capability','engine']);return;}
+  requireFields(value,ctx,['root_id','path','file_sha256','engine','diagnostics','truncated','result_sha256']);
+});
+export const codingSymbolImplementationsOutputSchema = z.strictObject({
+  status:z.enum(['ok','unsupported','failed']), error:z.string().optional(), capability:z.string().max(64).optional(),
+  root_id:z.string().min(1).max(64).optional(), path:z.string().min(1).max(512).optional(), line:z.number().int().min(0).optional(), column:z.number().int().min(0).optional(),
+  file_sha256:hex64.optional(), engine:z.string().min(1).max(128).optional(), locations:z.array(semanticLocationSchema).max(500).optional(),
+  truncated:z.boolean().optional(), result_sha256:hex64.optional()
+}).superRefine((value,ctx)=>{
+  if(value.status==='failed'){requireFields(value,ctx,['error']);return;}
+  if(value.status==='unsupported'){requireFields(value,ctx,['capability','engine']);return;}
+  requireFields(value,ctx,['root_id','path','line','column','file_sha256','engine','locations','truncated','result_sha256']);
+});
+export const codingSymbolRenamePreviewOutputSchema = z.strictObject({
+  status:z.enum(['ready','unsupported','failed']), error:z.string().optional(), capability:z.string().max(64).optional(), engine:z.string().min(1).max(128).optional(),
+  diff_id:hex64.optional(), affected_files:z.number().int().min(1).max(32).optional(), edit_count:z.number().int().min(1).optional(), backend:z.string().min(1).max(128).optional(),
+  preimages:z.array(z.strictObject({path:z.string().min(1).max(512),sha256:hex64})).max(32).optional()
+}).superRefine((value,ctx)=>{
+  if(value.status==='failed'){requireFields(value,ctx,['error']);return;}
+  if(value.status==='unsupported'){requireFields(value,ctx,['capability','engine']);return;}
+  requireFields(value,ctx,['diff_id','affected_files','edit_count','backend','preimages']);
+});
+
 export const codingSymbolReplaceOutputSchema = statusContract({
   statuses: ['committed','failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), previous_sha256: hex64.optional(),
@@ -125,8 +162,9 @@ export const codingSymbolReplaceOutputSchema = statusContract({
 export const codingFilesReadOutputSchema = statusContract({
   statuses: ['ok','failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), total_bytes: z.number().int().min(0).optional(),
-    files: z.array(z.strictObject({ path: z.string().min(1).max(512), encoding: z.enum(['utf8','base64']), bytes: z.number().int().min(0), sha256: hex64, content: z.string() })).max(32).optional() },
-  successStatuses: ['ok'], successRequired: ['root_id','total_bytes','files']
+    files: z.array(z.strictObject({ path: z.string().min(1).max(512), encoding: z.enum(['utf8','base64']), bytes: z.number().int().min(0), sha256: hex64, content: z.string() })).max(32).optional(),
+    observation_sha256: hex64.optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','total_bytes','files','observation_sha256']
 });
 export const codingFileReadOutputSchema = statusContract({
   statuses: ['ok', 'failed'],

package/src/coding-plane.mjs

@@ -9,6 +9,7 @@ import { decodeUtf8Strict } from './text-policy.mjs';
 import { isInside, validatePortableRelativePath } from './path-policy.mjs';
 import { loadPrivateSigningKey, loadPublicVerifyKey } from './trust.mjs';
 import { createCodingSearch } from './coding-search.mjs';
+import { createSearchCursorCodec } from './search-cursor.mjs';
 
 export const CODING_POLICY_SCHEMA = 'deadbyte.coding-policy.v1';
 export const CODING_LEASE_SCHEMA = 'deadbyte.coding-lease.v1';
@@ -613,18 +614,52 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
   async function statPath({ rootId, relativePath = '.', hash = false }) {
     const lease = await assertCodingArmed(policy, rootId);
     const root = getRoot(policy, rootId, 'read');
-    let resolved = root.real_path;
+    let lexical = root.real_path;
     let reported = '.';
     if (relativePath !== '.') {
-      const found = await resolveCodingExisting(policy, lease, rootId, relativePath, 'read');
-      resolved = found.resolved;
+      validatePortableRelativePath(relativePath);
+      if (!lease.root_ids.includes(rootId)) throw new Error(`coding root '${rootId}' is outside active lease`);
+      assertNotDenied(root, relativePath);
+      lexical = path.resolve(root.real_path, relativePath);
+      if (!isInside(root.real_path, lexical)) throw new Error('coding stat path escapes allowed root');
       reported = relativePath.replaceAll('\\', '/');
     }
-    const info = await lstat(resolved);
+    const info = await lstat(lexical);
     const type = info.isFile() ? 'file' : info.isDirectory() ? 'directory' : info.isSymbolicLink() ? 'symlink' : 'other';
-    const digest = hash && type === 'file' ? await sha256File(resolved) : null;
-    return { status: 'ok', root_id: rootId, path: reported, type, bytes: type === 'file' ? info.size : 0,
-      mtime_utc: info.mtime.toISOString(), sha256: digest };
+    const reparseState = info.isSymbolicLink() ? 'symlink' : 'none';
+    if (type !== 'symlink') {
+      const resolved = await realpath(lexical);
+      if (!isInside(root.real_path, resolved) && resolved !== root.real_path) throw new Error('coding stat path resolves outside allowed root');
+    }
+    const contentSha = type === 'file' ? await sha256File(lexical) : null;
+    const objectIdentitySha = sha256Object({
+      schema:'deadbyte.coding-object-identity.v1',type,bytes:type==='file'?info.size:0,
+      content_sha256:contentSha,device:Number(info.dev),inode:Number(info.ino),reparse_state:reparseState
+    });
+    const result = {
+      status:'ok',root_id:rootId,path:reported,normalized_path:reported,type,
+      bytes:type==='file'?info.size:0,mtime_utc:info.mtime.toISOString(),
+      sha256:hash&&type==='file'?contentSha:null,reparse_state:reparseState,
+      object_identity_sha256:objectIdentitySha,policy_root_id:rootId
+    };
+    return {...result,observation_sha256:sha256Object({schema:'deadbyte.coding-stat-observation.v1',...result})};
+  }
+
+  async function filesRead({ rootId, files, maxTotalBytes = 1048576 }) {
+    if (!Array.isArray(files) || files.length < 1 || files.length > 32) throw new Error('coding multi-read requires 1-32 files');
+    if (!Number.isInteger(maxTotalBytes) || maxTotalBytes < 1 || maxTotalBytes > 2097152) throw new Error('coding multi-read max_total_bytes must be in [1, 2097152]');
+    const values=[]; let total=0;
+    for(const item of files){
+      if(!item||typeof item.path!=='string'||!['utf8','base64'].includes(item.encoding??'utf8')) throw new Error('coding multi-read file entry invalid');
+      const encoding=item.encoding??'utf8';
+      const read=await fileRead({rootId,relativePath:item.path,encoding});
+      total+=read.bytes;
+      if(total>maxTotalBytes) throw new Error(`coding multi-read exceeds ${maxTotalBytes} byte total limit`);
+      values.push({path:item.path,encoding,bytes:read.bytes,sha256:read.sha256,content:read.content});
+    }
+    const identity=values.map(item=>({path:item.path,encoding:item.encoding,bytes:item.bytes,sha256:item.sha256}));
+    return {status:'ok',root_id:rootId,total_bytes:total,files:values,
+      observation_sha256:sha256Object({schema:'deadbyte.coding-files-read-observation.v1',root_id:rootId,files:identity})};
   }
 
   async function fileState({ rootId, relativePath }) {
@@ -651,7 +686,8 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
     return verifyCodingReceiptFile(policy, verifyKeyPath, receiptId);
   }
 
-  const search = createCodingSearch({ tree, fileRead });
-  return Object.freeze({ policy, sessionStatus, tree, stat: statPath, search, fileRead, fileWrite, fileDelete, textReplace, commandRun, benchmarkRun, receiptVerify,
+  const cursorCodec = createSearchCursorCodec({ signingKeyPath, verifyKeyPath });
+  const search = createCodingSearch({ tree, fileRead, cursorCodec });
+  return Object.freeze({ policy, sessionStatus, tree, stat: statPath, search, filesRead, fileRead, fileWrite, fileDelete, textReplace, commandRun, benchmarkRun, receiptVerify,
     fileState, verifyReceiptById: receiptVerify, verifyReceiptDetailed, requestSha });
 }

package/src/coding-search.mjs

@@ -1,55 +1,138 @@
-export function createCodingSearch({ tree, fileRead }) {
-  if (typeof tree !== 'function' || typeof fileRead !== 'function') {
-    throw new Error('coding search requires tree and fileRead');
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+import { decodeUtf8Strict } from './text-policy.mjs';
+
+const sha256Object=value=>createHash('sha256').update(canonicalJson(value),'utf8').digest('hex');
+const sha256Bytes=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+function validateInt(value,name,min,max){
+  if(!Number.isInteger(value)||value<min||value>max) throw new Error(`${name} must be in [${min}, ${max}]`);
+}
+function compileMatcher({pattern,mode,caseSensitive}){
+  if(typeof pattern!=='string'||pattern.length<1||pattern.length>256) throw new Error('coding search pattern must be 1-256 characters');
+  if(mode==='literal'){
+    const needle=caseSensitive?pattern:pattern.toLowerCase();
+    return {
+      all(text){
+        const haystack=caseSensitive?text:text.toLowerCase();
+        const out=[]; let from=0;
+        while(from<=haystack.length){
+          const index=haystack.indexOf(needle,from);
+          if(index<0) break;
+          out.push({index,length:Math.max(1,pattern.length)});
+          from=index+Math.max(1,pattern.length);
+        }
+        return out;
+      },
+      path(value){return (caseSensitive?value:value.toLowerCase()).includes(needle);}
+    };
+  }
+  if(mode!=='regex') throw new Error('coding search mode must be literal or regex');
+  let regex;
+  try{regex=new RegExp(pattern,caseSensitive?'gu':'giu');}
+  catch(error){throw new Error(`coding search regex invalid: ${error.message}`);}
+  return {
+    all(text){
+      const out=[]; regex.lastIndex=0; let match;
+      while((match=regex.exec(text))!==null){
+        out.push({index:match.index,length:Math.max(1,match[0].length)});
+        if(match[0].length===0) regex.lastIndex+=1;
+      }
+      return out;
+    },
+    path(value){regex.lastIndex=0;return regex.test(value);}
+  };
+}
+function lineColumn(text,index){
+  let line=1,column=1;
+  for(let i=0;i<index;i+=1){if(text.charCodeAt(i)===10){line+=1;column=1;}else column+=1;}
+  return {line,column};
+}
+function preview(text,index,length){
+  const start=Math.max(0,index-48); const end=Math.min(text.length,index+Math.max(length,1)+112);
+  return text.slice(start,end);
+}
+function normalizeQuery({rootId,path,target,mode,pattern,caseSensitive,maxResults,maxFileBytes,maxScanBytes,pageSize}){
+  return {
+    schema:'deadbyte.coding-search-query.v2',root_id:rootId,path,target,mode,pattern,
+    case_sensitive:caseSensitive,max_results:maxResults,max_file_bytes:maxFileBytes,
+    max_scan_bytes:maxScanBytes,page_size:pageSize
+  };
+}
+
+export function createCodingSearch({tree,fileRead,cursorCodec}){
+  if(typeof tree!=='function'||typeof fileRead!=='function'||!cursorCodec||typeof cursorCodec.encode!=='function'||typeof cursorCodec.decode!=='function'){
+    throw new Error('coding search requires tree, fileRead, and cursorCodec');
   }
   return async function search({
-    rootId, path = '.', pattern, mode = 'literal', caseSensitive = false,
-    maxResults = 200, maxFileBytes = 262144
-  }) {
-    if (mode !== 'literal') throw new Error('coding search mode must be literal');
-    if (typeof pattern !== 'string' || pattern.length < 1 || pattern.length > 256) {
-      throw new Error('coding search pattern must be 1-256 characters');
-    }
-    if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 1000) {
-      throw new Error('max_results must be in [1, 1000]');
-    }
-    if (!Number.isInteger(maxFileBytes) || maxFileBytes < 1 || maxFileBytes > 4 * 1024 * 1024) {
-      throw new Error('max_file_bytes out of range');
+    rootId,path='.',pattern,target='content',mode='literal',caseSensitive=false,
+    maxResults=200,maxFileBytes=262144,maxScanBytes=4*1024*1024,pageSize=100,cursor=null
+  }){
+    if(!['content','path'].includes(target)) throw new Error('coding search target must be content or path');
+    validateInt(maxResults,'max_results',1,1000);
+    validateInt(maxFileBytes,'max_file_bytes',1,4*1024*1024);
+    validateInt(maxScanBytes,'max_scan_bytes',1,64*1024*1024);
+    validateInt(pageSize,'page_size',1,500);
+    const matcher=compileMatcher({pattern,mode,caseSensitive});
+    const query=normalizeQuery({rootId,path,target,mode,pattern,caseSensitive,maxResults,maxFileBytes,maxScanBytes,pageSize});
+    const querySha=sha256Object(query);
+    let decodedCursor=null;
+    if(cursor!==null){
+      decodedCursor=await cursorCodec.decode(cursor);
+      if(decodedCursor.query_sha256!==querySha) throw new Error('coding search cursor query mismatch');
     }
-    const listed = await tree({ rootId, path, maxDepth: 12, maxEntries: 2000 });
-    const files = listed.entries
-      .filter(entry => entry.type === 'file' && entry.bytes <= maxFileBytes)
-      .map(entry => entry.path)
-      .sort((a, b) => a.localeCompare(b));
-    const needle = caseSensitive ? pattern : pattern.toLowerCase();
-    const matches = [];
-    let filesScanned = 0;
-    let bytesScanned = 0;
-    for (const relativePath of files) {
-      const item = await fileRead({ rootId, relativePath, encoding: 'utf8' }).catch(() => null);
-      if (!item) continue;
-      filesScanned += 1;
-      bytesScanned += item.bytes;
-      const haystack = caseSensitive ? item.content : item.content.toLowerCase();
-      const index = haystack.indexOf(needle);
-      if (index < 0) continue;
-      const before = item.content.slice(0, index);
-      const line = before.split('\n').length;
-      const lastNewline = before.lastIndexOf('\n');
-      const column = index - lastNewline;
-      matches.push({
-        path: relativePath,
-        line,
-        column,
-        preview: item.content.slice(index, index + Math.min(160, pattern.length + 120))
-      });
-      if (matches.length >= maxResults) break;
+
+    const listed=await tree({rootId,path,maxDepth:12,maxEntries:2000});
+    const entries=listed.entries.filter(entry=>entry.type==='file').sort((a,b)=>a.path.localeCompare(b.path,'en'));
+    const matches=[]; const snapshotEntries=[];
+    let filesScanned=0,bytesScanned=0,binaryFilesSkipped=0;
+    let truncated=listed.truncated===true;
+    let truncationReason=listed.truncated===true?'tree_limit':null;
+
+    if(target==='path'){
+      for(const entry of entries){
+        snapshotEntries.push({path:entry.path,bytes:entry.bytes,type:'file'});
+        if(matcher.path(entry.path)){
+          matches.push({path:entry.path,line:null,column:null,preview:entry.path,file_sha256:null});
+          if(matches.length>=maxResults){truncated=true;truncationReason='max_results';break;}
+        }
+      }
+    } else {
+      for(const entry of entries){
+        if(entry.bytes>maxFileBytes) continue;
+        if(bytesScanned+entry.bytes>maxScanBytes){truncated=true;truncationReason='scan_byte_limit';break;}
+        let item;
+        try{item=await fileRead({rootId,relativePath:entry.path,encoding:'base64'});}catch{continue;}
+        const raw=Buffer.from(item.content,'base64');
+        filesScanned+=1; bytesScanned+=item.bytes;
+        const fileSha=item.sha256??sha256Bytes(raw);
+        snapshotEntries.push({path:entry.path,bytes:item.bytes,sha256:fileSha});
+        let text;
+        try{text=decodeUtf8Strict(raw);}catch{binaryFilesSkipped+=1;continue;}
+        const found=matcher.all(text);
+        for(const hit of found){
+          const lc=lineColumn(text,hit.index);
+          matches.push({path:entry.path,line:lc.line,column:lc.column,preview:preview(text,hit.index,hit.length),file_sha256:fileSha});
+          if(matches.length>=maxResults){truncated=true;truncationReason='max_results';break;}
+        }
+        if(matches.length>=maxResults) break;
+      }
     }
+
+    const snapshotSha=sha256Object({schema:'deadbyte.coding-search-snapshot.v2',query_sha256:querySha,entries:snapshotEntries});
+    if(decodedCursor&&decodedCursor.snapshot_sha256!==snapshotSha) throw new Error('coding search cursor stale snapshot mismatch');
+    const offset=decodedCursor?.offset??0;
+    if(offset>matches.length) throw new Error('coding search cursor offset exceeds retained results');
+    const pageMatches=matches.slice(offset,offset+pageSize);
+    const nextOffset=offset+pageMatches.length;
+    const hasMore=nextOffset<matches.length;
+    const nextCursor=hasMore?await cursorCodec.encode({query_sha256:querySha,snapshot_sha256:snapshotSha,offset:nextOffset}):null;
+    const pageSha=sha256Object({schema:'deadbyte.coding-search-page.v2',query_sha256:querySha,snapshot_sha256:snapshotSha,offset,matches:pageMatches});
     return {
-      status: 'ok', root_id: rootId, path, pattern, mode,
-      case_sensitive: caseSensitive, matches,
-      files_scanned: filesScanned, bytes_scanned: bytesScanned,
-      truncated: matches.length >= maxResults || listed.truncated
+      status:'ok',root_id:rootId,path,pattern,target,mode,case_sensitive:caseSensitive,
+      matches:pageMatches,files_scanned:filesScanned,bytes_scanned:bytesScanned,binary_files_skipped:binaryFilesSkipped,
+      truncated:truncated||hasMore,truncation_reason:truncationReason,query_sha256:querySha,snapshot_sha256:snapshotSha,
+      page_sha256:pageSha,next_cursor:nextCursor
     };
   };
 }