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

package/support/retention.ts

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {copyArtifact} from './artifact-links';
+import {digest,fingerprint} from './isolation';
+
+interface RetainedFile {path:string;sha256:string;bytes:number;link?:string}
+export interface RetainedEvaluation {
+  version:1;
+  closed:boolean;
+  artifactDigest:string;
+  originalRunRoot:string;
+  originalArtifactRoot:string;
+  files:RetainedFile[];
+  limitations:string[];
+}
+
+function absoluteDirectory(directory:string):void {
+  if(!path.isAbsolute(directory)||path.resolve(directory)!==directory)throw Error('Retention requires an absolute path without traversal');
+  let parent=directory;
+  while(!fs.existsSync(parent))parent=path.dirname(parent);
+  if(fs.realpathSync(parent)!==parent)throw Error('Retention symlink ancestor rejected');
+}
+
+export function assertRetentionDestination(destination:string,excludedRoots:string[]=[]):void {
+  absoluteDirectory(destination);
+  if(fs.existsSync(destination))throw Error('Never overwrite retained evidence');
+  if(excludedRoots.some(root=>destination===root||destination.startsWith(root+path.sep)||root.startsWith(destination+path.sep)))throw Error('Retention must be disjoint from execution and artifact');
+}
+
+function inventory(root:string,relative=''):RetainedFile[] {
+  return fs.readdirSync(path.join(root,relative),{withFileTypes:true}).sort((a,b)=>a.name.localeCompare(b.name)).flatMap(entry=>{
+    const name=path.join(relative,entry.name),file=path.join(root,name);
+    if(entry.isDirectory())return inventory(root,name);
+    if(entry.isSymbolicLink()){
+      const link=fs.readlinkSync(file),resolved=fs.realpathSync(file);
+      if(!resolved.startsWith(root+path.sep)||!fs.statSync(resolved).isFile())throw Error('Retained link escapes archive');
+      return [{path:name,sha256:digest(link),bytes:Buffer.byteLength(link),link}];
+    }
+    if(!entry.isFile())throw Error('Unsupported retained object');
+    const bytes=fs.readFileSync(file);
+    return [{path:name,sha256:digest(bytes),bytes:bytes.length}];
+  });
+}
+
+/** Immutable data-only closure. Never copy HOME, auth, bin, live channels or service capabilities. */
+export function retainEvaluation(input:{runRoot:string;artifact:string;artifactDigest:string;destination:string}):RetainedEvaluation {
+  const {runRoot,artifact,artifactDigest,destination}=input;
+  assertRetentionDestination(destination,[runRoot,artifact]);
+  if(fingerprint(artifact)!==artifactDigest)throw Error('Artifact changed before retention');
+  fs.mkdirSync(destination,{mode:0o700});
+  copyArtifact({source:artifact,destination:path.join(destination,'artifact')});
+  const copy=(source:string,relative:string)=>{
+    if(!fs.existsSync(source))return;
+    const stat=fs.lstatSync(source);
+    if(stat.isSymbolicLink())throw Error('Runtime evidence symlink rejected');
+    const target=path.join(destination,relative);
+    if(stat.isDirectory()){
+      fs.mkdirSync(target,{recursive:true,mode:0o700});
+      for(const name of fs.readdirSync(source))copy(path.join(source,name),path.join(relative,name));
+    }else if(stat.isFile()){
+      fs.mkdirSync(path.dirname(target),{recursive:true,mode:0o700});
+      fs.writeFileSync(target,fs.readFileSync(source),{flag:'wx',mode:0o600});
+    }else throw Error('Unsupported runtime evidence');
+  };
+  for(const name of ['input','logs','target-input.json','final-input.json','coding-scope.json','groups.json','decision.json','report.json','ledger.jsonl','reservations.jsonl','invocations.jsonl','execution-profile.json','execution-preflight.json','runtime-preflight.json','judge-runtime-preflight.json','counter-review.json'])copy(path.join(runRoot,name),path.join('evaluation',name));
+  // Exact final model outputs are data; other scratch may contain runtime capabilities.
+  const invocationFile=path.join(runRoot,'invocations.jsonl');
+  if(fs.existsSync(invocationFile))for(const line of fs.readFileSync(invocationFile,'utf8').trim().split('\n')){
+    if(!line)continue;
+    const {id}=JSON.parse(line) as {id:string};
+    if(!/^[a-zA-Z0-9-]+$/.test(id))throw Error('Invalid retained invocation identity');
+    copy(path.join(runRoot,'home','tmp','turn-'+id,id+'.json'),path.join('model-output',id+'.json'));
+  }
+  if(fingerprint(artifact)!==artifactDigest)throw Error('Artifact changed during retention');
+  const value:RetainedEvaluation={version:1,closed:fs.existsSync(path.join(runRoot,'decision.json'))&&fs.existsSync(path.join(runRoot,'report.json')),artifactDigest,originalRunRoot:runRoot,originalArtifactRoot:artifact,files:inventory(destination),limitations:['Data-only immutable evidence; not an executable checkpoint','Hashes establish byte consistency, not semantic correctness or a signature','Original target bytes are in target-input/final-input; absolute original paths are historical locators','Partial closures preserve failures and cannot certify completion']};
+  fs.writeFileSync(path.join(destination,'archive.json'),JSON.stringify(value,null,2)+'\n',{flag:'wx',mode:0o600});
+  return value;
+}
+
+/** Read-only verification works after every original temporary directory is gone. */
+export function verifyRetainedEvaluation(root:string):RetainedEvaluation {
+  absoluteDirectory(root);
+  const manifest=path.join(root,'archive.json');
+  if(fs.lstatSync(manifest).isSymbolicLink())throw Error('Archive manifest symlink rejected');
+  const value=JSON.parse(fs.readFileSync(manifest,'utf8')) as RetainedEvaluation;
+  if(value.version!==1||!Array.isArray(value.files)||typeof value.closed!=='boolean')throw Error('Invalid retained evidence manifest');
+  for(const entry of value.files){
+    if(!entry.path||path.isAbsolute(entry.path)||entry.path.split(/[\\/]/).some(part=>!part||part==='.'||part==='..')||entry.path==='archive.json')throw Error('Unsafe retained path');
+  }
+  const actual=inventory(root).filter(entry=>entry.path!=='archive.json');
+  if(JSON.stringify(actual)!==JSON.stringify(value.files))throw Error('Retained evidence missing, changed or extended');
+  return value;
+}

