coding-artifact-evaluation-shell 0.0.0-stage → 0.1.0-eidolon.a1b37cbcd7c07

package/contract.ts

@@ -0,0 +1,116 @@
+/** Stable data/effect boundary. No product, vendor or IO dependencies. */
+export const POLICY = 'artifact-evaluation/v1';
+export type Judgment = 'pass' | 'fail' | 'indeterminate';
+export type FailureClass = 'business' | 'infrastructure' | 'protocol-cost' | 'scope-unresolved';
+export interface Source {
+  id: string; path: string; digest: string; content: string;
+  authority: 'original' | 'confirmed' | 'commitment' | 'inferred';
+}
+export interface Obligation {
+  id: string; sourceId: string; quote: string; expectation: string; rationale: string;
+  relation: 'leaf' | 'all' | 'any' | 'conditional'; children: string[];
+  condition: 'applicable' | 'not-applicable' | 'unresolved';
+}
+export interface Observation {
+  id: string; runId: string; artifactDigest: string; phase: 'observation';
+  channel: 'process' | 'browser' | 'http' | 'file'; method: string; conditions: string;
+  content: string; contentDigest: string; bytes: number; elapsedMs: number;
+  status: 'completed' | 'interrupted' | 'infrastructure-failed';
+  exitCode?: number; argv?: string[]; limitations: string[];
+  /** Owner-written provenance; absent on historical delivery observations. */
+  purpose?: 'delivery' | 'setup' | 'target';
+  environment?: {
+    process?: {network:'denied'|'loopback-only'; writes:'scratch-only'|'isolated-derived'; cwd:string;sourceRoot?:string;derivedDirectories?:string[]};
+    http?: {origin:string; method:string; path:string; serviceId?:string; authorization:'absent'|'present-redacted'; body?:unknown};
+  };
+}
+export interface CoverageItem {id:string;sourceId:string;quote:string;expectation:string;mode:'inspection'|'execution'}
+export interface CoverageReport {
+  items:CoverageItem[]; reviewedSourceIds:string[]; checkpointed:boolean;
+  links:{itemId:string;observationIds:string[]}[];
+  unavailable?:{itemId:string;reason:string}[];
+  gaps:{itemId:string;reason:string}[];
+  supplement:'not-needed'|'attempted'|'budget-unavailable'|'capability-unavailable'|'fenced'; semanticAuthority:false;
+}
+export interface Claim {
+  obligationId: string; judgment: Judgment; semanticExpectation: string;
+  method: string; conditions: string; reasoning: string; limitations: string[];
+  evidence: { observationId: string; excerpt: string; supports: string; complete?:true }[];
+  /** Required for business FAIL from restricted, nonzero process execution. */
+  preconditions?: {status:'established'|'unresolved'|'incompatible';reasoning:string;evidenceIds:string[]};
+}
+export interface Finding { id: string; obligationIds: string[]; description: string }
+export interface Proposal {
+  judgment: Judgment; obligations: Obligation[]; claims: Claim[]; findings: Finding[];
+  sourceReviews: { sourceId: string; complete: boolean; omissions: string[]; ambiguities: string[] }[];
+  needReviews?: {needId:string;disposition:'addressed'|'unresolved'|'not-required';obligationIds:string[];reasoning:string}[];
+}
+export interface Diagnostic { rule: string; location: string; message: string; repairable: boolean }
+export interface EvidenceRequest {id:string;sourceId:string;quote:string;expectation:string;missingEvidence:string;observationIds:string[]}
+export interface EvidenceFeedback {format:'evidence-request-v1';requests:EvidenceRequest[]}
+/** Owner handles survive repeated model-local request labels and fresh contexts. */
+export interface EvidenceNeed extends EvidenceRequest {needId:string;round:number}
+export interface Usage { input: number; cached: number; output: number }
+/** Owner-selected window INSIDE the original evaluation clock, never a new budget. */
+export interface ModelWindow {kind:'initial-collection'|'sufficiency-review'|'supplement'|'candidate-review';deadlineAt:number;finalReviewDeadlineAt:number;finalReviewReserveMs:number}
+export interface Invocation {
+  id: string; phase: 'judgment' | 'preparation' | 'representation-repair' | 'counter-review';
+  elapsedMs: number; usage: Usage | null; completed: boolean; model: string; effort: string | null;
+  window?:ModelWindow; outcome?:'phase-cutoff';
+}
+export interface EvaluationInput {
+  runId: string; artifactDigest: string; sources: Source[]; observations: Observation[];
+  /** Caller-owned targets, never inferred from the artifact's completion statements. */
+  obligations?: Obligation[];
+  coverage?:CoverageReport;
+  needs?:EvidenceNeed[];
+  executionContext?: {artifactRoot:string;artifactWrites:'denied';processNetwork:'denied'|'loopback-only';processWrites:'scratch-only'|'isolated-derived';executionRoot?:string;derivedDirectories?:string[];origins:Record<string,string>};
+}
+export interface EvaluationConfig { policyVersion: string; includeCommitments: boolean }
+export interface Decision {
+  schemaVersion: 1; policyVersion: string; runId: string; artifactDigest: string;
+  execution: 'completed' | 'interrupted' | 'infrastructure-failed'; judgment: Judgment;
+  failureClass: FailureClass | null; proposal: Proposal | null; observations: Observation[];
+  diagnostics: Diagnostic[]; invocations: Invocation[];
+}
+export interface JudgePort {
+  judge(input: EvaluationInput, repair?: { proposal: Proposal; diagnostics: Diagnostic[] }): Promise<Proposal>;
+  invocations(): Invocation[];
+  /** Independent sufficiency feedback while the native lease is still alive. */
+  review?(input:EvaluationInput,canSupplement:boolean,window?:ModelWindow):Promise<Proposal|EvidenceFeedback>;
+}
+export interface EvaluationRuntime { judge: JudgePort; record(event: unknown): void }
+export interface ProcessProbe { argv: string[]; conditions: string; timeoutMs?: number;cwd?:string }
+export interface BrowserProbe { op: string; args: unknown[]; conditions: string }
+/** Trusted caller declares execution capabilities, never business answers. */
+export interface ServiceSpec {
+  argv:string[]; portEnv:string; dataEnv:string[]; readyPath:string; readyTimeoutMs?:number;
+  cwd?:string; dataFiles?:Record<string,string>;
+}
+/** Native launch facts, not an application claim or semantic verdict. */
+export interface ServiceLaunchReceipt {
+  leaseId:string;pid:number|undefined;origin:string;data:string;argv:string[];cwd:string;generation:number;
+  environment:Record<string,string>;state:{directory:string;initiallyEmpty:true};
+  readiness:{path:string;status:number};semanticPass:false;elapsedMs:number;
+}
+export interface OwnedServiceCommand {serviceId:string;argv:string[];cwd?:string}
+export interface ServiceNode extends ServiceSpec {id:string;links?:Record<string,string>}
+export interface ServiceGraph {entry:string;nodes:ServiceNode[]}
+export interface RuntimeSpec {
+  /** Explicit tool aliases and readonly dependency roots. Never inferred by the judge. */
+  executables?:Record<string,string>; readPaths?:string[]; environment?:Record<string,string>;
+}
+export interface HttpProbe {method:'GET'|'POST'|'PUT'|'PATCH'|'DELETE';path:string;body?:unknown;headers?:Record<string,string>;conditions:string;serviceId?:string}
+export interface FileProbe {path:string;conditions:string}
+export interface Manifest {
+  artifact: string; targets: {id: string; path: string; authority: Source['authority']}[];
+  obligations?: Obligation[]; process?: ProcessProbe[];
+  browser?: {entry?: string; probes: BrowserProbe[]}; includeCommitments?: boolean;
+  service?:ServiceSpec; http?:HttpProbe[];
+  services?:ServiceGraph; runtime?:RuntimeSpec;
+  /** Native-owned copy; only derived outputs are writable, historical inputs stay protected. */
+  execution?:{workspace:'isolated-copy';network:'denied'|'loopback-only';derivedDirectories?:string[]};
+  files?:FileProbe[];
+  /** A bounded observer chooses actions from originals, never from historical findings. */
+  agentObservation?:{maxActions:number;allowServiceRestart?:boolean};
+}

