deadbyte-mcp 0.15.74 → 0.15.75

package/src/candidate-selection-evidence-r206.mjs

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+import { evaluateCandidateSelectionR205 } from './candidate-selection-r205.mjs';
+
+const SHA=/^[0-9a-f]{64}$/;
+const sha=value=>createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+const insist=(condition,message)=>{if(!condition)throw new Error(message);};
+
+function receiptExpectations(input){
+  const expectations=[];
+  const addCorrectness=(label,artifact,value)=>expectations.push({
+    label,kind:'correctness',receipt_sha256:value.receipt_sha256,artifact_sha256:artifact,
+    fixture_sha256:input.fixture_sha256,status:value.status
+  });
+  const addBenchmark=(label,artifact,value)=>expectations.push({
+    label,kind:'benchmark',receipt_sha256:value.receipt_sha256,artifact_sha256:artifact,
+    fixture_sha256:input.fixture_sha256,environment_sha256:input.environment_sha256,
+    samples_sha256:sha(value.samples_ms)
+  });
+  addCorrectness('baseline correctness',input.baseline.artifact_sha256,input.baseline.correctness);
+  addBenchmark('baseline benchmark',input.baseline.artifact_sha256,input.baseline.benchmark);
+  for(const candidate of input.candidates){
+    addCorrectness(`candidate ${candidate.candidate_id} correctness`,candidate.artifact_sha256,candidate.correctness);
+    if(candidate.benchmark)addBenchmark(`candidate ${candidate.candidate_id} benchmark`,candidate.artifact_sha256,candidate.benchmark);
+  }
+  return expectations;
+}
+
+function verifyFact(expected,actual){
+  insist(actual&&typeof actual==='object'&&!Array.isArray(actual),`${expected.label} receipt verification failed`);
+  insist(actual.verified===true&&actual.receipt_sha256===expected.receipt_sha256,
+    `${expected.label} receipt verification failed`);
+  insist(SHA.test(actual.receipt_sha256),`${expected.label} receipt verification failed`);
+  if(expected.kind==='correctness'){
+    insist(actual.evidence_kind==='correctness'&&actual.signer_role==='independent_correctness_oracle'&&
+      actual.artifact_sha256===expected.artifact_sha256&&actual.fixture_sha256===expected.fixture_sha256&&
+      actual.status===expected.status,`${expected.label} receipt binding mismatch`);
+  }else{
+    insist(actual.evidence_kind==='benchmark'&&actual.signer_role==='independent_benchmark_runner'&&
+      actual.artifact_sha256===expected.artifact_sha256&&actual.fixture_sha256===expected.fixture_sha256&&
+      actual.environment_sha256===expected.environment_sha256&&actual.samples_sha256===expected.samples_sha256,
+      `${expected.label} receipt binding mismatch`);
+  }
+  return Object.freeze({receipt_sha256:actual.receipt_sha256,evidence_kind:actual.evidence_kind,
+    signer_role:actual.signer_role,artifact_sha256:actual.artifact_sha256,fixture_sha256:actual.fixture_sha256,
+    ...(expected.kind==='correctness'?{status:actual.status}:{environment_sha256:actual.environment_sha256,
+      samples_sha256:actual.samples_sha256})});
+}
+
+export async function verifyCandidateSelectionEvidenceR206(input,{verifyReceipt}={}){
+  insist(typeof verifyReceipt==='function','independent receipt verifier required');
+  const provisional=evaluateCandidateSelectionR205(input);
+  const expectations=receiptExpectations(input);
+  const seen=new Set();
+  const verified=[];
+  for(const expected of expectations){
+    insist(SHA.test(expected.receipt_sha256),`${expected.label} receipt hash invalid`);
+    insist(!seen.has(expected.receipt_sha256),`${expected.label} receipt reused`);
+    seen.add(expected.receipt_sha256);
+    let actual;
+    try{actual=await verifyReceipt(expected.receipt_sha256,Object.freeze({...expected}));}
+    catch(error){throw new Error(`${expected.label} receipt verification failed: ${error?.message??error}`);}
+    verified.push(verifyFact(expected,actual));
+  }
+  const binding={schema:'deadbyte.candidate-selection-evidence-binding.r206.v1',
+    selection_report_sha256:provisional.report_sha256,verified_receipts:verified};
+  return Object.freeze({...provisional,schema:'deadbyte.candidate-selection-evidence-verdict.r206.v1',
+    evidence_verified:true,verified_receipt_count:verified.length,release_authorized:false,
+    reason:'Independent decision-bearing receipts verified. Candidate selection remains advisory and cannot authorize release.',
+    evidence_binding_sha256:sha(binding)});
+}