package/support/runtime-binding.ts

@@ -0,0 +1,39 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type {RuntimeSpec} from '../contract';
+import type {AgentRun} from './agent-runtime';
+
+export function environmentName(name:string):void {
+  if(!/^[_A-Z][_A-Z0-9]*$/.test(name)||['HOME','PATH','CODEX_HOME','TMPDIR','NODE_OPTIONS','BUN_OPTIONS','PYTHONSTARTUP','BASH_ENV','ENV','SHELLOPTS','GIT_CONFIG','GIT_CONFIG_GLOBAL','GIT_CONFIG_SYSTEM'].includes(name)||/^(DYLD_|LD_)/.test(name))throw Error('Runtime system overrides forbidden');
+}
+
+/** Trusted deployment data only: explicit aliases, dependencies and literal environment. */
+export function bindRuntime(run:AgentRun,spec:RuntimeSpec|undefined):AgentRun {
+  if(!spec)return run;
+  const readPaths=(spec.readPaths??[]).map(file=>{
+    if(!path.isAbsolute(file))throw Error('Runtime dependency roots must be absolute');
+    const real=fs.realpathSync(file);
+    if(!fs.statSync(real).isDirectory())throw Error('Runtime dependency root must be a directory');
+    if(real===run.workspace||real.startsWith(run.workspace+'/'))return real;
+    // Dependencies may live in a separate owned temporary installation, not personal
+    // data, owner records or arbitrary filesystem roots. Original artifacts stay readonly.
+    if(!/^\/private\/tmp\/[^/]+\/.+/.test(real)||real===run.root||real.startsWith(run.root+'/')||run.root.startsWith(real+'/'))throw Error('Runtime dependency root exceeds readonly temporary capability');
+    return real;
+  });
+  const environment={...spec.environment};
+  for(const [name,value] of Object.entries(environment)){environmentName(name);if(typeof value!=='string'||value.includes('\0'))throw Error('Literal runtime environment required');}
+  const executables:Record<string,string>={};
+  const home=os.homedir(),allowed=[path.join(home,'.bun/bin'),path.join(home,'.local/share/uv/python'),'/usr','/bin','/opt','/System','/Library'];
+  for(const [name,file] of Object.entries(spec.executables??{})){
+    if(!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name)||['codex','ego-browser'].includes(name)||!path.isAbsolute(file))throw Error('Explicit non-agent tool alias required');
+    const real=fs.realpathSync(file);
+    if(!allowed.some(root=>real.startsWith(root+'/'))&&!readPaths.some(root=>real.startsWith(root+'/')))throw Error('Executable is outside declared host tools or readonly dependency roots');
+    fs.accessSync(real,fs.constants.X_OK);executables[name]=real;
+  }
+  const bin=path.join(run.root,'bin','runtime');fs.mkdirSync(bin,{mode:0o700});
+  for(const [name,file] of Object.entries(executables))fs.symlinkSync(file,path.join(bin,name));
+  const bindings={executables,readPaths,environment};
+  fs.writeFileSync(path.join(run.root,'runtime-bindings.json'),JSON.stringify(bindings,null,2),{flag:'wx'});
+  return {...run,env:{...run.env,...environment,PATH:`${bin}:${run.env.PATH}`},runtimeReadPaths:[bin,...readPaths,...Object.values(executables)],runtimeBindings:bindings};
+}