package/counter-review.ts

@@ -0,0 +1,74 @@
+import type {Decision,EvaluationConfig,EvaluationInput,Invocation,Proposal} from './contract';
+import {admit} from './logic';
+import {canonicalIdentity} from './representation';
+import {decodeProposal,JudgeProtocolError} from './proposal';
+import {observationRef,resolveObservation} from './native-references';
+import {isDeliveryFact} from './coverage';
+
+/** Experimental second interpretation, never observation/requirement authority. */
+export interface CounterReview {
+  disposition:'uphold'|'challenge'|'unresolved';
+  reason:string;
+  sourceIds:string[];
+  observationRefs:string[];
+  replacement?:Proposal;
+}
+export interface CounterReviewResult {
+  candidate:Decision;
+  review:CounterReview|null;
+  decision:Decision;
+  resolution:'not-required'|'upheld'|'challenged'|'replacement-failure'|'unavailable';
+}
+
+export function eligibleCandidate(input:EvaluationInput,candidate:Decision,config:EvaluationConfig):boolean {
+  if(candidate.runId!==input.runId||candidate.artifactDigest!==input.artifactDigest||candidate.policyVersion!==config.policyVersion||canonicalIdentity(candidate.observations)!==canonicalIdentity(input.observations))throw new JudgeProtocolError('Counter-review requires the exact candidate identity, policy and observations');
+  return candidate.execution==='completed'&&candidate.diagnostics.length===0&&candidate.judgment!=='indeterminate'&&!!candidate.proposal&&candidate.proposal.judgment===candidate.judgment&&admit(input,candidate.proposal,config).length===0;
+}
+
+/** Remove only full duplicate bodies; all semantic choices remain explicit. */
+export function counterCandidateView(input:EvaluationInput,candidate:Decision,config:EvaluationConfig) {
+  if(!eligibleCandidate(input,candidate,config))throw new JudgeProtocolError('Only an admitted definitive candidate can be counter-reviewed');
+  const p=candidate.proposal!;
+  const reference=(id:string)=>observationRef(input.observations.findIndex(o=>o.id===id));
+  return {...p,obligations:p.obligations.map(({quote,...o})=>({...o,...(quote===input.sources.find(s=>s.id===o.sourceId)?.content?{wholeSource:true}:{quote})})),
+    claims:p.claims.map(c=>({...c,...(c.preconditions?{preconditions:{...c.preconditions,evidenceIds:c.preconditions.evidenceIds.map(reference)}}:{}),evidence:c.evidence.map(({observationId,excerpt,...e})=>{
+      const index=input.observations.findIndex(o=>o.id===observationId);
+      return {...e,observationRef:observationRef(index),...(excerpt===input.observations[index]!.content?{wholeObject:true}:{excerpt})};
+    })})),
+  };
+}
+
+export function decodeCounterReview(input:EvaluationInput,candidate:Decision,value:unknown,config:EvaluationConfig):CounterReview {
+  if(!eligibleCandidate(input,candidate,config))throw new JudgeProtocolError('Counter-review candidate is not eligible');
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new JudgeProtocolError('Counter-review must be an object');
+  const v=value as Record<string,unknown>;
+  const strings=(x:unknown):x is string[]=>Array.isArray(x)&&x.every(s=>typeof s==='string'&&!!s.trim())&&new Set(x).size===x.length;
+  if(Object.keys(v).some(k=>!['disposition','reason','sourceIds','observationRefs','replacement'].includes(k))||!['uphold','challenge','unresolved'].includes(v.disposition as string)||typeof v.reason!=='string'||!v.reason.trim()||!strings(v.sourceIds)||!v.sourceIds.length||!strings(v.observationRefs))throw new JudgeProtocolError('Counter-review needs disposition, reason, sourceIds and observationRefs');
+  const required=input.sources.filter(s=>s.authority==='original'||s.authority==='confirmed'||s.authority==='commitment'&&config.includeCommitments);
+  const sourceIds=v.sourceIds;
+  if(sourceIds.some(id=>!required.some(s=>s.id===id)))throw new JudgeProtocolError('Counter-review sources must have original policy authority');
+  if(v.observationRefs.some(ref=>!isDeliveryFact(resolveObservation(input,ref))))throw new JudgeProtocolError('Counter-review cannot use failed or setup-only facts');
+  if(v.disposition==='uphold'&&(!v.observationRefs.length||candidate.judgment==='pass'&&required.some(s=>!sourceIds.includes(s.id))))throw new JudgeProtocolError('Uphold needs native evidence; PASS review must include every authoritative source');
+  let replacement:Proposal|undefined;
+  if(v.replacement!==undefined){
+    if(v.disposition!=='challenge')throw new JudgeProtocolError('Only a challenge may supply a replacement failure');
+    replacement=decodeProposal(v.replacement,input);
+    if(replacement.judgment!=='fail')throw new JudgeProtocolError('Counter-review never flips a rejected FAIL into automatic PASS');
+    const diagnostics=admit(input,replacement,config);
+    if(diagnostics.length)throw new JudgeProtocolError('Replacement failure rejected: '+JSON.stringify(diagnostics));
+  }
+  return {disposition:v.disposition as CounterReview['disposition'],reason:v.reason,sourceIds:v.sourceIds,observationRefs:v.observationRefs,...(replacement?{replacement}:{})};
+}
+
+/** No voting, semantic synthesis, opposite-verdict inference or historical write. */
+export function resolveCounterReview(input:EvaluationInput,candidate:Decision,value:unknown,invocations:Invocation[],config:EvaluationConfig):CounterReviewResult {
+  const review=decodeCounterReview(input,candidate,value,config);
+  if(review.disposition==='uphold')return {candidate,review,decision:{...candidate,invocations},resolution:'upheld'};
+  if(review.replacement)return {candidate,review,decision:{...candidate,proposal:review.replacement,judgment:'fail',failureClass:'business',diagnostics:[],invocations},resolution:'replacement-failure'};
+  return {candidate,review,decision:{...candidate,proposal:null,judgment:'indeterminate',failureClass:'scope-unresolved',invocations,diagnostics:[{rule:'counter-review-unresolved',location:'$',message:review.reason,repairable:false}]},resolution:'challenged'};
+}
+
+export function unavailableCounterReview(candidate:Decision,invocations:Invocation[],reason:string,kind:'budget'|'protocol'|'infrastructure'):CounterReviewResult {
+  const failureClasses={budget:'scope-unresolved',protocol:'protocol-cost',infrastructure:'infrastructure'} as const;
+  return {candidate,review:null,resolution:'unavailable',decision:{...candidate,proposal:null,judgment:'indeterminate',execution:kind==='infrastructure'?'infrastructure-failed':'completed',failureClass:failureClasses[kind],invocations,diagnostics:[{rule:'counter-review-'+kind,location:'$',message:reason,repairable:false}]}};
+}