package/src/candidate-selection-r205.mjs

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const CANDIDATE_SELECTION_SCHEMA='deadbyte.candidate-selection.r205.v1';
+const H=/^[0-9a-f]{64}$/;
+const ID=/^[A-Za-z0-9._-]{1,96}$/;
+const STATES=new Set(['PASS','FAIL','UNKNOWN','INVALID','UNTESTED']);
+const digest=value=>createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+
+function object(value,label,allowed){
+  if(!value||typeof value!=='object'||Array.isArray(value))throw Error(label+' invalid');
+  const extra=Object.keys(value).filter(k=>!allowed.includes(k));
+  if(extra.length)throw Error(label+' unexpected field '+extra[0]);
+  return value;
+}
+function hash(value,label){if(typeof value!=='string'||!H.test(value))throw Error(label+' invalid');return value;}
+function sample(value,label){
+  if(!Array.isArray(value)||value.length<7||value.length>31||value.some(x=>typeof x!=='number'||!Number.isFinite(x)||x<=0||x>3_600_000))throw Error(label+' invalid');
+  return [...value];
+}
+const median=xs=>{const a=[...xs].sort((x,y)=>x-y);return a[Math.floor(a.length/2)];};
+const mad=xs=>median(xs.map(x=>Math.abs(x-median(xs))));
+function correctness(raw,label,artifact,fixture){
+  const v=object(raw,label,['status','artifact_sha256','fixture_sha256','receipt_sha256']);
+  if(!STATES.has(v.status))throw Error(label+' status invalid');
+  if(hash(v.artifact_sha256,label+' artifact')!==artifact||hash(v.fixture_sha256,label+' fixture')!==fixture)throw Error(label+' evidence identity mismatch');
+  hash(v.receipt_sha256,label+' receipt');
+  return Object.freeze({...v});
+}
+function benchmark(raw,label,artifact,fixture,environment){
+  const v=object(raw,label,['artifact_sha256','fixture_sha256','environment_sha256','receipt_sha256','samples_ms']);
+  if(hash(v.artifact_sha256,label+' artifact')!==artifact||hash(v.fixture_sha256,label+' fixture')!==fixture||hash(v.environment_sha256,label+' environment')!==environment)throw Error(label+' benchmark identity mismatch');
+  hash(v.receipt_sha256,label+' receipt');
+  return Object.freeze({...v,samples_ms:sample(v.samples_ms,label+' samples')});
+}
+function normalize(raw){
+  const v=object(raw,'candidate selection',['schema','fixture_sha256','environment_sha256','baseline','candidates']);
+  if(v.schema!==CANDIDATE_SELECTION_SCHEMA)throw Error('candidate selection schema invalid');
+  const fixture=hash(v.fixture_sha256,'fixture'),env=hash(v.environment_sha256,'environment');
+  const b=object(v.baseline,'baseline',['artifact_sha256','correctness','benchmark']);
+  const baseHash=hash(b.artifact_sha256,'baseline artifact');
+  const baseCorrect=correctness(b.correctness,'baseline correctness',baseHash,fixture);
+  if(baseCorrect.status!=='PASS')throw Error('baseline correctness not PASS');
+  const baseBench=benchmark(b.benchmark,'baseline benchmark',baseHash,fixture,env);
+  if(!Array.isArray(v.candidates)||v.candidates.length<1||v.candidates.length>8)throw Error('candidate count invalid');
+  const seen=new Set([baseHash]),ids=new Set();
+  const candidates=v.candidates.map((item,i)=>{
+    const c=object(item,'candidate '+i,['candidate_id','artifact_sha256','correctness','benchmark']);
+    if(typeof c.candidate_id!=='string'||!ID.test(c.candidate_id)||ids.has(c.candidate_id))throw Error('candidate id invalid or repeated');
+    ids.add(c.candidate_id);
+    const h=hash(c.artifact_sha256,'candidate artifact');
+    if(seen.has(h))throw Error('candidate artifact duplicated');seen.add(h);
+    const result=correctness(c.correctness,'candidate correctness',h,fixture);
+    const bench=c.benchmark===undefined?null:benchmark(c.benchmark,'candidate benchmark',h,fixture,env);
+    if(result.status==='PASS'&&!bench)throw Error('PASS candidate benchmark missing');
+    if(bench&&bench.samples_ms.length!==baseBench.samples_ms.length)throw Error('paired sample length mismatch');
+    return {candidate_id:c.candidate_id,artifact_sha256:h,correctness:result,benchmark:bench};
+  });
+  return {fixture,environment:env,baseline:{artifact_sha256:baseHash,correctness:baseCorrect,benchmark:baseBench},candidates};
+}
+export function buildBlindCandidateViewR205(input){
+  const v=normalize(input);
+  return Object.freeze({schema:CANDIDATE_SELECTION_SCHEMA,fixture_sha256:v.fixture,environment_sha256:v.environment,
+    baseline:{artifact_sha256:v.baseline.artifact_sha256,correctness:v.baseline.correctness,benchmark:v.baseline.benchmark},
+    candidates:v.candidates.map(c=>({artifact_sha256:c.artifact_sha256,correctness:c.correctness,benchmark:c.benchmark}))
+      .sort((a,b)=>a.artifact_sha256.localeCompare(b.artifact_sha256))});
+}
+export function evaluateCandidateSelectionR205(input,{minimum_gain_pct=5,minimum_win_rate=0.8,max_mad_pct=8,ambiguity_margin_pct=3}={}){
+  for(const [name,v,max] of [['minimum_gain_pct',minimum_gain_pct,100],['minimum_win_rate',minimum_win_rate,1],['max_mad_pct',max_mad_pct,100],['ambiguity_margin_pct',ambiguity_margin_pct,100]]){
+    if(typeof v!=='number'||!Number.isFinite(v)||v<0||v>max)throw Error(name+' invalid');
+  }
+  const parsed=normalize(input);
+  const baseline=parsed.baseline.benchmark.samples_ms;
+  const classified=parsed.candidates.map(c=>{
+    if(c.correctness.status!=='PASS')return {candidate_id:c.candidate_id,artifact_sha256:c.artifact_sha256,verdict:c.correctness.status==='FAIL'?'REJECT_CORRECTNESS':'UNGRADED',correctness_status:c.correctness.status};
+    const changes=c.benchmark.samples_ms.map((time,i)=>100*(baseline[i]-time)/baseline[i]);
+    const gain=median(changes),deviation=mad(changes),wins=changes.filter(x=>x>0).length;
+    const winRate=wins/changes.length;
+    const eligible=gain>=minimum_gain_pct&&winRate>=minimum_win_rate&&deviation<=max_mad_pct;
+    return {candidate_id:c.candidate_id,artifact_sha256:c.artifact_sha256,verdict:eligible?'PERFORMANCE_QUALIFIED':'REJECT_PERFORMANCE',
+      correctness_status:'PASS',median_gain_pct:Number(gain.toFixed(4)),mad_pct:Number(deviation.toFixed(4)),
+      win_rate:Number(winRate.toFixed(4)),sample_count:changes.length};
+  });
+  const ranked=classified.filter(x=>x.verdict==='PERFORMANCE_QUALIFIED').sort((a,b)=>b.median_gain_pct-a.median_gain_pct||a.artifact_sha256.localeCompare(b.artifact_sha256));
+  const ambiguous=ranked.length>1&&ranked[0].median_gain_pct-ranked[1].median_gain_pct<ambiguity_margin_pct;
+  const winner=ranked.length&&!ambiguous?ranked[0]:null;
+  const report={schema:'deadbyte.candidate-selection-verdict.r205.v1',
+    state:ambiguous?'AMBIGUOUS':winner?'PROVISIONAL_CANDIDATE':'NO_QUALIFIED_CANDIDATE',
+    winner_candidate_id:winner?.candidate_id??null,winner_artifact_sha256:winner?.artifact_sha256??null,
+    evidence_verified:false,release_authorized:false,
+    reason:'Claims and receipt hashes are syntax/identity checked only. Signed receipts, independent oracle and benchmark runner must be verified externally before promotion.',
+    fixture_sha256:parsed.fixture,environment_sha256:parsed.environment,baseline_artifact_sha256:parsed.baseline.artifact_sha256,
+    candidates:classified.sort((a,b)=>a.artifact_sha256.localeCompare(b.artifact_sha256)),
+    blind_evaluation_sha256:digest(buildBlindCandidateViewR205(input))};
+  return Object.freeze({...report,report_sha256:digest(report)});
+}

