deadbyte-mcp 0.8.9 → 0.9.0

package/src/autonomous-supervisor-host.mjs

@@ -0,0 +1,70 @@
+import { access } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultPrivateKeyPath, defaultPublicKeyPath } from './trust.mjs';
+import { createCodingRuntime, loadCodingPolicy } from './coding-plane.mjs';
+import { loadAutonomousPolicy } from './autonomous-policy.mjs';
+import { createNativeDiffRuntime } from './native-diff.mjs';
+import { createAutonomousRuntime } from './autonomous-runtime.mjs';
+import { startLocalSupervisorHost } from './autonomous-local-supervisor.mjs';
+
+const packageRoot=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
+const stateRoot=path.resolve(process.env.DEADBYTE_STATE_ROOT||path.join(os.homedir(),'.deadbyte-mcp'));
+const signingKeyPath=process.env.DEADBYTE_SIGNING_KEY||defaultPrivateKeyPath();
+const verifyKeyPath=process.env.DEADBYTE_VERIFY_KEY||defaultPublicKeyPath();
+
+async function policyPath(envName,localName){
+  const explicit=process.env[envName];
+  const candidate=explicit?path.resolve(explicit):path.join(packageRoot,'controller',localName);
+  try { await access(candidate); }
+  catch { throw new Error(`${envName} policy unavailable: ${candidate}`); }
+  return candidate;
+}
+
+const onceMode=process.env.DEADBYTE_SUPERVISOR_ONCE??'0';
+if(!['0','1'].includes(onceMode)) throw new Error('DEADBYTE_SUPERVISOR_ONCE must be 0 or 1');
+const codingPolicyPath=await policyPath('DEADBYTE_CODING_POLICY','deadbyte-coding-policy.json');
+const autonomousPolicyPath=await policyPath('DEADBYTE_AUTONOMOUS_POLICY','deadbyte-autonomous-policy.json');
+const codingPolicy=await loadCodingPolicy(codingPolicyPath);
+const codingRuntime=createCodingRuntime({policy:codingPolicy,signingKeyPath,verifyKeyPath});
+const autonomousPolicy=await loadAutonomousPolicy(autonomousPolicyPath,codingPolicy);
+const nativeDiffRuntime=createNativeDiffRuntime({policy:autonomousPolicy,codingRuntime,signingKeyPath,verifyKeyPath});
+const autonomousRuntime=createAutonomousRuntime({policy:autonomousPolicy,codingRuntime,nativeDiffRuntime,signingKeyPath,verifyKeyPath});
+const markerPath=path.resolve(process.env.DEADBYTE_SUPERVISOR_MARKER||path.join(autonomousPolicy.evidence_dir,'supervisor-owner.json'));
+const host=await startLocalSupervisorHost({runtime:autonomousRuntime,policy:autonomousPolicy,markerPath,
+  idleDelayMs:750,maxCycles:32,continuous:onceMode!=='1'});
+
+const ready={schema:'deadbyte.autonomous-supervisor-host.v1',status:'ready',pid:process.pid,
+  marker_path:markerPath,policy_sha256:autonomousPolicy.policy_sha256,state_root:stateRoot};
+process.stdout.write(`${JSON.stringify(ready)}\n`);
+
+let stopping=false;
+async function stopAndExit(code=0){
+  if(stopping) return;
+  stopping=true;
+  try { await host.stop(); }
+  catch(error){ process.stderr.write(`DEADBYTE supervisor host stop failed: ${String(error)}\n`); code=1; }
+  process.exitCode=code;
+}
+
+if(onceMode==='1') {
+  try { await host.scanNow(); await stopAndExit(0); }
+  catch(error){ process.stderr.write(`DEADBYTE supervisor host one-pass failed: ${String(error)}\n`); await stopAndExit(1); }
+} else {
+  await new Promise(resolve=>{
+    const keepAlive=setInterval(()=>{},60_000);
+    let finishing=false;
+    const finish=(code,error=null)=>{
+      if(finishing) return;
+      finishing=true;
+      clearInterval(keepAlive);
+      if(error) process.stderr.write(`${error?.stack??String(error)}\n`);
+      void stopAndExit(code).finally(resolve);
+    };
+    process.once('SIGINT',()=>finish(0));
+    process.once('SIGTERM',()=>finish(0));
+    process.once('uncaughtException',error=>finish(1,error));
+    process.once('unhandledRejection',error=>finish(1,error));
+  });
+}