package/coverage.ts

@@ -0,0 +1,74 @@
+import type {CoverageItem,CoverageReport,EvaluationInput,Observation,Source} from './contract';
+import {canonicalIdentity} from './representation';
+
+const text=(value:unknown):value is string=>typeof value==='string'&&!!value.trim();
+export const isDeliveryFact=(o:Observation)=>o.status==='completed'&&(!o.purpose||o.purpose==='delivery');
+
+function requiredSources(input:EvaluationInput,includeCommitments:boolean):Source[] {
+  return input.sources.filter(source=>source.authority==='original'||source.authority==='confirmed'||includeCommitments&&source.authority==='commitment');
+}
+
+/** Whitelisted immutable inputs, never observations of the delivery. */
+export function readTarget(input:EvaluationInput,sourceId:unknown):Source {
+  const source=input.sources.find(s=>s.id===sourceId);
+  if(!source)throw Error('Unknown target source ID; use the immutable input source list');
+  return structuredClone(source);
+}
+
+/** Reference coverage only; never a semantic sufficiency check. */
+export function coveragePlan(input:EvaluationInput,value:unknown,includeCommitments=false):CoverageReport {
+  const plan=value as {items:CoverageItem[];reviewedSourceIds:string[]};
+  if(!plan||!Array.isArray(plan.items)||!plan.items.length||plan.items.length>200||!Array.isArray(plan.reviewedSourceIds)||!plan.reviewedSourceIds.every(text))throw Error('Coverage plan needs 1..200 source-bound items and reviewedSourceIds');
+  const allowed=requiredSources(input,includeCommitments);
+  if(plan.reviewedSourceIds.some(id=>!allowed.some(s=>s.id===id)))throw Error('Coverage reviewed source is not requirement authority');
+  const ids=new Set<string>();
+  for(const item of plan.items){
+    if(!item||!text(item.id)||ids.has(item.id)||!text(item.quote)||!text(item.expectation)||!['inspection','execution'].includes(item.mode))throw Error('Invalid or duplicate coverage item');
+    ids.add(item.id);
+    if(!allowed.some(s=>s.id===item.sourceId&&s.content.includes(item.quote)))throw Error(`Coverage item ${item.id} in source ${item.sourceId} must quote an exact authoritative source`);
+  }
+  for(const obligation of input.obligations??[]){
+    if(obligation.children.length||obligation.condition==='not-applicable')continue;
+    const unchanged=plan.items.some(item=>item.id===obligation.id&&item.sourceId===obligation.sourceId&&item.quote===obligation.quote&&item.expectation===obligation.expectation);
+    if(!unchanged)throw Error('Coverage plan omitted or changed a caller-owned leaf obligation');
+  }
+  return {items:structuredClone(plan.items),reviewedSourceIds:[...new Set(plan.reviewedSourceIds)],checkpointed:false,links:[],gaps:[],supplement:'not-needed',semanticAuthority:false};
+}
+
+export function coverageCheckpoint(input:EvaluationInput,plan:CoverageReport,value:unknown,unavailable:unknown=[]):CoverageReport {
+  const links=value as CoverageReport['links'];
+  if(!Array.isArray(links))throw Error('Coverage checkpoint needs links array');
+  const seen=new Set<string>();
+  for(const link of links){
+    const item=plan.items.find(i=>i.id===link?.itemId);
+    if(!item||seen.has(link.itemId)||!Array.isArray(link.observationIds)||!link.observationIds.every(text))throw Error('Invalid coverage checkpoint item');
+    seen.add(link.itemId);
+    for(const id of link.observationIds){
+      const fact=input.observations.find(o=>o.id===id);
+      if(!fact||fact.runId!==input.runId||fact.artifactDigest!==input.artifactDigest||!isDeliveryFact(fact))throw Error('Coverage reference must bind a completed native delivery fact');
+      if(item.mode==='execution'&&fact.channel==='file')throw Error('Static file cannot close execution coverage');
+    }
+  }
+  if(!Array.isArray(unavailable)||unavailable.some(item=>!item||!plan.items.some(i=>i.id===item.itemId)||!text(item.reason)))throw Error('Unavailable coverage needs known items and explicit capability limitations');
+  return {...plan,checkpointed:true,links:structuredClone(links),unavailable:structuredClone(unavailable)};
+}
+
+export function coverageGaps(input:EvaluationInput,plan?:CoverageReport,includeCommitments=false):CoverageReport {
+  const result:CoverageReport=plan?structuredClone(plan):{items:[],reviewedSourceIds:[],checkpointed:false,links:[],gaps:[],supplement:'not-needed',semanticAuthority:false};
+  result.gaps=[];
+  if(!plan)result.gaps.push({itemId:'$plan',reason:'No source-bound observation plan was submitted'});
+  if(!result.checkpointed)result.gaps.push({itemId:'$checkpoint',reason:'No final native-reference coverage checkpoint'});
+  for(const source of requiredSources(input,includeCommitments)){
+    if(!result.reviewedSourceIds.includes(source.id))result.gaps.push({itemId:`$source:${source.id}`,reason:'Original target source not reviewed in the observation plan'});
+  }
+  for(const item of result.items){
+    if(result.links.find(l=>l.itemId===item.id)?.observationIds.length)continue;
+    const limitation=result.unavailable?.find(entry=>entry.itemId===item.id);
+    result.gaps.push({itemId:item.id,reason:limitation?.reason??`No native ${item.mode} reference; ${item.expectation}`});
+  }
+  return result;
+}
+
+export function samePlan(a:CoverageReport,b:CoverageReport):boolean {
+  return canonicalIdentity({items:a.items,sources:a.reviewedSourceIds})===canonicalIdentity({items:b.items,sources:b.reviewedSourceIds});
+}