package/support/runtime-preflight.ts

@@ -0,0 +1,16 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {AgentRun,AgentRuntime} from './agent-runtime';
+import {boundary,digest} from './isolation';
+import {executeNative} from './process';
+/** No model/auth/implementation: exercise the actual runtime through the exact boundary. */
+export async function preflightJudgeRuntime(run:AgentRun,agent:AgentRuntime,timeoutMs=10000,name='runtime-preflight') {
+  if(!/^[a-z][a-z0-9-]{0,80}$/.test(name))throw Error('Invalid runtime preflight name');
+  const log=path.join(run.root,'logs',`${name}.log`);
+  const result=await executeNative({interrupted:false},{argv:boundary(run,agent,'judge',[agent.executable(run),'--version']),cwd:run.controlWorkspace??run.workspace,env:run.env,log,timeoutMs});
+  const content=fs.readFileSync(log,'utf8');
+  const receipt={...result,executable:agent.executable(run),outputDigest:digest(content),output:content,modelInvoked:false};
+  fs.writeFileSync(path.join(run.root,`${name}.json`),JSON.stringify(receipt,null,2)+'\n',{flag:'wx'});
+  if(result.code!==0||!content.includes('codex-cli'))throw Error(`Judge runtime preflight failed before model use: ${content}`);
+  return receipt;
+}

package/support/service-evidence.ts

@@ -0,0 +1,23 @@
+import * as path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import type {Observation,OwnedServiceCommand,ProcessProbe,ServiceLaunchReceipt} from '../contract';
+import {digest} from './isolation';
+
+/** Project an actual native launch into the same immutable fact catalog. */
+export function serviceObservation(input:{runId:string;artifactDigest:string},serviceId:string,receipt:ServiceLaunchReceipt):Observation {
+  const content=JSON.stringify({serviceId,...receipt});
+  return {id:randomUUID(),...input,phase:'observation',channel:'process',purpose:'delivery',method:'native owned service launch/readiness',conditions:'Declared deployment argv/cwd, native fresh port and initially empty leased state; only explicit port/data/dependency environment projected',content,contentDigest:digest(content),bytes:Buffer.byteLength(content),elapsedMs:receipt.elapsedMs,status:'completed',argv:receipt.argv,limitations:['Availability and supplied launch conditions only, not proof of application business correctness','Fresh directory and supplied environment do not prove the application exclusively stores state there','Inherited environment and credentials are deliberately not projected']};
+}
+
+/** Finite process channel cannot duplicate a declared long-lived lease. */
+export function assertTerminatingProcess(probe:ProcessProbe,services:OwnedServiceCommand[],executables:Record<string,string>):void {
+  const executable=(value:string)=>executables[value]??value;
+  const repeated=services.find(service=>{
+    if(path.normalize(probe.cwd??'.')!==path.normalize(service.cwd??'.'))return false;
+    if(probe.argv.length!==service.argv.length)return false;
+    return probe.argv.every((value,index)=>index===0
+      ? executable(value)===executable(service.argv[index]!)
+      : value===service.argv[index]);
+  });
+  if(repeated)throw Error(`Process channel requires a terminating command; service ${repeated.serviceId} is already leased. Read its native launch receipt or use the explicitly granted owned restart capability`);
+}

package/support/service-group.ts