package/src/autonomous-supervisor.mjs

@@ -2,7 +2,7 @@ import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 
 const GOAL_ID_RE = /^[0-9a-f]{64}$/;
-const TERMINAL = new Set(['succeeded', 'cancelled', 'paused']);
+const TERMINAL = new Set(['succeeded', 'cancelled']);
 
 function delay(ms, signal) {
   if (signal?.aborted) return Promise.resolve();
@@ -22,22 +22,22 @@ async function listGoalIds(policy) {
     .map(item => item.name).sort();
 }
 export function startAutonomousSupervisor({ runtime, policy = runtime?.policy,
-  idleDelayMs = 750, maxCycles = 32, logger = console } = {}) {
+  idleDelayMs = 750, maxCycles = 32, logger = console, continuous = true } = {}) {
   if (!runtime || !policy) throw new Error('autonomous supervisor requires runtime + policy');
-  if (policy.planner.backend !== 'openai_compatible') {
-    throw new Error('autonomous supervisor requires openai_compatible planner backend');
-  }
+  const providerBacked = policy.planner.backend === 'openai_compatible';
   if (!Number.isInteger(idleDelayMs) || idleDelayMs < 25 || idleDelayMs > 60_000) {
     throw new Error('autonomous supervisor idleDelayMs out of range');
   }
   if (!Number.isInteger(maxCycles) || maxCycles < 1 || maxCycles > 32) {
     throw new Error('autonomous supervisor maxCycles out of range');
   }
+  if (typeof continuous !== 'boolean') throw new Error('autonomous supervisor continuous must be boolean');
   const abort = new AbortController();
   const failures = new Map();
   let passes = 0;
 
   async function pass() {
+    if (!providerBacked) { passes += 1; return 0; }
     let runnable = 0;
     for (const goalId of await listGoalIds(policy)) {
       if (abort.signal.aborted) break;
@@ -45,12 +45,35 @@ export function startAutonomousSupervisor({ runtime, policy = runtime?.policy,
       try { status = await runtime.status({ goalId }); }
       catch (error) { logger.warn?.(`DEADBYTE supervisor status ${goalId}: ${String(error)}`); continue; }
       if (TERMINAL.has(status.state)) { failures.delete(goalId); continue; }
+      if (status.state === 'paused' && status.reason !== 'provider_circuit_open') {
+        failures.delete(goalId); continue;
+      }
+      if (status.state === 'paused' && status.reason === 'provider_circuit_open') {
+        let circuit;
+        try { circuit=await runtime.providerCircuitStatus({goalId}); }
+        catch (error) { logger.warn?.(`DEADBYTE supervisor circuit ${goalId}: ${String(error)}`); continue; }
+        const probeAt=Date.parse(circuit?.next_probe_at_utc ?? '');
+        if (circuit?.state === 'OPEN' && Number.isFinite(probeAt) && Date.now() < probeAt) {
+          failures.set(goalId,{count:0,retry_at:probeAt,error:'provider_circuit_open'});
+          continue;
+        }
+        if (!['HALF_OPEN','CLOSED'].includes(circuit?.state)) {
+          failures.delete(goalId); continue;
+        }
+      }
       runnable += 1;
       const failure = failures.get(goalId);
       if (failure && Date.now() < failure.retry_at) continue;
       try {
         const result = await runtime.run({ goalId, maxCycles });
-        failures.delete(goalId);
+        if (result.status === 'paused' && result.reason === 'provider_circuit_open') {
+          const circuit=await runtime.providerCircuitStatus({goalId});
+          const probeAt=Date.parse(circuit?.next_probe_at_utc ?? '');
+          failures.set(goalId,{count:0,retry_at:Number.isFinite(probeAt)?probeAt:Date.now()+idleDelayMs,
+            error:'provider_circuit_open'});
+        } else {
+          failures.delete(goalId);
+        }
         if (result.status === 'input_required') {
           throw new Error('provider-backed supervisor unexpectedly requested client sampling');
         }
@@ -66,7 +89,7 @@ export function startAutonomousSupervisor({ runtime, policy = runtime?.policy,
     return runnable;
   }
 
-  const done = (async () => {
+  const done = continuous ? (async () => {
     while (!abort.signal.aborted) {
       let runnable = 0;
       try { runnable = await pass(); }
@@ -74,7 +97,7 @@ export function startAutonomousSupervisor({ runtime, policy = runtime?.policy,
       if (abort.signal.aborted) break;
       await delay(runnable > 0 ? 25 : idleDelayMs, abort.signal);
     }
-  })();
+  })() : Promise.resolve();
 
   return Object.freeze({
     get running() { return !abort.signal.aborted; },

package/src/capability-benchmark-runner.mjs

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalJson } from './canonical-json.mjs';
+import { buildCapabilityBenchmark } from './capability-benchmark.mjs';
+
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+const TEST_TIMEOUT_MS=180_000;
+
+export const R35_BENCHMARK_CASE_IDS=Object.freeze([
+  'filesystem_bounded_read','exact_edit_stale_reject','paged_search','process_owned_lifecycle',
+  'semantic_typescript','semantic_python','semantic_rust','semantic_cpp','context_provenance',
+  'autonomous_fail_repair','remote_replay_dedupe'
+]);
+
+const DEFINITIONS=Object.freeze([
+  {case_id:'filesystem_bounded_read',test_files:['test/multi-file-read.test.mjs'],fixture_files:['test/multi-file-read.test.mjs'],round_trips:2,stale_rejected:false,recovery_success:true},
+  {case_id:'exact_edit_stale_reject',test_files:['test/coding-plane.test.mjs','test/native-diff.test.mjs'],fixture_files:['test/coding-plane.test.mjs','test/native-diff.test.mjs'],round_trips:4,stale_rejected:true,recovery_success:true},
+  {case_id:'paged_search',test_files:['test/observation-runtime.test.mjs'],fixture_files:['test/observation-runtime.test.mjs'],round_trips:4,stale_rejected:false,recovery_success:true},
+  {case_id:'process_owned_lifecycle',test_files:['test/process-runtime.test.mjs'],fixture_files:['test/process-runtime.test.mjs'],round_trips:6,stale_rejected:true,recovery_success:true},
+  {case_id:'semantic_typescript',test_files:['test/semantic-code.test.mjs'],fixture_files:['test/semantic-code.test.mjs','test/fixtures/semantic/typescript'],round_trips:5,stale_rejected:true,recovery_success:true},
+  {case_id:'semantic_python',test_files:['test/semantic-multilang.test.mjs'],fixture_files:['test/semantic-multilang.test.mjs','test/fixtures/semantic/python'],test_name_pattern:'R35 python semantic tracer',requires_semantic_config:true,round_trips:5,stale_rejected:true,recovery_success:true},
+  {case_id:'semantic_rust',test_files:['test/semantic-multilang.test.mjs'],fixture_files:['test/semantic-multilang.test.mjs','test/fixtures/semantic/rust'],test_name_pattern:'R35 rust semantic tracer',requires_semantic_config:true,round_trips:5,stale_rejected:true,recovery_success:true},
+  {case_id:'semantic_cpp',test_files:['test/semantic-multilang.test.mjs'],fixture_files:['test/semantic-multilang.test.mjs','test/fixtures/semantic/cpp'],test_name_pattern:'R35 cpp semantic tracer',requires_semantic_config:true,round_trips:5,stale_rejected:true,recovery_success:true},
+  {case_id:'context_provenance',test_files:['test/context-provenance.test.mjs','test/autonomous-context-engine.test.mjs'],fixture_files:['test/context-provenance.test.mjs','test/autonomous-context-engine.test.mjs'],round_trips:2,stale_rejected:false,recovery_success:true},
+  {case_id:'autonomous_fail_repair',test_files:['test/autonomous-r34-e2e.test.mjs','test/autonomous-loop-v2.test.mjs'],fixture_files:['test/autonomous-r34-e2e.test.mjs','test/autonomous-loop-v2.test.mjs','test/helpers/autonomous-r34-fixture.mjs'],test_name_pattern:'(?:multi-step fail replan repair finish|failed VERIFY enters CRITIC|REPAIR must change)',round_trips:8,stale_rejected:true,recovery_success:true},
+  {case_id:'remote_replay_dedupe',test_files:['test/remote-result-journal.test.mjs','test/remote-session-cli.test.mjs'],fixture_files:['test/remote-result-journal.test.mjs','test/remote-session-cli.test.mjs'],test_name_pattern:'(?:duplicate terminal results|remote --resume replays)',round_trips:4,stale_rejected:false,recovery_success:true}
+]);
+
+export function benchmarkCaseDefinitions(){
+  return DEFINITIONS.map(item=>({
+    ...structuredClone(item),
+    fixture_files:['bench/fixtures/corpus.json',...item.fixture_files]
+  }));
+}
+
+async function collectFiles(root,relative){
+  const absolute=path.resolve(root,relative);
+  const info=await stat(absolute);
+  if(info.isFile()) return [{relative:relative.replaceAll('\\','/'),absolute}];
+  if(!info.isDirectory()) throw new Error(`benchmark fixture '${relative}' is not file/directory`);
+  const out=[];
+  async function walk(dir,rel){
+    const names=(await readdir(dir,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name));
+    for(const entry of names){
+      const child=path.join(dir,entry.name);const childRel=path.join(rel,entry.name);
+      if(entry.isSymbolicLink()) throw new Error(`benchmark fixture symlink rejected: ${childRel}`);
+      if(entry.isDirectory()) await walk(child,childRel);
+      else if(entry.isFile()) out.push({relative:childRel.replaceAll('\\','/'),absolute:child});
+    }
+  }
+  await walk(absolute,relative);
+  return out;
+}
+
+export async function fixtureIdentityForCase({rootUrl,definition}){
+  if(!definition||typeof definition!=='object'||!Array.isArray(definition.fixture_files)||definition.fixture_files.length<1) throw new Error('benchmark fixture definition invalid');
+  const root=typeof rootUrl==='string'?path.resolve(rootUrl):fileURLToPath(rootUrl);
+  const files=[];
+  for(const relative of definition.fixture_files) files.push(...await collectFiles(root,relative));
+  files.sort((a,b)=>a.relative.localeCompare(b.relative));
+  const records=[];
+  for(const item of files) records.push({path:item.relative,sha256:sha256(await readFile(item.absolute))});
+  return sha256(Buffer.from(canonicalJson({schema:'deadbyte.r35-benchmark-fixture.v1',case_id:definition.case_id,files:records}),'utf8'));
+}
+
+function runNodeTest({root,definition,env,timeoutMs}){
+  return new Promise(resolve=>{
+    const args=['--test'];
+    if(definition.test_name_pattern) args.push(`--test-name-pattern=${definition.test_name_pattern}`);
+    args.push(...definition.test_files);
+    const started=process.hrtime.bigint();
+    const child=spawn(process.execPath,args,{cwd:root,env:{...process.env,...env},shell:false,windowsHide:true,stdio:['ignore','pipe','pipe']});
+    const stdout=[];const stderr=[];let bytes=0;let killed=false;
+    const timer=setTimeout(()=>{killed=true;child.kill('SIGKILL');},timeoutMs);
+    child.stdout.on('data',chunk=>{stdout.push(chunk);bytes+=chunk.length;});
+    child.stderr.on('data',chunk=>{stderr.push(chunk);bytes+=chunk.length;});
+    child.once('error',error=>{clearTimeout(timer);resolve({exit_code:null,timed_out:false,error:String(error),stdout:Buffer.concat(stdout),stderr:Buffer.concat(stderr),bytes,elapsed_ms:Number(process.hrtime.bigint()-started)/1e6});});
+    child.once('exit',(code,signal)=>{clearTimeout(timer);resolve({exit_code:code,timed_out:killed,signal,stdout:Buffer.concat(stdout),stderr:Buffer.concat(stderr),bytes,elapsed_ms:Number(process.hrtime.bigint()-started)/1e6});});
+  });
+}
+
+export async function runCapabilityBenchmark({rootUrl,definitions=benchmarkCaseDefinitions(),env={},timeoutMs=TEST_TIMEOUT_MS}={}){
+  const root=typeof rootUrl==='string'?path.resolve(rootUrl):fileURLToPath(rootUrl??new URL('../',import.meta.url));
+  if(!Array.isArray(definitions)||definitions.length<1) throw new Error('benchmark definitions invalid');
+  if(!Number.isInteger(timeoutMs)||timeoutMs<1000||timeoutMs>600000) throw new Error('benchmark timeout invalid');
+  const cases=[];
+  for(const definition of definitions){
+    if(definition.requires_semantic_config&&(!env.DEADBYTE_R35_SEMANTIC_CONFIG||!env.DEADBYTE_R35_SEMANTIC_CONFIG_SHA256)){
+      throw new Error(`benchmark case '${definition.case_id}' requires pinned semantic config env`);
+    }
+    const fixture_sha256=await fixtureIdentityForCase({rootUrl:root,definition});
+    let result;
+    try{result=await runNodeTest({root,definition,env,timeoutMs});}
+    catch(error){result={exit_code:null,timed_out:false,error:String(error),stdout:Buffer.alloc(0),stderr:Buffer.alloc(0),bytes:0,elapsed_ms:0};}
+    const evidence={schema:'deadbyte.r35-benchmark-case-evidence.v1',case_id:definition.case_id,exit_code:result.exit_code,
+      timed_out:result.timed_out===true,signal:result.signal??null,error:result.error??null,
+      stdout_sha256:sha256(result.stdout??Buffer.alloc(0)),stderr_sha256:sha256(result.stderr??Buffer.alloc(0))};
+    const correct=result.exit_code===0&&!result.timed_out&&!result.error;
+    cases.push({case_id:definition.case_id,fixture_sha256,correct,round_trips:definition.round_trips,
+      bytes_returned:result.bytes??0,elapsed_ms:result.elapsed_ms??0,
+      stale_rejected:correct&&definition.stale_rejected===true,recovery_success:correct&&definition.recovery_success===true,
+      duplicate_side_effects:correct?0:1,evidence_sha256:sha256(Buffer.from(canonicalJson(evidence),'utf8'))});
+  }
+  return buildCapabilityBenchmark({suite_id:'r35-offline-v1',cases});
+}

package/src/capability-benchmark.mjs

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const CAPABILITY_BENCHMARK_SCHEMA='deadbyte.r35-capability-benchmark.v1';
+const HEX64=/^[0-9a-f]{64}$/;
+const CASE_ID=/^[A-Za-z0-9._-]{1,96}$/;
+const SUITE_ID=/^[A-Za-z0-9._-]{1,96}$/;
+
+function sha256(value){return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');}
+function bool(value,label){if(typeof value!=='boolean') throw new Error(`${label} invalid`);return value;}
+function uint(value,label,{min=0,max=Number.MAX_SAFE_INTEGER}={}){
+  if(!Number.isSafeInteger(value)||value<min||value>max) throw new Error(`${label} invalid`);return value;
+}
+function finite(value,label){if(typeof value!=='number'||!Number.isFinite(value)||value<0) throw new Error(`${label} invalid`);return value;}
+function hash(value,label){if(typeof value!=='string'||!HEX64.test(value)) throw new Error(`${label} evidence hash invalid`);return value;}
+
+export function normalizeBenchmarkCase(raw){
+  if(!raw||typeof raw!=='object'||Array.isArray(raw)) throw new Error('benchmark case invalid');
+  const id=raw.case_id;
+  if(typeof id!=='string'||!CASE_ID.test(id)) throw new Error('benchmark case_id invalid');
+  return Object.freeze({
+    case_id:id,
+    fixture_sha256:hash(raw.fixture_sha256,'benchmark fixture'),
+    correct:bool(raw.correct,'benchmark correct'),
+    round_trips:uint(raw.round_trips,'benchmark round-trips',{min:1,max:100000}),
+    bytes_returned:uint(raw.bytes_returned,'benchmark bytes_returned',{max:1024*1024*1024}),
+    elapsed_ms:finite(raw.elapsed_ms,'benchmark elapsed_ms'),
+    stale_rejected:bool(raw.stale_rejected,'benchmark stale_rejected'),
+    recovery_success:bool(raw.recovery_success,'benchmark recovery_success'),
+    duplicate_side_effects:uint(raw.duplicate_side_effects,'benchmark duplicate_side_effects',{max:100000}),
+    evidence_sha256:hash(raw.evidence_sha256,'benchmark evidence')
+  });
+}
+
+export function buildCapabilityBenchmark({suite_id:rawSuiteId,cases:rawCases}={}){
+  if(typeof rawSuiteId!=='string'||!SUITE_ID.test(rawSuiteId)) throw new Error('benchmark suite_id invalid');
+  if(!Array.isArray(rawCases)||rawCases.length<1||rawCases.length>128) throw new Error('benchmark cases invalid');
+  const cases=rawCases.map(normalizeBenchmarkCase).sort((a,b)=>a.case_id.localeCompare(b.case_id));
+  const seen=new Set();
+  for(const item of cases){if(seen.has(item.case_id)) throw new Error(`duplicate case '${item.case_id}'`);seen.add(item.case_id);}
+  const fixtureIdentity={schema:'deadbyte.r35-capability-fixtures.v1',suite_id:rawSuiteId,
+    fixtures:cases.map(item=>({case_id:item.case_id,fixture_sha256:item.fixture_sha256}))};
+  const fixture_identity_sha256=sha256(fixtureIdentity);
+  const observation={schema:CAPABILITY_BENCHMARK_SCHEMA,suite_id:rawSuiteId,fixture_identity_sha256,cases};
+  return Object.freeze({
+    ...observation,
+    overall_correct:cases.every(item=>item.correct),
+    observation_sha256:sha256(observation)
+  });
+}

package/src/coding-mcp-tools.mjs

@@ -2,8 +2,9 @@ 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, codingSymbolReplaceOutputSchema,
   codingTaskApproveOutputSchema, codingTaskCancelOutputSchema,
   codingTaskEventsOutputSchema, codingTaskRunOutputSchema,
   codingTaskStatusOutputSchema, codingTaskSubmitOutputSchema,
@@ -45,8 +46,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.',
@@ -76,6 +77,48 @@ export function registerCodingTools(server, { codingRuntime, taskRuntime }) {
     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_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 in one request using the same coding-policy lease and deny-path checks as coding_file_read.',
+    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); }
+  });
+
   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

@@ -83,6 +83,51 @@ export const codingSearchOutputSchema = statusContract({
     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']
 });
+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 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() },
+  successStatuses: ['ok'], successRequired: ['root_id','total_bytes','files']
+});
 export const codingFileReadOutputSchema = statusContract({
   statuses: ['ok', 'failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), encoding: z.enum(['utf8', 'base64']).optional(),

package/src/context-provenance.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+const SCHEMA='deadbyte.context-provenance.v1';
+const HEX64=/^[0-9a-f]{64}$/;
+const SECRET_KEY=/(?:^|[_-])(token|password|secret|authorization|cookie|credential|credentials|api[_-]?key|private[_-]?key|recovery)(?:$|[_-])/i;
+
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+function boundedText(value,label,max=512){
+  if(typeof value!=='string'||value.length<1||value.length>max||/[\r\n\0]/.test(value)) throw new Error(`provenance ${label} invalid`);
+  return value;
+}
+
+function observedUtc(value){
+  if(typeof value!=='string'||value.length<20||value.length>64) throw new Error('provenance observedAtUtc invalid');
+  const time=Date.parse(value);
+  if(!Number.isFinite(time)) throw new Error('provenance observedAtUtc invalid');
+  return new Date(time).toISOString();
+}
+
+function structuredSecretShape(value,key=''){
+  if(key&&SECRET_KEY.test(key)) return {value:'[REDACTED]',secret:true};
+  if(Array.isArray(value)){
+    let secret=false;
+    const out=value.map(item=>{const next=structuredSecretShape(item,'');secret=secret||next.secret;return next.value;});
+    return {value:out,secret};
+  }
+  if(value&&typeof value==='object'&&!Buffer.isBuffer(value)&&!(value instanceof Uint8Array)){
+    let secret=false;const out={};
+    for(const name of Object.keys(value).sort()){
+      const next=structuredSecretShape(value[name],name);secret=secret||next.secret;out[name]=next.value;
+    }
+    return {value:out,secret};
+  }
+  return {value,secret:false};
+}
+
+function bytesIdentity(bytes){
+  if(Buffer.isBuffer(bytes)) return {raw:bytes,safe:bytes,secret:false};
+  if(bytes instanceof Uint8Array) { const raw=Buffer.from(bytes); return {raw,safe:raw,secret:false}; }
+  if(typeof bytes==='string'){const raw=Buffer.from(bytes,'utf8');return {raw,safe:raw,secret:false};}
+  if(bytes===null||typeof bytes!=='object') throw new Error('provenance bytes invalid');
+  const raw=Buffer.from(canonicalJson(bytes),'utf8');
+  const shaped=structuredSecretShape(bytes);
+  return {raw,safe:Buffer.from(canonicalJson(shaped.value),'utf8'),secret:shaped.secret};
+}
+
+export function provenanceFor({sourceKind,sourceId,bytes,observedAtUtc,trustClass,relevanceEpoch}){
+  const source_kind=boundedText(sourceKind,'sourceKind',96);
+  const source_id=boundedText(sourceId,'sourceId',1024);
+  const trust_class=boundedText(trustClass,'trustClass',96);
+  if(!Number.isInteger(relevanceEpoch)||relevanceEpoch<0||relevanceEpoch>Number.MAX_SAFE_INTEGER) throw new Error('provenance relevanceEpoch invalid');
+  const observed_at_utc=observedUtc(observedAtUtc);
+  const identity=bytesIdentity(bytes);
+  const source_sha256=identity.secret?null:sha256(identity.raw);
+  const safePayloadSha256=sha256(identity.safe);
+  const provenance_id=sha256(Buffer.from(canonicalJson({schema:SCHEMA,source_kind,source_id,source_sha256,safe_payload_sha256:safePayloadSha256,trust_class,relevance_epoch:relevanceEpoch}),'utf8'));
+  const out={schema:SCHEMA,source_kind,source_id,observed_at_utc,byte_count:identity.raw.length,trust_class,relevance_epoch:relevanceEpoch,provenance_id};
+  if(source_sha256!==null) out.source_sha256=source_sha256;
+  else out.digest_withheld='secret';
+  return Object.freeze(out);
+}
+
+function provenanceOf(item,index){
+  if(!item||typeof item!=='object'||Array.isArray(item)) throw new Error(`evidence item ${index+1} invalid`);
+  const provenance=item.provenance;
+  if(!provenance||typeof provenance!=='object'||provenance.schema!==SCHEMA||!HEX64.test(provenance.provenance_id??'')) throw new Error(`evidence provenance ${index+1} invalid`);
+  const time=Date.parse(provenance.observed_at_utc);
+  if(!Number.isFinite(time)) throw new Error(`evidence provenance ${index+1} observed_at_utc invalid`);
+  return {provenance,time};
+}
+
+export function dedupeEvidence(items){
+  if(!Array.isArray(items)) throw new Error('evidence items must be an array');
+  const order=[];const selected=new Map();
+  for(let index=0;index<items.length;index+=1){
+    const item=items[index];const {provenance,time}=provenanceOf(item,index);const id=provenance.provenance_id;
+    if(!selected.has(id)){order.push(id);selected.set(id,{item,time,index});continue;}
+    const previous=selected.get(id);
+    if(time>previous.time||(time===previous.time&&index>previous.index)) selected.set(id,{item,time,index});
+  }
+  return order.map(id=>structuredClone(selected.get(id).item));
+}
+
+export const CONTEXT_PROVENANCE_SCHEMA=SCHEMA;