package/environment.ts

@@ -0,0 +1,11 @@
+import type {HttpProbe,Observation} from './contract';
+
+/** Preserve request shape/ordinary values without persisting credentials. */
+export function redactRequest(value:unknown):unknown {
+  if(Array.isArray(value))return value.map(redactRequest);
+  if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).map(([key,entry])=>[key,/password|secret|token|authorization|cookie|api.?key/i.test(key)?'[redacted]':redactRequest(entry)]));
+  return value;
+}
+export function httpEnvironment(origin:string,probe:HttpProbe):NonNullable<Observation['environment']> {
+  return {http:{origin,method:probe.method,path:probe.path,serviceId:probe.serviceId,authorization:Object.keys(probe.headers??{}).some(key=>key.toLowerCase()==='authorization')?'present-redacted':'absent',...(probe.body===undefined?{}:{body:redactRequest(probe.body)})}};
+}

package/feedback.ts

@@ -0,0 +1,31 @@
+import type {EvaluationInput,EvidenceFeedback} from './contract';
+import {JudgeProtocolError} from './proposal';
+import {resolveObservation} from './native-references';
+
+/** Source/reference authenticity, NOT a completeness or business oracle. */
+export function decodeFeedback(value:unknown,input:EvaluationInput,includeCommitments=false):EvidenceFeedback {
+  let v=value as EvidenceFeedback;
+  if((value as any)?.format==='evidence-request-v2'){
+    const data=value as {format:string;requests:any[]};
+    if(Object.keys(data).some(k=>!['format','requests'].includes(k))||!Array.isArray(data.requests))throw new JudgeProtocolError('Malformed native evidence request');
+    v={format:'evidence-request-v1',requests:data.requests.map(r=>{
+      if(!r||Object.keys(r).some(k=>!['id','sourceId','quote','expectation','missingEvidence','observationRefs'].includes(k))||r.observationRefs!==undefined&&!Array.isArray(r.observationRefs))throw new JudgeProtocolError('Evidence request uses only source binding and optional observationRefs');
+      const source=input.sources.find(s=>s.id===r.sourceId);
+      return {id:r.id,sourceId:r.sourceId,quote:r.quote??source?.content,expectation:r.expectation,missingEvidence:r.missingEvidence,observationIds:(r.observationRefs??[]).map((ref:unknown)=>resolveObservation(input,ref).id)};
+    })};
+  }
+  if(!v||v.format!=='evidence-request-v1'||!Array.isArray(v.requests)||!v.requests.length||v.requests.length>24)throw new JudgeProtocolError('Evidence feedback requires 1..24 source-bound requests');
+  if(Object.keys(v).some(k=>!['format','requests'].includes(k)))throw new JudgeProtocolError('Evidence feedback is a request, never a verdict or capability grant');
+  const ids=new Set<string>();
+  for(const r of v.requests){
+    const s=input.sources.find(s=>s.id===r?.sourceId);
+    if(!r||[r.id,r.sourceId,r.quote,r.expectation,r.missingEvidence].some(v=>typeof v!=='string'||!v.trim())||ids.has(r.id))throw new JudgeProtocolError('Malformed or duplicate evidence request');
+    ids.add(r.id);
+    if(!s||s.authority==='inferred'||s.authority==='commitment'&&!includeCommitments||!s.content.includes(r.quote))throw new JudgeProtocolError('Evidence request must bind an exact authoritative source quote');
+    if(!Array.isArray(r.observationIds)||r.observationIds.some(id=>!input.observations.some(o=>o.id===id&&o.runId===input.runId&&o.artifactDigest===input.artifactDigest)))throw new JudgeProtocolError('Evidence request references foreign observations');
+    if(Object.keys(r).some(k=>!['id','sourceId','quote','expectation','missingEvidence','observationIds'].includes(k)))throw new JudgeProtocolError('Evidence request cannot contain executable steps or permission overrides');
+  }
+  return v;
+}
+
+export const FEEDBACK_GUIDANCE=`While the native lease is alive, check facts against COMPLETE originals, not just coverage IDs. If a material missing fact can safely be obtained, save {format:"evidence-request-v2",requests:[{id:"need-1",sourceId:"original-id",expectation:"unchanged required behavior",missingEvidence:"specific absent observation and why needed",observationRefs:["obs:N"]}]}. quote is optional: omitting it natively binds the complete original; observationRefs is optional. Use current catalog refs, never digests/UUIDs. This is advisory need, not a verdict/script/permission. Request ALL currently material gaps together; do not demand exhaustive proof or re-exercise sufficiently supported behavior. A supported required defect already permits overall FAIL: submit its finding, preserving other limits rather than collecting until PASS. When canSupplement:false, or nothing material is missing, submit the final Proposal. The owner checks the same immutable bytes.`;