package/src/desktop-postcondition-r196.mjs

@@ -0,0 +1,30 @@
+const SHA256=/^[0-9a-f]{64}$/;
+
+export function validateDesktopPostconditionExpectation(expectation){
+ if(expectation===null)return null;
+ if(!expectation||typeof expectation!=='object'||Array.isArray(expectation)||
+    Object.keys(expectation).sort().join(',')!=='expected_sha256,kind'||
+    expectation.kind!=='frame_image_sha256'||!SHA256.test(expectation.expected_sha256??''))
+  throw new Error('R196 unsupported desktop postcondition expectation');
+ return Object.freeze({kind:expectation.kind,expected_sha256:expectation.expected_sha256});
+}
+
+// An input injection receipt is not evidence that the application accepted it.
+// This verifier only establishes the explicit observable postcondition.
+export function evaluateDesktopPostcondition({expectation=null,beforeFrame,afterFrame}={}){
+ if(!beforeFrame||!afterFrame||!SHA256.test(beforeFrame.image_sha256??'')||
+    !SHA256.test(afterFrame.image_sha256??'')||!SHA256.test(beforeFrame.frame_id??'')||
+    !SHA256.test(afterFrame.frame_id??''))throw new Error('R196 desktop frames invalid');
+ const base={schema:'deadbyte.desktop-postcondition.v1',
+  before_frame_id:beforeFrame.frame_id,after_frame_id:afterFrame.frame_id,
+  before_image_sha256:beforeFrame.image_sha256,after_image_sha256:afterFrame.image_sha256};
+ if(expectation===null)return Object.freeze({...base,status:'unknown',reason:'no_explicit_expectation',kind:null,expected_sha256:null});
+ const verified=validateDesktopPostconditionExpectation(expectation);
+ const expected=verified.expected_sha256;
+ if(beforeFrame.image_sha256===expected)
+  return Object.freeze({...base,status:'unknown',reason:'expected_state_already_present_before_action',
+   kind:expectation.kind,expected_sha256:expected});
+ return Object.freeze({...base,status:afterFrame.image_sha256===expected?'satisfied':'unsatisfied',
+  reason:afterFrame.image_sha256===expected?'exact_post_image_observed':'post_image_differs_from_expected',
+  kind:expectation.kind,expected_sha256:expected});
+}

package/src/desktop-runtime-r40.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { canonicalJson } from './canonical-json.mjs';
 import { createDesktopAction,createDesktopTarget,guardDesktopAction,bindDesktopPostObservation,bindDesktopActionChain } from './desktop-contract.mjs';
 import { effectIdentity,bindEffectCompletion } from './effect-ledger.mjs';