@@ -0,0 +1,45 @@
+import type {ServiceGraph,ServiceNode} from '../contract';
+import type {AgentRun,AgentRuntime} from './agent-runtime';
+import {startService,serviceDirectory} from './service';
+import {environmentName} from './runtime-binding';
+
+/** Pure dependency plan. IDs denote deployment nodes, never application scenarios. */
+export function serviceOrder(graph:ServiceGraph):ServiceNode[] {
+  if(!graph||!Array.isArray(graph.nodes)||!graph.nodes.length||graph.nodes.length>8)throw Error('Service graph needs 1..8 declared nodes');
+  const nodes=new Map<string,ServiceNode>();
+  for(const node of graph.nodes){if(!/^[a-zA-Z0-9][\w-]*$/.test(node.id)||nodes.has(node.id))throw Error('Unique service IDs required');nodes.set(node.id,node);}
+  if(!nodes.has(graph.entry))throw Error('Unknown entry service');
+  const visited=new Set<string>(),pending=new Set<string>(),order:ServiceNode[]=[];
+  function visit(id:string):void {
+    if(visited.has(id))return;
+    const node=nodes.get(id);if(!node)throw Error('Unknown linked service');
+    if(pending.has(id))throw Error('Cyclic service dependency');pending.add(id);
+    for(const [name,target] of Object.entries(node.links??{})){environmentName(name);visit(target);}
+    pending.delete(id);visited.add(id);order.push(node);
+  }
+  for(const id of nodes.keys())visit(id);
+  return order;
+}
+
+/** Exact owned origins, dependency-only network and reverse lifecycle cleanup. */
+export async function startServices(runtime:{run:AgentRun;agent:AgentRuntime;deadlineAt:number},graph:ServiceGraph) {
+  const order=serviceOrder(graph);
+  for(const node of order)serviceDirectory(runtime.run.workspace,node.cwd);
+  const leases=new Map<string,Awaited<ReturnType<typeof startService>>>();
+  let closing:Promise<void>|undefined;
+  const close=()=>closing??=(async()=>{
+    const errors:unknown[]=[];
+    for(const lease of [...leases.values()].reverse())try{await lease.close();}catch(error){errors.push(error);}
+    if(errors.length)throw new AggregateError(errors,'Service graph cleanup failed');
+  })();
+  try{
+    for(const node of order){
+      const environment=Object.fromEntries(Object.entries(node.links??{}).map(([name,id])=>[name,leases.get(id)!.origin]));
+      const outboundPorts=Object.values(node.links??{}).map(id=>Number(new URL(leases.get(id)!.origin).port));
+      leases.set(node.id,await startService(runtime,node,{environment,outboundPorts}));
+    }
+    return {origin:leases.get(graph.entry)!.origin,origins:Object.fromEntries([...leases].map(([id,lease])=>[id,lease.origin])),receipts:[...leases].map(([serviceId,lease])=>({serviceId,receipt:lease.receipt})),close,restart:async(id:string,deadlineAt?:number)=>{
+      if(closing)throw Error('Service graph is closed');const lease=leases.get(id);if(!lease)throw Error('Unknown owned service');return lease.restart(deadlineAt);
+    }};
+  }catch(error){await close();throw error;}
+}

package/support/service.ts