package/history.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {inventoryHistory} from './support/history';
+const [command,list,output]=process.argv.slice(2);
+if(command!=='inventory'||!list||!output||!path.isAbsolute(list)||!path.isAbsolute(output))throw Error('Usage: bun evaluation/history.ts inventory /absolute/roots.json /absolute/new-inventory.json');
+const roots=JSON.parse(fs.readFileSync(list,'utf8'));
+if(!Array.isArray(roots)||roots.some(r=>typeof r!=='string'||!path.isAbsolute(r)))throw Error('Provide an explicit absolute-path list');
+const inventory=inventoryHistory(roots);
+fs.writeFileSync(output,JSON.stringify(inventory,null,2)+'\n',{flag:'wx'});
+console.log(JSON.stringify({samples:inventory.samples.length,excluded:inventory.excluded.length,duplicates:inventory.duplicates.length,output}));

package/host.xnl

@@ -0,0 +1,7 @@
+<HostBundle #ArtifactEvaluation.Host envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
+  profile = "host-package"
+  packageRoot = "vfs://."
+  descriptor = "vfs://./app/host.ts"
+  runtime = "bun"
+  exports = ["LocalFunction"]
+}>

package/index.ts

@@ -0,0 +1,6 @@
+/** Public evaluation surface; IO and product adapters remain outside pure rules. */
+export * from './contract';
+export { evaluate, admit, semanticIdentity, summarize, aggregateUsage, defaultConfig } from './logic';
+export { newBudget } from './budget';
+export {projectTargetGroups,type TargetGroup} from './target-groups';
+export {resolveCounterReview,decodeCounterReview,type CounterReview,type CounterReviewResult} from './counter-review';

package/logic.ts