+import { evaluateDesktopPostcondition,validateDesktopPostconditionExpectation } from './desktop-postcondition-r196.mjs';
+import { bindUiaElementR199,assertFreshUiaElementR199 } from './desktop-uia-identity-r199.mjs';
 import { DESKTOP_ACTION_KINDS,DESKTOP_POLICY_SCHEMA,assertDesktopArmed,desktopSessionStatus } from './desktop-policy-r40.mjs';
 
 export const DESKTOP_RECEIPT_SCHEMA='deadbyte.desktop-receipt.v1';
@@ -82,6 +84,8 @@ export function createDesktopRuntime({
   insist(Number.isInteger(maxTargets)&&maxTargets>=1&&maxTargets<=1024,'maxTargets invalid');
   const receiptPublicKey=publicKey??createPublicKey(privateKey);
   const targets=new Map();
+  const groundedTargets=new Set();
+  const uiaBindings=new Map();
 
   async function receipt(kind,payload,stamp=now()){
     return writeReceipt({policy,privateKey,keyId,evidenceDir,kind,payload,nowUtc:stamp});
@@ -193,15 +197,29 @@ export function createDesktopRuntime({
     const confidence=grounded.query_kind==='name_contains'?0.98:1;
     const created=createDesktopTarget({
       frame:fresh.frame,rect:candidate.rect,source:'uia',confidence,
-      semanticLabelSha256:grounded.query_sha256,windowBinding:fresh.frame.active_window
+      // Hash the ephemeral native identity into the target handle to prevent
+      // old and new elements at identical coordinates sharing one target_id.
+      semanticLabelSha256:Array.isArray(candidate.runtime_id)&&candidate.runtime_id.length>0
+        ?sha256Object({query_sha256:grounded.query_sha256,runtime_id:candidate.runtime_id})
+        :grounded.query_sha256,
+      windowBinding:fresh.frame.active_window
     });
     targets.set(created.target_id,created);
-    while(targets.size>maxTargets)targets.delete(targets.keys().next().value);
+    groundedTargets.add(created.target_id);
+    if(candidate.runtime_id!==null&&candidate.runtime_id!==undefined){
+      const binding=bindUiaElementR199({frame:fresh.frame,grounded,candidate,query});
+      uiaBindings.set(created.target_id,binding);
+    }
+    while(targets.size>maxTargets){
+      const removed=targets.keys().next().value;
+      targets.delete(removed);groundedTargets.delete(removed);uiaBindings.delete(removed);
+    }
     const evidence=await receipt('desktop_grounding',{
       requested_frame_id:expected.frame_id,grounded_frame_id:fresh.frame.frame_id,
       target_id:created.target_id,query_sha256:grounded.query_sha256,query_kind:grounded.query_kind,
       ordinal:grounded.ordinal,match_count:grounded.matches.length,visited:grounded.visited,truncated:grounded.truncated,
-      provider_receipt_sha256:grounded.provider_receipt_sha256,control_type:candidate.control_type
+      provider_receipt_sha256:grounded.provider_receipt_sha256,control_type:candidate.control_type,
+      element_token_sha256:uiaBindings.get(created.target_id)?.token_sha256??null
     },fresh.frame.observed_at_utc);
     return Object.freeze({
       status:'ok',frame:fresh.frame,target:created,
@@ -209,15 +227,18 @@ export function createDesktopRuntime({
         query_sha256:grounded.query_sha256,query_kind:grounded.query_kind,ordinal:grounded.ordinal,
         match_count:grounded.matches.length,visited:grounded.visited,truncated:grounded.truncated,
         control_type:candidate.control_type,provider_receipt_sha256:grounded.provider_receipt_sha256,
+        element_token_sha256:uiaBindings.get(created.target_id)?.token_sha256??null,
         receipt_id:evidence.receipt_id,receipt_sha256:evidence.receipt_sha256
       })
     });
   }
   async function action({
     intentId,kind,expectedFrameId,targetId=null,expectedWindow=undefined,point=null,
-    scrollDelta=null,keyChord=null,text=null,effectContext=null
+    scrollDelta=null,keyChord=null,text=null,effectContext=null,expectedPostcondition=null
   }={}){
     insist(DESKTOP_ACTION_KINDS.includes(kind),'desktop action kind invalid');
+    const postconditionExpectation=validateDesktopPostconditionExpectation(expectedPostcondition);
+    const expectedPostconditionSha256=postconditionExpectation?sha256Object(postconditionExpectation):null;
     const authority=await assertDesktopArmed(policy,kind);
     if(kind==='text_input'){
       insist(typeof text==='string','desktop text input invalid');
@@ -243,6 +264,15 @@ export function createDesktopRuntime({
     // bind it to the same fresh desktop/topology/foreground identity and let the native helper
     // revalidate HWND/PID immediately before SendInput instead of requiring unrelated pixels to freeze.
     if(kind!=='key_chord') insist(pre.frame.image_sha256===expected.image_sha256,'desktop pixels changed before action');
+    // Before any injection, reacquire the same UIA element through a fresh
+    // query bound to the current foreground window and runtime identity.
+    if(chosenTarget&&groundedTargets.has(chosenTarget.target_id)){
+      const identity=uiaBindings.get(chosenTarget.target_id);
+      insist(identity,'R199 UIA target has no RuntimeId binding and is not actionable');
+      insist(typeof grounderProvider==='function','R199 UIA re-ground provider unavailable');
+      const refreshed=await grounderProvider({frame:pre.frame,query:identity.query});
+      assertFreshUiaElementR199(identity,refreshed);
+    }
 
     let actionPoint=point;
     if(chosenTarget&&['pointer_move','click_primary','click_secondary','double_click_primary','scroll'].includes(kind)){
@@ -260,7 +290,8 @@ export function createDesktopRuntime({
     const effectAction=Object.freeze({
       kind:`desktop_${kind}`,action_sha256:actionObject.action_sha256,frame_id:pre.frame.frame_id,
       target_id:actionObject.target_id,point:actionObject.point,scroll_delta:actionObject.scroll_delta,
-      key_chord:actionObject.key_chord,text_sha256:actionObject.text_sha256
+      key_chord:actionObject.key_chord,text_sha256:actionObject.text_sha256,
+      ...(expectedPostconditionSha256?{expected_postcondition_sha256:expectedPostconditionSha256}:{})
     });
     const ctx=effectContext??{};
     const effectLedger=effectIdentity({
@@ -272,7 +303,8 @@ export function createDesktopRuntime({
       intent_id:intentId,kind,expected_frame_id:expected.frame_id,pre_frame_id:pre.frame.frame_id,
       target_id:chosenTarget?.target_id??null,action_sha256:actionObject.action_sha256,
       guard_sha256:guarded.guard_sha256,authority_instance_nonce:authority.instance_nonce,
-      effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint
+      effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,
+      expected_postcondition_sha256:expectedPostconditionSha256
     });
 
     let effect;
@@ -303,6 +335,9 @@ export function createDesktopRuntime({
     try{
       const post=await observerRuntime.capture();
       const bound=bindDesktopPostObservation({guard:guarded,beforeFrame:pre.frame,action:actionObject,afterFrame:post.frame});
+      const postcondition=evaluateDesktopPostcondition({expectation:postconditionExpectation,
+        beforeFrame:pre.frame,afterFrame:post.frame});
+      const postconditionSha256=sha256Object(postcondition);
       const postEvidence=await receipt('desktop_post_observation',{
         started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
         effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,
@@ -329,11 +364,13 @@ export function createDesktopRuntime({
         action_sha256:actionObject.action_sha256,guard_sha256:guarded.guard_sha256,
         effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,effect_completion:effectCompletion,
         effect:{injected:true,side_effect_state:'confirmed_injected',provider_receipt_sha256:HEX64.test(effect.provider_receipt_sha256??'')?effect.provider_receipt_sha256:null},
-        action_chain:chain,post_observation:bound
+        action_chain:chain,post_observation:bound,
+        postcondition,postcondition_sha256:postconditionSha256
       },post.frame.observed_at_utc);
       return Object.freeze({
         status:'ok',injected:true,task_success:null,side_effect_state:'confirmed_injected',
         action:actionObject,guard:guarded,post_observation:bound,action_chain:chain,
+        postcondition,postcondition_sha256:postconditionSha256,
         effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,effect_completion:effectCompletion,
         started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
         post_receipt_id:postEvidence.receipt_id,post_receipt_sha256:postEvidence.receipt_sha256,

package/src/desktop-uia-identity-r199.mjs

@@ -0,0 +1,51 @@
+import {createHash} from 'node:crypto';
+import {canonicalJson} from './canonical-json.mjs';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const sha=value=>createHash('sha256').update(canonicalJson(value),'utf8').digest('hex');
+function insist(ok,message){if(!ok)throw new Error(message);}
+export function normalizeUiaRuntimeIdR199(value){
+ insist(Array.isArray(value)&&value.length>=1&&value.length<=64,'R199 UIA RuntimeId missing or unbounded');
+ insist(value.every(x=>Number.isInteger(x)&&x>=-2147483648&&x<=2147483647),
+   'R199 UIA RuntimeId component invalid');
+ return Object.freeze([...value]);
+}
+function eqArray(a,b){return a.length===b.length&&a.every((v,i)=>v===b[i]);}
+function eqRect(a,b){return ['left','top','width','height'].every(k=>a?.[k]===b?.[k]);}
+export function bindUiaElementR199({frame,grounded,candidate,query}={}){
+ insist(frame?.frame_id&&HEX64.test(frame.frame_id),'R199 UIA frame identity missing');
+ insist(typeof grounded?.query_sha256==='string'&&HEX64.test(grounded.query_sha256),'R199 UIA query hash invalid');
+ insist(grounded.truncated===false,'R199 UIA scan truncated');
+ const runtimeId=normalizeUiaRuntimeIdR199(candidate?.runtime_id);
+ insist(candidate.enabled===true&&!candidate.offscreen,'R199 UIA element not actionable');
+ const q=Object.freeze({
+   kind:query.kind,value:query.value,
+   max_results:query.max_results??8,ordinal:query.ordinal??0
+ });
+ const tokenSha256=sha({schema:'deadbyte.uia-element-binding-r199.v1',
+   frame_id:frame.frame_id,desktop_epoch:frame.desktop_epoch,
+   active_window:frame.active_window,query_sha256:grounded.query_sha256,
+   runtime_id:runtimeId,control_type:candidate.control_type,rect:candidate.rect});
+ return Object.freeze({
+   schema:'deadbyte.uia-element-binding-r199.v1',
+   query:q,query_sha256:grounded.query_sha256,ordinal:grounded.ordinal,
+   runtime_id:runtimeId,control_type:candidate.control_type,
+   rect:Object.freeze({...candidate.rect}),token_sha256:tokenSha256
+ });
+}
+export function assertFreshUiaElementR199(binding,grounded){
+ insist(binding?.schema==='deadbyte.uia-element-binding-r199.v1','R199 UIA binding missing');
+ insist(grounded?.status==='ok'&&grounded.truncated===false,'R199 UIA reground scan invalid or incomplete');
+ insist(grounded.query_sha256===binding.query_sha256 &&
+   grounded.ordinal===binding.ordinal,'R199 UIA query identity changed');
+ insist(Array.isArray(grounded.matches)&&binding.ordinal<grounded.matches.length,
+   'R199 UIA stale target no longer found');
+ const candidate=grounded.matches[binding.ordinal];
+ const current=normalizeUiaRuntimeIdR199(candidate?.runtime_id);
+ insist(eqArray(binding.runtime_id,current),'R199 UIA element identity changed');
+ insist(candidate.control_type===binding.control_type&&candidate.enabled===true&&!candidate.offscreen,
+   'R199 UIA control state changed');
+ insist(eqRect(candidate.rect,binding.rect),'R199 UIA element rectangle changed');
+ return Object.freeze({token_sha256:binding.token_sha256,
+   runtime_id_sha256:sha(current),verified:true});
+}

package/src/desktop-uia-r40.mjs

@@ -73,10 +73,18 @@ export function parseDesktopUiaResponse(bytes,{expectedWindow,query,expectedBoun
     };
     const inside=rect.left>=left&&rect.top>=top&&rect.left+rect.width<=left+width&&rect.top+rect.height<=top+height;
     if(!inside) continue;
+    let runtimeId=null;
+    if(item.runtime_id!==undefined){
+      insist(Array.isArray(item.runtime_id)&&item.runtime_id.length<=64,'desktop UIA RuntimeId shape invalid');
+      if(item.runtime_id.length===0)insist(q.kind==='root','desktop UIA RuntimeId missing for non-root');
+      else runtimeId=Object.freeze(item.runtime_id.map(v=>
+        integer(v,'desktop UIA RuntimeId component',{min:-2147483648,max:2147483647})));
+    }
     matches.push(Object.freeze({
       rect:Object.freeze(rect),
       control_type:integer(item.control_type,'desktop UIA control_type',{min:0,max:100000}),
-      enabled:item.enabled===true,offscreen:item.offscreen===true
+      enabled:item.enabled===true,offscreen:item.offscreen===true,
+      runtime_id:runtimeId
     }));
   }
   return Object.freeze({

package/src/machine-fs-handle-read-r196.mjs

@@ -0,0 +1,43 @@
+import {createHash} from 'node:crypto';
+
+function sameMetadata(a,b){
+ return a.dev===b.dev&&a.ino===b.ino&&a.size===b.size&&
+  a.mtimeNs===b.mtimeNs&&a.ctimeNs===b.ctimeNs;
+}
+
+// Hash bytes through the same open FileHandle used for the range read.
+// This does not prove that the pathname was safe before open, or that
+// concurrent in-place writes cannot alter data between individual reads.
+export async function readRangeFromHandle(handle,{offset,length,hashFile=false,signal}){
+ if(!handle||typeof handle.read!=='function'||typeof handle.stat!=='function'||
+    typeof handle.createReadStream!=='function')throw new TypeError('R196 requires a live FileHandle');
+ if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(length)||length<0||length>4194304)
+  throw new RangeError('R196 invalid bounded file range');
+ const before=await handle.stat({bigint:true});
+ if(!before.isFile())throw new Error('R196 read requires a regular file');
+ if(before.size>BigInt(Number.MAX_SAFE_INTEGER))throw new Error('R196 file size exceeds safe integer');
+ const fileSize=Number(before.size);
+ if(offset>fileSize)throw new Error('R196 offset exceeds opened file size');
+ const buffer=Buffer.alloc(Math.min(length,fileSize-offset));
+ const read=buffer.length?await handle.read(buffer,0,buffer.length,offset):{bytesRead:0};
+ let digest=null;
+ if(hashFile){
+  const hash=createHash('sha256');
+  await new Promise((resolve,reject)=>{
+   const stream=handle.createReadStream({start:0,autoClose:false,signal});
+   stream.on('data',chunk=>hash.update(chunk));
+   stream.once('error',reject);
+   stream.once('end',resolve);
+  });
+  digest=hash.digest('hex');
+ }
+ const after=await handle.stat({bigint:true});
+ if(!sameMetadata(before,after))throw new Error('R196 opened file changed during read/hash');
+ return {
+  schema:'deadbyte.machine-fs-read-worker.v1',
+  bytes_read:read.bytesRead,
+  data_base64:buffer.subarray(0,read.bytesRead).toString('base64'),
+  file_sha256:digest,file_size:fileSize,
+  file_dev:String(before.dev),file_ino:String(before.ino)
+ };
+}

package/src/machine-fs-native-read-r197.mjs

@@ -0,0 +1,73 @@
+import {createHash} from 'node:crypto';
+import {lstat,readFile} from 'node:fs/promises';
+import {spawn} from 'node:child_process';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {validatePortableRelativePath} from './path-policy.mjs';
+
+const SHA=/^[0-9a-f]{64}$/;
+const DECIMAL=/^(?:0|[1-9][0-9]{0,19})$/;
+const EXECUTABLE=fileURLToPath(new URL('../bin/deadbyte-fs-read-r197-fixed.exe',import.meta.url));
+export const R197_NATIVE_READ_EXE_SHA256='7477ca3d94168c8b75711b734df5b9c20a43ecbd9338cfc234700d7e27982b63';
+const hash=b=>createHash('sha256').update(b).digest('hex');
+let pinnedInfo=null;
+async function verifyExecutable(){
+ const info=await lstat(EXECUTABLE);
+ if(!info.isFile()||info.isSymbolicLink()||info.size<1024||info.size>4*1024*1024)
+  throw new Error('R197 native file reader binary is not a regular bounded executable');
+ // Only a trust-state fast path, NOT a general same-user tamper sandbox.
+ const current=hash(await readFile(EXECUTABLE));
+ if(current!==R197_NATIVE_READ_EXE_SHA256)throw new Error('R197 native reader executable SHA-256 mismatch');
+ pinnedInfo={sha256:current,bytes:info.size};
+ return pinnedInfo;
+}
+export async function boundedNativeReadR197({rootPath,relativePath,offset,length,hashFile=false,timeoutMs=30000}={}){
+ if(process.platform!=='win32')throw new Error('R197 native root-relative reader requires Windows');
+ if(typeof rootPath!=='string'||!path.win32.isAbsolute(rootPath)||!path.isAbsolute(rootPath))
+  throw new Error('R197 native root path invalid');
+ validatePortableRelativePath(relativePath);
+ if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(length)||length<0||length>4*1024*1024)
+  throw new Error('R197 native bounded range invalid');
+ if(!Number.isInteger(timeoutMs)||timeoutMs<100||timeoutMs>180000)
+  throw new Error('R197 native timeout invalid');
+ await verifyExecutable();
+ return await new Promise((resolve,reject)=>{
+  const args=[rootPath,relativePath,String(offset),String(length),hashFile?'1':'0'];
+  const child=spawn(EXECUTABLE,args,{windowsHide:true,shell:false,stdio:['ignore','pipe','pipe']});
+  const chunks=[];let byteCount=0,stderr='',settled=false,timer=null;
+  const finish=(error,value)=>{
+   if(settled)return;
+   settled=true;if(timer!==null)clearTimeout(timer);
+   error?reject(error):resolve(value);
+  };
+  child.stdout.on('data',chunk=>{
+   byteCount+=chunk.length;
+   if(byteCount>8*1024*1024){child.kill();finish(new Error('R197 native read stdout exceeds bound'));return;}
+   chunks.push(Buffer.from(chunk));
+  });
+  child.stderr.on('data',chunk=>{
+   stderr=(stderr+chunk.toString('utf8')).slice(-16384);
+  });
+  child.on('error',error=>finish(error));
+  child.on('close',(code,signal)=>{
+   if(settled)return;
+   if(code!==0)return finish(new Error('R197 native root-relative read refused exit='+code+' signal='+(signal??'none')+' '+stderr.slice(-512)));
+   let response;
+   try{response=JSON.parse(Buffer.concat(chunks).toString('utf8'));}
+   catch{return finish(new Error('R197 native read response invalid JSON'));}
+   const data=typeof response?.data_base64==='string'?Buffer.from(response.data_base64,'base64'):null;
+   if(response?.schema!=='deadbyte.machine-fs-read-worker.v1'||!data||
+      response.bytes_read!==data.length||data.length>length||
+      !Number.isSafeInteger(response.file_size)||!DECIMAL.test(response.file_dev??'')||
+      !DECIMAL.test(response.file_ino??'')||
+      (hashFile?!SHA.test(response.file_sha256??''):response.file_sha256!==null))
+    return finish(new Error('R197 native read response contract mismatch'));
+   return finish(null,response);
+  });
+  timer=setTimeout(()=>{
+   child.kill();
+   finish(new Error('R197 native read timed out after '+timeoutMs+'ms'));
+  },timeoutMs);
+  timer.unref?.();
+ });
+}

package/src/machine-fs-native-read-r198.mjs

@@ -0,0 +1,76 @@
+import {createHash} from 'node:crypto';
+import {lstat,readFile} from 'node:fs/promises';
+import {spawn} from 'node:child_process';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {validatePortableRelativePath} from './path-policy.mjs';
+
+const SHA=/^[0-9a-f]{64}$/;
+const DECIMAL=/^(?:0|[1-9][0-9]{0,19})$/;
+const EXECUTABLE=fileURLToPath(new URL('../bin/deadbyte-fs-read-r198.exe',import.meta.url));
+export const R198_NATIVE_READ_EXE_SHA256='4325ae4f033bba195b34d2c49b48493a1a468f3443e369a9bb887a7a129eac16';
+const hash=b=>createHash('sha256').update(b).digest('hex');
+let pinnedInfo=null;
+async function verifyExecutable(){
+ const info=await lstat(EXECUTABLE);
+ if(!info.isFile()||info.isSymbolicLink()||info.size<1024||info.size>4*1024*1024)
+  throw new Error('R198 native file reader binary is not a regular bounded executable');
+ // Only a trust-state fast path, NOT a general same-user tamper sandbox.
+ const current=hash(await readFile(EXECUTABLE));
+ if(current!==R198_NATIVE_READ_EXE_SHA256)throw new Error('R198 native reader executable SHA-256 mismatch');
+ pinnedInfo={sha256:current,bytes:info.size};
+ return pinnedInfo;
+}
+export async function boundedNativeReadR198({rootPath,relativePath,offset,length,hashFile=false,timeoutMs=30000,expectedRootDev,expectedRootIno}={}){
+ if(process.platform!=='win32')throw new Error('R198 native root-relative reader requires Windows');
+ if(typeof rootPath!=='string'||!path.win32.isAbsolute(rootPath)||!path.isAbsolute(rootPath))
+  throw new Error('R198 native root path invalid');
+ validatePortableRelativePath(relativePath);
+ if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(length)||length<0||length>4*1024*1024)
+  throw new Error('R198 native bounded range invalid');
+ if(!Number.isInteger(timeoutMs)||timeoutMs<100||timeoutMs>180000)
+  throw new Error('R198 native timeout invalid');
+ if(typeof expectedRootDev!=='string'||!DECIMAL.test(expectedRootDev)||
+    typeof expectedRootIno!=='string'||!DECIMAL.test(expectedRootIno)||expectedRootIno==='0')
+  throw new Error('R198 expected root identity missing or invalid');
+ await verifyExecutable();
+ return await new Promise((resolve,reject)=>{
+  const args=[rootPath,relativePath,String(offset),String(length),hashFile?'1':'0',expectedRootDev,expectedRootIno];
+  const child=spawn(EXECUTABLE,args,{windowsHide:true,shell:false,stdio:['ignore','pipe','pipe']});
+  const chunks=[];let byteCount=0,stderr='',settled=false,timer=null;
+  const finish=(error,value)=>{
+   if(settled)return;
+   settled=true;if(timer!==null)clearTimeout(timer);
+   error?reject(error):resolve(value);
+  };
+  child.stdout.on('data',chunk=>{
+   byteCount+=chunk.length;
+   if(byteCount>8*1024*1024){child.kill();finish(new Error('R198 native read stdout exceeds bound'));return;}
+   chunks.push(Buffer.from(chunk));
+  });
+  child.stderr.on('data',chunk=>{
+   stderr=(stderr+chunk.toString('utf8')).slice(-16384);
+  });
+  child.on('error',error=>finish(error));
+  child.on('close',(code,signal)=>{
+   if(settled)return;
+   if(code!==0)return finish(new Error('R198 native root-relative read refused exit='+code+' signal='+(signal??'none')+' '+stderr.slice(-512)));
+   let response;
+   try{response=JSON.parse(Buffer.concat(chunks).toString('utf8'));}
+   catch{return finish(new Error('R198 native read response invalid JSON'));}
+   const data=typeof response?.data_base64==='string'?Buffer.from(response.data_base64,'base64'):null;
+   if(response?.schema!=='deadbyte.machine-fs-read-worker.v1'||!data||
+      response.bytes_read!==data.length||data.length>length||
+      !Number.isSafeInteger(response.file_size)||!DECIMAL.test(response.file_dev??'')||
+      !DECIMAL.test(response.file_ino??'')||
+      (hashFile?!SHA.test(response.file_sha256??''):response.file_sha256!==null))
+    return finish(new Error('R198 native read response contract mismatch'));
+   return finish(null,response);
+  });
+  timer=setTimeout(()=>{
+   child.kill();
+   finish(new Error('R198 native read timed out after '+timeoutMs+'ms'));
+  },timeoutMs);
+  timer.unref?.();
+ });
+}

package/src/machine-fs-read-worker.mjs

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
-import { createReadStream, promises as fs } from 'node:fs';
+import { promises as fs } from 'node:fs';
+import { readRangeFromHandle } from './machine-fs-handle-read-r196.mjs';
 
 const [file, offsetText, lengthText, hashText] = process.argv.slice(2);
 const offset = Number(offsetText);
@@ -13,33 +13,13 @@ if (typeof file !== 'string' || !Number.isSafeInteger(offset) || offset < 0 ||
 
 try {
   const handle = await fs.open(file, 'r');
-  let bytes;
+  let result;
   try {
-    const buffer = Buffer.alloc(length);
-    const result = length ? await handle.read(buffer, 0, length, offset) : { bytesRead: 0 };
-    bytes = buffer.subarray(0, result.bytesRead);
+    result = await readRangeFromHandle(handle,{offset,length,hashFile:hashText==='1'});
   } finally {
     await handle.close();
   }
-
-  let fileSha256 = null;
-  if (hashText === '1') {
-    const hash = createHash('sha256');
-    await new Promise((resolve, reject) => {
-      const stream = createReadStream(file);
-      stream.on('data', chunk => hash.update(chunk));
-      stream.once('error', reject);
-      stream.once('end', resolve);
-    });
-    fileSha256 = hash.digest('hex');
-  }
-
-  process.stdout.write(JSON.stringify({
-    schema: 'deadbyte.machine-fs-read-worker.v1',
-    bytes_read: bytes.length,
-    data_base64: bytes.toString('base64'),
-    file_sha256: fileSha256
-  }));
+  process.stdout.write(JSON.stringify(result));
 } catch (error) {
   process.stderr.write(String(error?.stack ?? error));
   process.exit(1);