@@ -0,0 +1,84 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {spawn} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import type {ServiceSpec,ServiceLaunchReceipt} from '../contract';
+import type {AgentRun,AgentRuntime} from './agent-runtime';
+import {boundary} from './isolation';
+import {environmentName} from './runtime-binding';
+
+export function serviceDirectory(workspace:string,relative='.') :string {
+  const root=fs.realpathSync(workspace),file=path.resolve(root,relative);
+  if(file!==root&&!file.startsWith(root+'/'))throw Error('Service cwd escapes artifact');
+  const real=fs.realpathSync(file);if(real!==file||!fs.statSync(real).isDirectory())throw Error('Service cwd must be a real artifact directory');
+  return file;
+}
+
+export function originPath(origin:string,relative:string):string {
+  if(typeof relative!=='string'||!relative.startsWith('/')||relative.startsWith('//')||relative.includes('\\')||/[\r\n]/.test(relative))throw Error('Literal origin-relative path required');
+  const url=new URL(relative,origin);
+  if(url.origin!==origin||url.pathname!==relative.split('?')[0])throw Error('Path escapes leased origin or is normalized');
+  return url.href;
+}
+/** One native service/data lease. No application-specific setup, assertions or commands. */
+export async function startService(runtime:{run:AgentRun;agent:AgentRuntime;deadlineAt:number},spec:ServiceSpec,binding:{environment:Record<string,string>;outboundPorts:number[]}={environment:{},outboundPorts:[]}) {
+  if(!Array.isArray(spec.argv)||!spec.argv.length||spec.argv.some(s=>typeof s!=='string'||!s.trim()))throw Error('Service requires explicit argv');
+  const envNames=[spec.portEnv,...spec.dataEnv,...Object.keys(spec.dataFiles??{}),...Object.keys(binding.environment)];
+  if(new Set(envNames).size!==envNames.length)throw Error('Declare distinct port/data/link env names');
+  for(const name of envNames)environmentName(name);
+  for(const name of Object.values(spec.dataFiles??{}))if(!name||path.isAbsolute(name)||name.split(/[\\/]/).some(part=>part==='..'||part==='.')||name.includes('\0'))throw Error('Data file must be a safe lease-relative path');
+  if(spec.readyTimeoutMs!==undefined&&(!Number.isSafeInteger(spec.readyTimeoutMs)||spec.readyTimeoutMs<1||spec.readyTimeoutMs>30000))throw Error('Readiness bound must be 1..30000ms');
+  const {run,agent}=runtime,leaseId=randomUUID(),data=path.join(run.home,'tmp',`service-${leaseId}`);
+  const allocation=Bun.serve({hostname:'127.0.0.1',port:0,fetch:()=>new Response('allocation')});
+  const port=allocation.port!;allocation.stop(true);
+  const origin=`http://127.0.0.1:${port}`,ready=originPath(origin,spec.readyPath);
+  fs.mkdirSync(data,{mode:0o700});
+  const environment={...binding.environment,[spec.portEnv]:String(port),...Object.fromEntries(spec.dataEnv.map(n=>[n,data])),...Object.fromEntries(Object.entries(spec.dataFiles??{}).map(([name,file])=>[name,path.join(data,file)]))};
+  const env={...run.env,...environment},cwd=serviceDirectory(run.execution?.root??run.workspace,spec.cwd);
+  const argv=boundary(run,agent,'service',spec.argv,[],port,[],binding.outboundPorts);
+  const lifecycle=path.join(run.root,'logs',`service-${leaseId}-lifecycle.jsonl`);
+  const record=(event:object)=>fs.appendFileSync(lifecycle,JSON.stringify({leaseId,origin,data,at:Date.now(),...event})+'\n');
+  let child:ReturnType<typeof spawn>|undefined,failure:unknown,closing:Promise<void>|undefined,generation=0;
+  const stop=()=>{try{if(child?.pid)process.kill(-child.pid,'SIGKILL');}catch{/* own group already closed */}};
+  process.once('SIGTERM',stop);process.once('SIGINT',stop);
+  const stopGeneration=async()=>{
+    const current=child;stop();
+    if(current?.exitCode===null&&current.signalCode===null)await Promise.race([new Promise<void>(resolve=>current.once('close',()=>resolve())),Bun.sleep(2000)]);
+    let reachable=false;try{await fetch(origin,{signal:AbortSignal.timeout(500)});reachable=true;}catch{/* no listener */}
+    record({kind:'generation-stopped',generation,pid:current?.pid,reachable});
+    if(reachable)throw Error('Owned service endpoint remained reachable after close');
+  };
+  const close=()=>closing??=(async()=>{
+    process.off('SIGTERM',stop);process.off('SIGINT',stop);await stopGeneration();
+    fs.writeFileSync(path.join(run.root,`service-${leaseId}-closed.json`),JSON.stringify({leaseId,pid:child?.pid,origin,reachable:false,generations:generation+1}));
+  })();
+  const launch=async(phaseDeadlineAt=runtime.deadlineAt)=>{
+    const started=Date.now();
+    if(Date.now()>=Math.min(runtime.deadlineAt,phaseDeadlineAt))throw Error('Service window expired before launch');
+    failure=undefined;
+    const log=path.join(run.root,'logs',`service-${leaseId}${generation?'-generation-'+generation:''}.log`),fd=fs.openSync(log,'wx',0o600);
+    try{child=spawn(argv[0]!,argv.slice(1),{cwd,env,detached:true,stdio:['ignore',fd,fd]});}finally{fs.closeSync(fd);}
+    child.on('error',e=>{failure=e;});
+    const deadline=Math.min(runtime.deadlineAt,phaseDeadlineAt,Date.now()+(spec.readyTimeoutMs??15000));
+    while(Date.now()<deadline){
+      if(failure||child.exitCode!==null||child.signalCode!==null)throw Error(`Service exited before readiness: ${String(failure??fs.readFileSync(log,'utf8'))}`);
+      try{
+        // Any actual HTTP response proves readiness, not business correctness.
+        const response=await fetch(ready,{redirect:'manual',signal:AbortSignal.timeout(Math.min(1000,Math.max(1,deadline-Date.now())))});
+        await response.body?.cancel();
+        const receipt:ServiceLaunchReceipt={leaseId,pid:child.pid,origin,data,argv:[...spec.argv],cwd,generation,environment,state:{directory:data,initiallyEmpty:true},readiness:{path:spec.readyPath,status:response.status},semanticPass:false,elapsedMs:Date.now()-started};
+        record({kind:'generation-ready',...receipt});
+        if(!generation)fs.writeFileSync(path.join(run.root,`service-${leaseId}.json`),JSON.stringify(receipt));
+        return receipt;
+      }catch{/* wait only until the declared startup deadline */}
+      await Bun.sleep(Math.min(200,Math.max(0,deadline-Date.now())));
+    }
+    throw Error('Native service readiness deadline exhausted');
+  };
+  const restart=async(phaseDeadlineAt=runtime.deadlineAt)=>{
+    if(closing||Date.now()>=Math.min(runtime.deadlineAt,phaseDeadlineAt))throw Error('Closed or expired service lease cannot restart');
+    const previousPid=child?.pid;await stopGeneration();generation++;
+    try{return {...await launch(phaseDeadlineAt),previousPid,statePreserved:true};}catch(error){await close();throw error;}
+  };
+  try{const receipt=await launch();return {leaseId,origin,data,receipt,close,restart};}catch(error){await close();throw error;}
+}