@@ -0,0 +1,135 @@
+import { POLICY, type Claim, type Decision, type Diagnostic, type EvaluationConfig, type EvaluationInput, type EvaluationRuntime, type Invocation, type Obligation, type Proposal } from './contract';
+import { canonicalIdentity, excerptDiagnostic, repairOnce } from './representation';
+import { JudgeProtocolError } from './proposal';
+import {isDeliveryFact} from './coverage';
+import {admitNeeds} from './needs';
+import {obligationGraph} from './obligation-graph';
+
+const issue = (rule: string, location: string, message: string, repairable = false): Diagnostic => ({rule, location, message, repairable});
+const text = (s: unknown): s is string => typeof s === 'string' && s.trim().length > 0;
+const validJudgment = (s: unknown) => typeof s==='string'&&['pass','fail','indeterminate'].includes(s);
+
+/** Authenticity/coverage admission, NOT a semantic oracle. Model reasoning remains fallible. */
+export function admit(input: EvaluationInput, proposal: Proposal, config: EvaluationConfig): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  if (!proposal || !validJudgment(proposal.judgment) || !Array.isArray(proposal.obligations) || !Array.isArray(proposal.claims) || !Array.isArray(proposal.findings) || !Array.isArray(proposal.sourceReviews)) {
+    return [issue('proposal-shape','$','Malformed judgment protocol')];
+  }
+  if(proposal.obligations.some(o=>!o||!Array.isArray(o.children)||!o.children.every(text))||proposal.claims.some(c=>!c||!Array.isArray(c.evidence)||c.evidence.some(e=>!e))||proposal.findings.some(f=>!f)||proposal.sourceReviews.some(r=>!r||typeof r.complete!=='boolean'))return [issue('proposal-shape','$','Malformed nested protocol data')];
+  const obligations = new Map<string,Obligation>();
+  for (const [i,o] of proposal.obligations.entries()) {
+    const at = `obligations[${i}]`;
+    if (!o || !text(o.id) || obligations.has(o.id)) {diagnostics.push(issue('obligation-id',at,'Invalid or duplicate obligation'));continue;}
+    obligations.set(o.id,o);
+    const source = input.sources.find(s=>s.id===o.sourceId);
+    if (!source || !text(o.quote) || !source.content.includes(o.quote)) diagnostics.push(issue('source-binding',at,'Quote must be an exact excerpt of a frozen source'));
+    if (source && (source.authority==='inferred' || (source.authority==='commitment' && !config.includeCommitments))) diagnostics.push(issue('source-authority',at,'This source cannot create a required obligation under the trusted policy'));
+    if (!text(o.expectation) || !text(o.rationale) || !['leaf','all','any','conditional'].includes(o.relation) || !Array.isArray(o.children) || !['applicable','not-applicable','unresolved'].includes(o.condition)) diagnostics.push(issue('obligation-shape',at,'Expectation, relation, children, condition and rationale required'));
+    else if (o.relation==='leaf' && o.children.length || ['all','any'].includes(o.relation) && !o.children.length) diagnostics.push(issue('obligation-relation',at,'All/any need children; leaves cannot have children'));
+  }
+  for (const o of proposal.obligations) {
+    if (!Array.isArray(o?.children)) continue;
+    const visit = (id: string, trail: string[]): void => {
+      if (trail.includes(id)) {diagnostics.push(issue('obligation-cycle',o.id,'Cyclic obligation graph'));return;}
+      const child = obligations.get(id);
+      if (!child) {diagnostics.push(issue('obligation-child',o.id,`Unknown child ${id}`));return;}
+      for (const c of child.children ?? []) visit(c,[...trail,id]);
+    };
+    for (const child of o.children) visit(child,[o.id]);
+  }
+  for (const frozen of input.obligations ?? []) {
+    if (canonicalIdentity(obligations.get(frozen.id))!==canonicalIdentity(frozen)) diagnostics.push(issue('target-omission',frozen.id,'Caller-owned obligation omitted or changed'));
+  }
+  for (const source of input.sources.filter(s=>s.authority==='original'||s.authority==='confirmed'||(s.authority==='commitment'&&config.includeCommitments))) {
+    const review = proposal.sourceReviews.filter(r=>r.sourceId===source.id);
+    if (review.length!==1 || !Array.isArray(review[0]?.omissions) || !Array.isArray(review[0]?.ambiguities)) diagnostics.push(issue('source-review',source.id,'Full-source review must record completeness, omissions and ambiguities'));
+    else if (proposal.judgment==='pass' && (!review[0].complete || review[0].omissions.length || review[0].ambiguities.length)) diagnostics.push(issue('target-unresolved',source.id,'Omissions or ambiguity forbid unconditional PASS'));
+  }
+  const claims = new Map<string,Claim>();
+  for (const [i,c] of proposal.claims.entries()) {
+    const at = `claims[${i}]`;
+    if (!c || !obligations.has(c.obligationId) || claims.has(c.obligationId) || !validJudgment(c.judgment) || !Array.isArray(c.evidence) || !Array.isArray(c.limitations)) {diagnostics.push(issue('claim-shape',at,'Unique claim must reference an obligation'));continue;}
+    claims.set(c.obligationId,c);
+    if (c.semanticExpectation !== obligations.get(c.obligationId)!.expectation || !text(c.method) || !text(c.conditions) || !text(c.reasoning)) diagnostics.push(issue('claim-support',at,'Freeze expectation; explain method, conditions and semantic support'));
+    if (c.judgment!=='indeterminate' && !c.evidence.length && !obligations.get(c.obligationId)!.children.length) diagnostics.push(issue('evidence-insufficient',at,'A definitive leaf judgment needs native evidence'));
+    if(c.preconditions&&(!['established','unresolved','incompatible'].includes(c.preconditions.status)||!text(c.preconditions.reasoning)||!Array.isArray(c.preconditions.evidenceIds)))diagnostics.push(issue('environment-preconditions',at,'Malformed execution prerequisite assessment'));
+    if(c.judgment!=='indeterminate'&&c.preconditions&&c.preconditions.status!=='established')diagnostics.push(issue('environment-unresolved',at,'Unresolved or incompatible execution prerequisites cannot support a definitive claim'));
+    const restrictedFailure=c.judgment==='fail'&&c.evidence.some(e=>input.observations.some(o=>o.id===e.observationId&&o.environment?.process&&o.exitCode!==undefined&&o.exitCode!==0));
+    if(restrictedFailure){
+      const p=c.preconditions;
+      const established=p?.status==='established'&&text(p.reasoning)&&Array.isArray(p.evidenceIds)&&p.evidenceIds.length>0&&p.evidenceIds.every(id=>c.evidence.some(e=>e.observationId===id)&&input.observations.some(o=>o.id===id&&o.runId===input.runId&&o.artifactDigest===input.artifactDigest&&isDeliveryFact(o)&&(!o.environment?.process||o.exitCode===0)));
+      if(!established)diagnostics.push(issue('environment-unresolved',at,'Restricted nonzero execution alone cannot establish business FAIL; prerequisite applicability needs independently cited native delivery evidence'));
+    }
+    for (const [j,e] of c.evidence.entries()) {
+      const location = `${at}.evidence[${j}]`;
+      const observation = input.observations.find(o=>o.id===e.observationId);
+      if (!observation || observation.runId!==input.runId || observation.artifactDigest!==input.artifactDigest || observation.phase!=='observation' || !isDeliveryFact(observation)) diagnostics.push(issue('observation-binding',location,'Unknown, foreign, failed, input/setup-only or wrong-phase observation',true));
+      else if(e.complete===true){if(e.excerpt!==observation.content)diagnostics.push(issue('native-excerpt',location,'Complete evidence must preserve every native byte',true));}
+      else {const diagnostic=excerptDiagnostic(observation.content,e.excerpt,location);if(diagnostic)diagnostics.push(diagnostic);}
+      if (!text(e.supports)) diagnostics.push(issue('evidence-reasoning',location,'Explain how this fact supports the unchanged claim'));
+    }
+  }
+  if (proposal.judgment==='pass' && (!obligations.size || proposal.findings.length)) diagnostics.push(issue('pass-shape','$','PASS requires obligations and no findings'));
+  const graph=obligationGraph(proposal);
+  if(proposal.judgment==='pass')for(const o of graph.roots)if(!['pass','not-applicable'].includes(graph.compare(o.id).judgment))diagnostics.push(issue('leaf-coverage',o.id,'Unsupported/unresolved compound obligation cannot pass via parent coverage ID'));
+  if (proposal.judgment==='fail' && (!proposal.findings.length || !proposal.claims.some(c=>c.judgment==='fail'))) diagnostics.push(issue('finding-required','$','Business FAIL needs a supported failed claim and stable finding'));
+  const ids = new Set<string>();
+  for (const finding of proposal.findings) {
+    if (!text(finding.id) || ids.has(finding.id) || !text(finding.description) || !Array.isArray(finding.obligationIds) || !finding.obligationIds.length || finding.obligationIds.some(id=>claims.get(id)?.judgment!=='fail'||graph.compare(id).judgment!=='fail')) diagnostics.push(issue('finding-binding',`findings.${finding.id}`,'Stable finding must bind failed obligations supported by the applicable leaf relation'));
+    else if(finding.obligationIds.some(id=>!graph.withinFailedRoot(id)))diagnostics.push(issue('target-contradiction',`findings.${finding.id}`,'A failed optional branch cannot falsify a satisfied or unresolved required root'));
+    ids.add(finding.id);
+  }
+  return [...diagnostics,...admitNeeds(input,proposal)];
+}
+
+/** Evidence references/excerpts are representations. Business semantics are immutable. */
+export function semanticIdentity(proposal: Proposal): string {
+  return canonicalIdentity({...proposal, claims: proposal.claims.map(c=>({...c,evidence:c.evidence.map(e=>({supports:e.supports}))}))});
+}
+export function decisionExitCode(decision:Pick<Decision,'execution'|'judgment'>,noModel=false):number {
+  if(decision.execution!=='completed')return 2;
+  if(decision.judgment==='fail')return 1;
+  if(decision.judgment==='indeterminate'&&!noModel)return 3;
+  return 0;
+}
+export async function evaluate(runtime: EvaluationRuntime, input: EvaluationInput, config: EvaluationConfig): Promise<Decision> {
+  const failure = input.observations.find(o=>o.status!=='completed');
+  const base = {schemaVersion:1 as const,policyVersion:config.policyVersion,runId:input.runId,artifactDigest:input.artifactDigest,observations:input.observations};
+  if (failure) return {...base,execution:failure.status==='interrupted'?'interrupted':'infrastructure-failed',judgment:'indeterminate',failureClass:'infrastructure',proposal:null,diagnostics:[issue('execution-failed',failure.id,'Native observer did not complete')],invocations:runtime.judge.invocations()};
+  if(!input.observations.some(isDeliveryFact)){
+    runtime.record({phase:'judgment-skipped',reason:'no-delivery-evidence',coverage:input.coverage??null});
+    return {...base,execution:'completed',judgment:'indeterminate',failureClass:'scope-unresolved',proposal:null,diagnostics:[issue('no-delivery-evidence','$','No completed native delivery evidence. Target reads and lease setup do not demonstrate the artifact; no model judge was invoked.')],invocations:runtime.judge.invocations()};
+  }
+  let proposal: Proposal;
+  try {proposal=await runtime.judge.judge(input);} catch (error) {
+    const protocol=error instanceof JudgeProtocolError;
+    return {...base,execution:protocol?'completed':'infrastructure-failed',judgment:'indeterminate',failureClass:protocol?'protocol-cost':'infrastructure',proposal:null,diagnostics:[issue(protocol?'judge-protocol':'judge-unavailable','$',String(error))],invocations:runtime.judge.invocations()};
+  }
+  let diagnostics = admit(input,proposal,config);
+  if (diagnostics.length && diagnostics.every(d=>d.repairable)) {
+    runtime.record({phase:'representation-repair',diagnostics});
+    try {
+      proposal=await repairOnce({identity:semanticIdentity,repairable:()=>true,record:()=>{},admit:p=>{const ds=admit(input,p,config);if(ds.length)throw Object.assign(Error(JSON.stringify(ds)),{diagnostics:ds});},repair:p=>runtime.judge.judge(input,{proposal:p,diagnostics})},proposal);
+      diagnostics=admit(input,proposal,config);
+    } catch (error) {diagnostics=[issue(String(error).includes('changed business')?'repair-changed-semantics':'repair-unavailable','$',String(error))];}
+  }
+  const judgment = diagnostics.length ? 'indeterminate' : proposal.judgment;
+  let failureClass:Decision['failureClass']=null;
+  if(diagnostics.length)failureClass=diagnostics.every(d=>!['target-omission','source-authority','target-unresolved','leaf-coverage','target-contradiction','environment-unresolved','need-unresolved'].includes(d.rule))?'protocol-cost':'scope-unresolved';
+  else if(judgment==='fail')failureClass='business';
+  else if(judgment==='indeterminate')failureClass='scope-unresolved';
+  return {...base,execution:'completed',judgment,failureClass,proposal,diagnostics,invocations:runtime.judge.invocations()};
+}
+export function aggregateUsage(invocations: Invocation[]) {
+  const unique = [...new Map(invocations.map(i=>[i.id,i])).values()];
+  const valid = unique.filter(i=>i.usage && [i.usage.input,i.usage.cached,i.usage.output].every(n=>Number.isFinite(n)&&n>=0) && i.usage.cached<=i.usage.input);
+  return {known:valid.reduce((a,i)=>({input:a.input+i.usage!.input,cached:a.cached+i.usage!.cached,output:a.output+i.usage!.output}),{input:0,cached:0,output:0}),unknownInvocations:unique.length-valid.length,scope:'cached is a subset of input; includes failures; not a bill'};
+}
+export function summarize(decisions: Decision[]) {
+  const policies = [...new Set(decisions.map(d=>d.policyVersion))];
+  return {policies,groups:policies.map(policy=> {
+    const all=decisions.filter(d=>d.policyVersion===policy),eligible=all.filter(d=>d.execution==='completed'&&d.failureClass!=='protocol-cost'&&d.judgment!=='indeterminate');
+    return {policyVersion:policy,allSamples:all.length,businessEligible:eligible.length,passes:eligible.filter(d=>d.judgment==='pass').length,indeterminate:all.filter(d=>d.judgment==='indeterminate').length,usage:aggregateUsage(all.flatMap(d=>d.invocations))};
+  })};
+}
+export const defaultConfig: EvaluationConfig = {policyVersion:POLICY,includeCommitments:false};

