deadbyte-mcp 0.8.10 → 0.10.0

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

package/src/compact-gateway-mcp-tools.mjs

@@ -0,0 +1,128 @@
+import * as z from 'zod/v4';
+import { compactGatewayOutputSchema, compactGatewayResult } from './compact-gateway-output-contracts.mjs';
+
+const id=z.string().regex(/^[A-Za-z0-9._-]{1,64}$/);
+const rel=z.string().min(1).max(2048);
+const rel512=z.string().min(1).max(512);
+const hex64=z.string().regex(/^[0-9a-f]{64}$/);
+const cursor=z.string().max(4096).nullable().default(null);
+const nonneg=z.number().int().nonnegative();
+const symbolName=z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/);
+
+export const codingInspectInputSchema=z.discriminatedUnion('op',[
+  z.strictObject({op:z.literal('stat'),root_id:id,path:rel512.default('.'),hash:z.boolean().default(false)}),
+  z.strictObject({op:z.literal('search'),root_id:id,path:rel512.default('.'),pattern:z.string().min(1).max(256),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(4*1024*1024).default(262144),max_scan_bytes:z.number().int().min(1).max(64*1024*1024).default(4*1024*1024),page_size:z.number().int().min(1).max(500).default(100),cursor}),
+  z.strictObject({op:z.literal('files_read'),root_id:id,files:z.array(z.strictObject({path:rel512,encoding:z.enum(['utf8','base64']).default('utf8')})).min(1).max(32),max_total_bytes:z.number().int().min(1).max(2097152).default(1048576)}),
+  z.strictObject({op:z.literal('symbol_outline'),root_id:id,path:rel512,max_symbols:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({op:z.literal('symbol_definition'),root_id:id,path:rel512,line:nonneg,column:nonneg,max_results:z.number().int().min(1).max(200).default(50)}),
+  z.strictObject({op:z.literal('symbol_references'),root_id:id,path:rel512,line:nonneg,column:nonneg,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({op:z.literal('symbol_diagnostics'),root_id:id,path:rel512,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({op:z.literal('symbol_implementations'),root_id:id,path:rel512,line:nonneg,column:nonneg,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({op:z.literal('symbol_rename_preview'),root_id:id,path:rel512,line:nonneg,column:nonneg,new_name:symbolName})
+]);
+
+export const machineFsGatewayInputSchema=z.discriminatedUnion('op',[
+  z.strictObject({op:z.literal('stat'),root_id:id,path:rel.default('.'),hash:z.boolean().default(false)}),
+  z.strictObject({op:z.literal('list'),root_id:id,path:rel.default('.'),cursor,limit:z.number().int().min(1).max(1000).default(100),hash_files:z.boolean().default(false)}),
+  z.strictObject({op:z.literal('read'),root_id:id,path:rel,offset:nonneg.default(0),max_bytes:z.number().int().min(1).max(4*1024*1024).default(65536),hash_file:z.boolean().default(false)}),
+  z.strictObject({op:z.literal('write'),root_id:id,path:rel,content:z.string().max(12*1024*1024),encoding:z.enum(['utf8','base64']).default('utf8'),expected_sha256:z.string().regex(/^(?:absent|[0-9a-f]{64})$/)}),
+  z.strictObject({op:z.literal('edit_exact'),root_id:id,path:rel,expected_sha256:hex64,old_string:z.string().min(1).max(262144),new_string:z.string().max(524288),expected_replacements:z.number().int().min(1).max(64).default(1)}),
+  z.strictObject({op:z.literal('mkdir'),root_id:id,path:rel}),
+  z.strictObject({op:z.literal('move'),root_id:id,source_path:rel,destination_path:rel,expected_source_identity:hex64}),
+  z.strictObject({op:z.literal('delete'),root_id:id,path:rel,expected_source_identity:hex64})
+]);
+
+export const processSessionGatewayInputSchema=z.discriminatedUnion('op',[
+  z.strictObject({op:z.literal('start'),profile_id:id,root_id:id,cwd:rel.default('.'),args:z.array(z.string().max(8192)).max(64).default([])}),
+  z.strictObject({op:z.literal('read'),session_id:hex64,offset:nonneg.default(0),max_bytes:z.number().int().min(1).max(262144).default(65536)}),
+  z.strictObject({op:z.literal('status'),session_id:hex64}),
+  z.strictObject({op:z.literal('list')}),
+  z.strictObject({op:z.literal('action'),session_id:hex64,action_id:id}),
+  z.strictObject({op:z.literal('terminate'),session_id:hex64})
+]);
+
+export const machineObserveInputSchema=z.discriminatedUnion('op',[
+  z.strictObject({op:z.literal('machine_list')}),
+  z.strictObject({op:z.literal('machine_status')}),
+  z.strictObject({op:z.literal('machine_ping'),nonce:z.string().min(1).max(256)}),
+  z.strictObject({op:z.literal('search_start'),root_id:id,path:rel512.default('.'),pattern:z.string().min(1).max(256),case_sensitive:z.boolean().default(false),max_results:z.number().int().min(1).max(1000).default(200),max_files:z.number().int().min(1).max(10000).default(2000),max_bytes:z.number().int().min(1).max(64*1024*1024).default(4*1024*1024),max_file_bytes:z.number().int().min(1).max(4*1024*1024).default(262144)}),
+  z.strictObject({op:z.literal('search_page'),search_id:hex64,limit:z.number().int().min(1).max(500).default(100),cursor:z.string().max(512).nullable().default(null)}),
+  z.strictObject({op:z.literal('search_status'),search_id:hex64}),
+  z.strictObject({op:z.literal('search_cancel'),search_id:hex64}),
+  z.strictObject({op:z.literal('process_list'),limit:z.number().int().min(1).max(256).default(100),include_external:z.boolean().default(false),cursor:z.string().max(512).nullable().default(null)}),
+  z.strictObject({op:z.literal('system_status')})
+]);
+
+const capabilityManifestInputSchema=z.strictObject({});
+
+function unavailable(op,name){return compactGatewayResult({status:'unavailable',op,error:`${name} runtime unavailable`},true);}
+async function invoke(op,runtime,name,call){
+  if(!runtime) return unavailable(op,name);
+  try{return compactGatewayResult({status:'ok',op,result:await call(runtime)},false);}
+  catch(error){return compactGatewayResult({status:'denied',op,error:String(error)},true);}
+}
+
+async function codingInspect(args,codingRuntime,semanticRuntime){
+  switch(args.op){
+    case 'stat': return invoke(args.op,codingRuntime,'coding',r=>r.stat({rootId:args.root_id,relativePath:args.path,hash:args.hash}));
+    case 'search': return invoke(args.op,codingRuntime,'coding',r=>r.search({rootId:args.root_id,path:args.path,pattern:args.pattern,target:args.target,mode:args.mode,caseSensitive:args.case_sensitive,maxResults:args.max_results,maxFileBytes:args.max_file_bytes,maxScanBytes:args.max_scan_bytes,pageSize:args.page_size,cursor:args.cursor}));
+    case 'files_read': return invoke(args.op,codingRuntime,'coding',r=>r.filesRead({rootId:args.root_id,files:args.files,maxTotalBytes:args.max_total_bytes}));
+    case 'symbol_outline': return invoke(args.op,semanticRuntime,'semantic',r=>r.outline({rootId:args.root_id,relativePath:args.path,maxSymbols:args.max_symbols}));
+    case 'symbol_definition': return invoke(args.op,semanticRuntime,'semantic',r=>r.definition({rootId:args.root_id,relativePath:args.path,line:args.line,column:args.column,maxResults:args.max_results}));
+    case 'symbol_references': return invoke(args.op,semanticRuntime,'semantic',r=>r.references({rootId:args.root_id,relativePath:args.path,line:args.line,column:args.column,maxResults:args.max_results}));
+    case 'symbol_diagnostics': return invoke(args.op,semanticRuntime,'semantic',r=>r.diagnostics({rootId:args.root_id,relativePath:args.path,maxResults:args.max_results}));
+    case 'symbol_implementations': return invoke(args.op,semanticRuntime,'semantic',r=>{if(typeof r.implementations!=='function') throw new Error('semantic implementations unavailable');return r.implementations({rootId:args.root_id,relativePath:args.path,line:args.line,column:args.column,maxResults:args.max_results});});
+    case 'symbol_rename_preview': return invoke(args.op,semanticRuntime,'semantic',r=>{if(typeof r.renamePreview!=='function') throw new Error('semantic rename preview unavailable');return r.renamePreview({rootId:args.root_id,relativePath:args.path,line:args.line,column:args.column,newName:args.new_name});});
+  }
+}
+
+async function machineFs(args,runtime){
+  const map={
+    stat:r=>r.stat({rootId:args.root_id,relativePath:args.path,hash:args.hash}),
+    list:r=>r.list({rootId:args.root_id,relativePath:args.path,cursor:args.cursor,limit:args.limit,hashFiles:args.hash_files}),
+    read:r=>r.read({rootId:args.root_id,relativePath:args.path,offset:args.offset,maxBytes:args.max_bytes,hashFile:args.hash_file}),
+    write:r=>r.write({rootId:args.root_id,relativePath:args.path,content:args.content,encoding:args.encoding,expectedSha256:args.expected_sha256}),
+    edit_exact:r=>r.editExact({rootId:args.root_id,relativePath:args.path,expectedSha256:args.expected_sha256,oldString:args.old_string,newString:args.new_string,expectedReplacements:args.expected_replacements}),
+    mkdir:r=>r.mkdir({rootId:args.root_id,relativePath:args.path}),
+    move:r=>r.move({rootId:args.root_id,sourcePath:args.source_path,destinationPath:args.destination_path,expectedSourceIdentity:args.expected_source_identity}),
+    delete:r=>r.delete({rootId:args.root_id,relativePath:args.path,expectedSourceIdentity:args.expected_source_identity})
+  };
+  return invoke(args.op,runtime,'machine_fs',map[args.op]);
+}
+
+async function processSession(args,runtime){
+  const map={
+    start:r=>r.start({profileId:args.profile_id,rootId:args.root_id,cwd:args.cwd,args:args.args}),
+    read:r=>r.read({sessionId:args.session_id,offset:args.offset,maxBytes:args.max_bytes}),
+    status:r=>r.status({sessionId:args.session_id}),
+    list:r=>r.list(),
+    action:r=>r.action({sessionId:args.session_id,actionId:args.action_id}),
+    terminate:r=>r.terminate({sessionId:args.session_id})
+  };
+  return invoke(args.op,runtime,'process',map[args.op]);
+}
+
+async function machineObserve(args,machineRuntime,observationRuntime){
+  if(args.op==='machine_list') return invoke(args.op,machineRuntime,'machine',r=>r.list());
+  if(args.op==='machine_status') return invoke(args.op,machineRuntime,'machine',r=>r.status());
+  if(args.op==='machine_ping') return invoke(args.op,machineRuntime,'machine',r=>r.ping({nonce:args.nonce}));
+  const map={
+    search_start:r=>r.searchStart({rootId:args.root_id,relativePath:args.path,pattern:args.pattern,caseSensitive:args.case_sensitive,maxResults:args.max_results,maxFiles:args.max_files,maxBytes:args.max_bytes,maxFileBytes:args.max_file_bytes}),
+    search_page:r=>r.searchPage({searchId:args.search_id,limit:args.limit,cursor:args.cursor}),
+    search_status:r=>r.searchStatus({searchId:args.search_id}),
+    search_cancel:r=>r.searchCancel({searchId:args.search_id}),
+    process_list:r=>r.processList({limit:args.limit,includeExternal:args.include_external,cursor:args.cursor}),
+    system_status:r=>r.systemStatus()
+  };
+  return invoke(args.op,observationRuntime,'observation',map[args.op]);
+}
+
+export function registerCompactGatewayTools(server,{profile,ledger,codingRuntime,semanticRuntime,machineFsRuntime,processRuntime,observationRuntime,machineRuntime}){
+  if(!server) throw new Error('compact gateway registration requires server');
+  if(profile!=='compact') return;
+  server.registerTool('capability_manifest',{description:'Read the canonical R36 capability ledger and active compact profile.',inputSchema:capabilityManifestInputSchema,outputSchema:compactGatewayOutputSchema},async()=>compactGatewayResult({status:'ok',op:'manifest',result:{schema:'deadbyte.capability-manifest.v1',profile,ledger_sha256:ledger?.ledger_sha256??null,capabilities:ledger?.entries??[]}},false));
+  server.registerTool('coding_inspect',{description:'Typed compact coding inspection and semantic navigation gateway. No arbitrary tool dispatch.',inputSchema:codingInspectInputSchema,outputSchema:compactGatewayOutputSchema},args=>codingInspect(args,codingRuntime,semanticRuntime));
+  server.registerTool('machine_fs',{description:'Typed compact machine filesystem gateway preserving root policy and mutation preconditions.',inputSchema:machineFsGatewayInputSchema,outputSchema:compactGatewayOutputSchema},args=>machineFs(args,machineFsRuntime));
+  server.registerTool('process_session',{description:'Typed compact DEADBYTE-owned process session gateway. No raw stdin or PID authority.',inputSchema:processSessionGatewayInputSchema,outputSchema:compactGatewayOutputSchema},args=>processSession(args,processRuntime));
+  server.registerTool('machine_observe',{description:'Typed compact machine identity and read-only observation gateway. Revoke is intentionally excluded.',inputSchema:machineObserveInputSchema,outputSchema:compactGatewayOutputSchema},args=>machineObserve(args,machineRuntime,observationRuntime));
+}

package/src/compact-gateway-output-contracts.mjs

@@ -0,0 +1,16 @@
+import * as z from 'zod/v4';
+import { structuredToolResult } from './output-contracts.mjs';
+
+export const compactGatewayOutputSchema=z.strictObject({
+  status:z.enum(['ok','denied','failed','unavailable']),
+  op:z.string().min(1).max(64),
+  result:z.json().optional(),
+  error:z.string().max(4096).optional()
+}).superRefine((value,ctx)=>{
+  if(value.status==='ok'&&value.result===undefined) ctx.addIssue({code:'custom',path:['result'],message:'result is required for status=ok'});
+  if(value.status!=='ok'&&value.error===undefined) ctx.addIssue({code:'custom',path:['error'],message:'error is required for non-ok status'});
+});
+
+export function compactGatewayResult(value,isError=false){
+  return structuredToolResult(compactGatewayOutputSchema,value,isError);
+}

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;