package/support/source-identity.ts

@@ -0,0 +1,22 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {digest} from './isolation';
+
+/** Evaluator source identity, distinct from the strict delivered-artifact fingerprint.
+ * Installed dependency/cache trees are not source; the independent lock is source.
+ */
+export function evaluatorSourceDigest(root: string): string {
+  const excluded = new Set(['node_modules', '.git', 'dist', 'coverage', '.tmp']);
+  function walk(directory: string): string[] {
+    const entries = fs.readdirSync(directory, {withFileTypes: true})
+      .sort((a, b) => a.name.localeCompare(b.name));
+    return entries.flatMap(entry => {
+      if (entry.isDirectory() && excluded.has(entry.name)) return [];
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw Error(`Evaluator source contains a symlink: ${file}`);
+      if (entry.isDirectory()) return walk(file);
+      return [`${path.relative(root, file)}:${digest(fs.readFileSync(file))}`];
+    });
+  }
+  return digest(walk(root).join('\n'));
+}

package/support/target-group-view.ts

@@ -0,0 +1,11 @@
+import {readFileSync} from 'node:fs';
+import {isAbsolute} from 'node:path';
+import {projectTargetGroups,type TargetGroup} from '../target-groups';
+
+/** Explicit readonly files only; no history discovery or new model/effect. */
+export function readTargetGroupView(inputPath:string,decisionPath:string,groups:TargetGroup[]) {
+  if(!isAbsolute(inputPath)||!isAbsolute(decisionPath))throw Error('Absolute native input and decision paths required');
+  const input=JSON.parse(readFileSync(inputPath,'utf8'));
+  const decision=JSON.parse(readFileSync(decisionPath,'utf8'));
+  return projectTargetGroups(input,decision,groups,{policyVersion:decision.policyVersion,includeCommitments:input.policy?.includeCommitments??false});
+}

package/target-groups.ts