package/manifest.xnl

@@ -0,0 +1,10 @@
+<SkillApp #ArtifactEvaluation.App envelopeVersion="halfcode.resource-envelope/v1" specVersion=1 {
+  profile = "app-package"
+  packageRoot = "vfs://."
+  descriptor = "vfs://./app/app.ts"
+} (
+  <Catalogs [
+    <DirectoryResourceCatalog #host { resourceKind = "HostBundle" root = "vfs://./" entry = "host.xnl" scope = "root" }>
+    <FileResourceCatalog #procedures { resourceKind = "SOP" root = "vfs://./resources/" }>
+  ]>
+)>

package/native-references.ts

@@ -0,0 +1,21 @@
+import type {EvaluationInput,Observation} from './contract';
+import {JudgeProtocolError} from './protocol-error';
+
+/** Explicit owner-assigned catalog addresses, never guesses from a digest/UUID. */
+export const observationRef=(index:number)=>`obs:${index+1}`;
+export function resolveObservation(input:EvaluationInput,ref:unknown):Observation {
+  if(typeof ref!=='string'||!/^obs:[1-9]\d*$/.test(ref))throw new JudgeProtocolError('Use an observationRef from the current catalog (obs:N), not a digest or ID');
+  const index=Number(ref.slice(4))-1,o=input.observations[index];
+  if(!Number.isSafeInteger(index)||!o||o.runId!==input.runId||o.artifactDigest!==input.artifactDigest)throw new JudgeProtocolError('Unknown or foreign observationRef');
+  return o;
+}
+
+/** Model selects a fact; owner supplies its exact bytes and provenance. */
+export function referenceEvidence(input:EvaluationInput,value:unknown) {
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new JudgeProtocolError('Evidence reference must be an object');
+  const e=value as Record<string,unknown>;
+  if(Object.keys(e).some(k=>!['observationRef','supports','excerpt'].includes(k))||typeof e.supports!=='string'||!e.supports.trim())throw new JudgeProtocolError('Evidence needs observationRef and a semantic supports explanation');
+  const o=resolveObservation(input,e.observationRef);
+  if(e.excerpt!==undefined&&typeof e.excerpt!=='string')throw new JudgeProtocolError('Optional excerpt must be literal native text');
+  return {observationId:o.id,excerpt:e.excerpt===undefined?o.content:e.excerpt,supports:e.supports,...(e.excerpt===undefined?{complete:true as const}:{})};
+}

package/needs.ts

