deadbyte-mcp 0.8.10 → 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

@@ -2,8 +2,10 @@ import * as z from 'zod/v4';
 import { CODING_TASK_ID_RE, CODING_STEP_ID_RE } from './coding-task-runtime.mjs';
 import {
   codingBenchmarkRunOutputSchema, codingCommandRunOutputSchema,
-  codingFileReadOutputSchema, codingFileWriteOutputSchema,
+  codingFileReadOutputSchema, codingFilesReadOutputSchema, codingFileWriteOutputSchema,
   codingReceiptVerifyOutputSchema, codingSearchOutputSchema, codingSessionStatusOutputSchema, codingStatOutputSchema,
+  codingSymbolOutlineOutputSchema, codingSymbolDefinitionOutputSchema, codingSymbolReferencesOutputSchema,
+  codingSymbolDiagnosticsOutputSchema, codingSymbolImplementationsOutputSchema, codingSymbolRenamePreviewOutputSchema, codingSymbolReplaceOutputSchema,
   codingTaskApproveOutputSchema, codingTaskCancelOutputSchema,
   codingTaskEventsOutputSchema, codingTaskRunOutputSchema,
   codingTaskStatusOutputSchema, codingTaskSubmitOutputSchema,
@@ -45,8 +47,8 @@ const taskStep = z.union([
 
 function result(schema, value, isError = false) { return codingStructuredResult(schema, value, isError); }
 function fail(schema, error) { return result(schema, { status: 'failed', error: String(error) }, true); }
-export function registerCodingTools(server, { codingRuntime, taskRuntime }) {
-  if (!codingRuntime || !taskRuntime) throw new Error('coding tool registration requires runtimes');
+export function registerCodingTools(server, { codingRuntime, taskRuntime, semanticRuntime }) {
+  if (!codingRuntime || !taskRuntime || !semanticRuntime) throw new Error('coding tool registration requires runtimes');
 
   server.registerTool('coding_session_status', {
     description: 'Read coding-plane policy/lease status. This never arms or renews authority.',
@@ -66,16 +68,71 @@ export function registerCodingTools(server, { codingRuntime, taskRuntime }) {
   }, 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); }
   });
 
+  server.registerTool('coding_symbol_outline', {
+    description: 'Return a bounded JS/TS symbol outline using the bundled TypeScript language service. Results are rooted in the active coding-policy source tree.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath, max_symbols: z.number().int().min(1).max(500).default(200) }),
+    outputSchema: codingSymbolOutlineOutputSchema
+  }, async ({ root_id, path, max_symbols }) => { try { return result(codingSymbolOutlineOutputSchema, await semanticRuntime.outline({ rootId: root_id, relativePath: path, maxSymbols: max_symbols })); } catch (error) { return fail(codingSymbolOutlineOutputSchema, error); } });
+
+  server.registerTool('coding_symbol_definition', {
+    description: 'Resolve JS/TS definitions at a zero-based line/column using the bundled TypeScript language service.',
+    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(200).default(50) }),
+    outputSchema: codingSymbolDefinitionOutputSchema
+  }, async ({ root_id, path, line, column, max_results }) => { try { return result(codingSymbolDefinitionOutputSchema, await semanticRuntime.definition({ rootId: root_id, relativePath: path, line, column, maxResults: max_results })); } catch (error) { return fail(codingSymbolDefinitionOutputSchema, error); } });
+
+  server.registerTool('coding_symbol_references', {
+    description: 'Find bounded JS/TS references at a zero-based line/column using the bundled TypeScript language service.',
+    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: 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 }),
+    outputSchema: codingSymbolReplaceOutputSchema
+  }, 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 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 { 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', {
     description: 'Read one bounded file inside an active coding lease.',
     inputSchema: z.strictObject({ root_id: rootId, path: relPath, encoding: z.enum(['utf8','base64']).default('utf8') }), outputSchema: codingFileReadOutputSchema

package/src/coding-output-contracts.mjs

@@ -70,18 +70,101 @@ 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),
+  start_line: z.number().int().min(0), start_column: z.number().int().min(0),
+  end_line: z.number().int().min(0), end_column: z.number().int().min(0)
+});
+const semanticSymbolSchema = semanticLocationSchema.extend({
+  symbol_id: hex64, container_name: z.string().max(256),
+  name_start_line: z.number().int().min(0), name_start_column: z.number().int().min(0)
+});
+export const codingSymbolOutlineOutputSchema = statusContract({
+  statuses: ['ok','failed'],
+  shape: { 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(64).optional(),
+    symbols: z.array(semanticSymbolSchema).max(500).optional(), truncated: z.boolean().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','file_sha256','engine','symbols','truncated']
+});
+export const codingSymbolDefinitionOutputSchema = statusContract({
+  statuses: ['ok','failed'],
+  shape: { 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(), engine: z.string().min(1).max(64).optional(),
+    locations: z.array(semanticLocationSchema).max(200).optional(), truncated: z.boolean().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','line','column','engine','locations','truncated']
+});
+export const codingSymbolReferencesOutputSchema = statusContract({
+  statuses: ['ok','failed'],
+  shape: { 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(), engine: z.string().min(1).max(64).optional(),
+    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(),
+    sha256: hex64.optional(), bytes: z.number().int().min(0).optional(), replacements: z.literal(1).optional(),
+    receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional(),
+    symbol_id: hex64.optional(), symbol_name: z.string().min(1).max(256).optional(), engine: z.string().min(1).max(64).optional() },
+  successStatuses: ['committed'], successRequired: ['root_id','path','previous_sha256','sha256','bytes','replacements','receipt_id','receipt_sha256','request_sha256','symbol_id','symbol_name','engine']
+});
+
+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(),
+    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 });
 }