@@ -0,0 +1,57 @@
+import type {Decision,EvaluationConfig,EvaluationInput,Judgment} from './contract';
+import {admit,defaultConfig} from './logic';
+import {obligationGraph} from './obligation-graph';
+import {canonicalIdentity} from './representation';
+
+/** Caller-owned presentation scope. Labels never add requirements or evidence. */
+export interface TargetGroup {id:string;label:string;rootIds:string[]}
+
+/** Project an admitted graph, not a second judge. Never infer groups from names,
+ * source wording, domains, historical scores or model completion assertions.
+ */
+export function projectTargetGroups(input:EvaluationInput,decision:Decision,groups:TargetGroup[],config:EvaluationConfig=defaultConfig) {
+  if(decision.runId!==input.runId||decision.artifactDigest!==input.artifactDigest||decision.policyVersion!==config.policyVersion)throw Error('Group view requires the same native evaluation identity and policy');
+  if(canonicalIdentity(input.observations)!==canonicalIdentity(decision.observations))throw Error('Group view requires the original decision observations, not later or altered facts');
+  if(!Array.isArray(groups)||groups.length>64)throw Error('At most 64 explicit target groups');
+  const ids=new Set<string>();
+  for(const g of groups){
+    if(!g||typeof g.id!=='string'||!g.id.trim()||ids.has(g.id)||typeof g.label!=='string'||!g.label.trim()||!Array.isArray(g.rootIds)||!g.rootIds.length||g.rootIds.some(id=>typeof id!=='string'||!id.trim())||new Set(g.rootIds).size!==g.rootIds.length)throw Error('Groups need unique IDs, labels and distinct nonempty root IDs');
+    ids.add(g.id);
+  }
+  const proposal=decision.proposal;
+  const diagnostics=proposal?admit(input,proposal,config):[];
+  const eligible=decision.execution==='completed'&&decision.diagnostics.length===0&&proposal!==null&&diagnostics.length===0&&decision.judgment===proposal.judgment;
+  // Rejected/unfinished drafts cannot yield a partial success view.
+  const graph=eligible?obligationGraph(proposal!):undefined;
+  const roots=graph?.roots??[];
+  const rootIds=new Set(roots.map(o=>o.id));
+  const obligations=new Map(proposal?.obligations.map(o=>[o.id,o]));
+  if(graph)for(const g of groups)for(const id of g.rootIds)if(!rootIds.has(id))throw Error('Group references an unknown or non-root obligation: '+id);
+  const selected=new Set(groups.flatMap(g=>g.rootIds));
+  function sourcesFor(id:string,seen=new Set<string>()):Set<string> {
+    if(seen.has(id))return new Set();seen.add(id);
+    const o=obligations.get(id)!;
+    return new Set([o.sourceId,...o.children.flatMap(child=>[...sourcesFor(child,seen)])]);
+  }
+  const results=groups.map(g=>{
+    let judgment:Judgment='indeterminate';
+    let reason='No complete admitted decision is available; drafts cannot be mined for partial success.';
+    let sourceIds:string[]=[];
+    if(graph){
+      const outcomes=g.rootIds.map(id=>graph.compare(id)).filter(o=>o.judgment!=='not-applicable');
+      sourceIds=[...new Set(g.rootIds.flatMap(id=>[...sourcesFor(id)]))];
+      const reviewed=sourceIds.every(id=>proposal!.sourceReviews.some(r=>r.sourceId===id&&r.complete&&!r.omissions.length&&!r.ambiguities.length));
+      if(outcomes.some(o=>o.judgment==='fail')){judgment='fail';reason='An admitted selected required root is contradicted.';}
+      else if(outcomes.length&&outcomes.every(o=>o.judgment==='pass')&&reviewed){judgment='pass';reason='All selected applicable roots are supported; related source reviews contain no recorded gaps.';}
+      else reason=outcomes.length?'A selected root or its source review remains unresolved.':'No selected applicable root was evaluated; not-applicable is not PASS.';
+    }
+    return {...g,rootIds:[...g.rootIds],sourceIds,judgment,reason};
+  });
+  return {runId:decision.runId,artifactDigest:decision.artifactDigest,
+    overall:{execution:decision.execution,judgment:decision.judgment,failureClass:decision.failureClass},
+    scope:'caller-selected-root-obligations' as const,groups:results,
+    ungroupedRootIds:roots.filter(o=>!selected.has(o.id)).map(o=>o.id),
+    sharedRootIds:roots.filter(o=>groups.filter(g=>g.rootIds.includes(o.id)).length>1).map(o=>o.id),
+    semanticAuthority:false as const,
+    limitations:['A group label does not certify unlisted requirements or a whole domain.','This is a view of the original fallible judgment, not a fresh assessment or authorization to change the artifact.','Overall judgment and exit semantics remain unchanged; overlapping groups must not be averaged.']};
+}