@@ -0,0 +1,33 @@
+import type {Diagnostic,EvaluationInput,EvidenceFeedback,EvidenceNeed,Proposal} from './contract';
+import {obligationGraph} from './obligation-graph';
+
+/** Append only. A request is advisory, not a new authority or an execution grant. */
+export function retainNeeds(previous:EvidenceNeed[],feedback:EvidenceFeedback,round:number):EvidenceNeed[] {
+  return [...previous,...feedback.requests.map((r,index)=>({...r,observationIds:[...r.observationIds],round,needId:`need:${previous.length+index+1}`}))];
+}
+
+/** Known gap conservation, not a semantic completeness oracle. */
+export function admitNeeds(input:EvaluationInput,proposal:Proposal):Diagnostic[] {
+  const diagnostics:Diagnostic[]=[],reviews=proposal.needReviews??[],known=new Map((input.needs??[]).map(n=>[n.needId,n])),seen=new Set<string>();
+  const graph=obligationGraph(proposal);
+  const issue=(location:string,message:string)=>diagnostics.push({rule:'need-unresolved',location,message,repairable:false});
+  if(!Array.isArray(reviews))return [{rule:'need-unresolved',location:'needReviews',message:'Known feedback needs require explicit final dispositions',repairable:false}];
+  for(const r of reviews){
+    if(!r||!known.has(r.needId)||seen.has(r.needId)||!['addressed','unresolved','not-required'].includes(r.disposition)||typeof r.reasoning!=='string'||!r.reasoning.trim()||!Array.isArray(r.obligationIds)) {issue('needReviews','Invalid, unknown or duplicate need disposition');continue;}
+    seen.add(r.needId);
+    const need=known.get(r.needId)!;
+    const obligations=r.obligationIds.map(id=>proposal.obligations.find(o=>o.id===id));
+    if(obligations.some(o=>!o||o.sourceId!==need.sourceId||o.expectation!==need.expectation))issue(r.needId,'Need disposition must bind its retained source AND exact expectation; another claim from the same source does not close this need');
+    if(r.disposition==='addressed'&&(!obligations.length||!obligations.some(o=>{
+      if(!o)return false;
+      const outcome=graph.compare(o.id);
+      return outcome.compared&&['pass','fail'].includes(outcome.judgment);
+    })))issue(r.needId,'Addressed need requires a supported definitive comparison of its exact leaf or compound relation; partial evidence or a parent assertion alone is insufficient');
+    if(r.disposition==='not-required'&&(!obligations.length||!obligations.every(o=>o?.relation==='conditional'&&o.condition==='not-applicable'&&o.rationale.trim())))issue(r.needId,'Not-required requires its exact expectation bound as a justified conditional/not-applicable obligation, not an ordinary or unresolved leaf');
+    if(r.disposition==='unresolved'&&proposal.judgment==='pass')issue(r.needId,'An unresolved material feedback need forbids unconditional PASS');
+  }
+  for(const id of known.keys())if(!seen.has(id))issue(id,'Previously identified need omitted from final review');
+  return diagnostics;
+}
+
+export const NEED_GUIDANCE='Retain EVERY need with needReviews:[{needId:"need:N",disposition:"addressed|unresolved|not-required",obligationIds:[],reasoning:string}]. Addressed binds the EXACT expectation: use obligation.needRef:"need:N" and omit sourceId/expectation/quote; owner supplies retained bytes. For compound needs put needRef on the all/any parent and compare independent source-bound leaves, not a partially supported broad PASS. ALL needs every applicable child; ANY accepts a valid alternative. Unresolved may bind [] with explicit limits and forbids overall PASS. Not-required binds the exact need as conditional/not-applicable with original-source rationale. Advisory needs are fallible, not new user authority; no same-source substitution or duplicate parent score.';

package/obligation-graph.ts

@@ -0,0 +1,47 @@
+import type {Judgment,Obligation,Proposal} from './contract';
+
+interface Outcome {judgment:Judgment|'not-applicable';compared:boolean}
+const unknown:Outcome={judgment:'indeterminate',compared:false};
+
+/** Pure relation folding, not natural-language decomposition or a truth oracle. */
+export function obligationGraph(proposal:Pick<Proposal,'obligations'|'claims'>) {
+  const obligations=new Map(proposal.obligations.map(o=>[o.id,o]));
+  const claims=new Map(proposal.claims.map(c=>[c.obligationId,c]));
+  const children=new Set(proposal.obligations.flatMap(o=>o.children));
+  const roots=proposal.obligations.filter(o=>!children.has(o.id));
+
+  function compare(id:string,trail:string[]=[]):Outcome {
+    const o=obligations.get(id);
+    if(!o||trail.includes(id))return unknown;
+    if(o.relation==='conditional'&&o.condition==='not-applicable'&&o.rationale.trim())return {judgment:'not-applicable',compared:false};
+    if(o.condition!=='applicable')return unknown;
+    if(o.relation==='leaf'&&o.children.length||['all','any'].includes(o.relation)&&!o.children.length)return unknown;
+    if(!o.children.length){
+      const claim=claims.get(id);
+      if(!claim?.evidence.length||claim.judgment==='indeterminate')return unknown;
+      return {judgment:claim.judgment,compared:true};
+    }
+    const active=o.children.map(child=>compare(child,[...trail,id])).filter(c=>c.judgment!=='not-applicable');
+    if(!active.length)return {judgment:'not-applicable',compared:false};
+    const compared=active.some(c=>c.compared);
+    if(o.relation==='any'){
+      if(active.some(c=>c.judgment==='pass'))return {judgment:'pass',compared};
+      if(active.every(c=>c.judgment==='fail'))return {judgment:'fail',compared};
+    }else{
+      if(active.some(c=>c.judgment==='fail'))return {judgment:'fail',compared};
+      if(active.every(c=>c.judgment==='pass'))return {judgment:'pass',compared};
+    }
+    return {judgment:'indeterminate',compared};
+  }
+
+  function containsContradiction(o:Obligation,id:string,trail:string[]=[]):boolean {
+    if(trail.includes(o.id)||compare(o.id).judgment!=='fail')return false;
+    if(o.id===id)return true;
+    return o.children.some(child=>{
+      const next=obligations.get(child);
+      return !!next&&containsContradiction(next,id,[...trail,o.id]);
+    });
+  }
+
+  return {roots,compare,withinFailedRoot:(id:string)=>roots.some(root=>containsContradiction(root,id))};
+}