@yunhozz/arc 0.1.9 → 0.1.10

package/lib/runtime/cooperative.mjs

@@ -0,0 +1,136 @@
+import {EXTERNAL_ACTIONS,reconcileCooperativeExternal,cooperativeSupport} from './external.mjs';
+import {reconcileCooperativeCommit} from './acceptance.mjs';
+import {evaluateCooperativeVerification,invalidateAffectedEvidence,readCooperativeChanges} from './verification.mjs';
+import {readAssignmentGitEvidence,readCooperativeCommitGitEvidence} from './git-evidence.mjs';
+import {recordCooperativeAssignmentResult} from './assignment.mjs';
+import fs from 'node:fs/promises';
+import {validateCooperativeCommand,validateCooperativeState} from './cooperative-schema.mjs';
+import {observeCooperativeTarget,validateObservedTarget,validateWorkflowId,workflowStatePath,inspectPath,absolute,within} from './scope.mjs';
+import {fingerprintRequest,saveDurableState,applyCooperativeCommitTransition} from './store.mjs';
+import {commandResult,cooperativeVersions} from './bootstrap.mjs';
+import {evaluateCooperative,reconcileCooperativeResult} from './evaluate.mjs';
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+const sameCheckout=(a,b)=>['realpath','gitCommonDir','gitDir'].every(k=>a[k]===b[k]);
+/** Only trusted code may inject observation/storage. CLI JSON cannot set either. */
+export async function runCooperativeCommand({cwd,workflowId,command,input,observe=observeCooperativeTarget,storage={},readGit=readAssignmentGitEvidence,readChanges=readCooperativeChanges,readCommitGit=readCooperativeCommitGitEvidence}){
+ validateWorkflowId(workflowId);validateCooperativeCommand({command,input});
+ if(command==='init')throw Error('Use initializeCooperativeWorkflow for init');
+ const target=await validateObservedTarget(cwd,await observe(cwd)),statePath=await workflowStatePath(target,workflowId);
+ const read=async()=>{await inspectPath(statePath);const state=validateCooperativeState(JSON.parse(await fs.readFile(statePath,'utf8')));if(state.workflowId!==workflowId)throw Error('Workflow identity mismatch');return state;};
+ const result=(state,decision,extra={})=>commandResult({workflowId,state,input,...decision,...extra});
+ if(command==='status'){
+  const state=await read();
+  if(!sameCheckout(state.target,target))return result(undefined,{decision:'hold',ruleIds:['cooperative.target']});
+  const changes=state.tasks.length?await readChanges({state}):undefined;
+  const evaluation=evaluateCooperative({state,request:{command,input},evidence:{target,versions:await cooperativeVersions(),changes}});
+  const unresolved=state.unresolved.some(entry=>!entry.resolvedBy)||state.intents.some(i=>['prepared','unknown','mismatch'].includes(i.status)&&!(['check','review'].includes(i.operation)&&i.stale));
+  return {...result(state,evaluation.decision==='allow'&&unresolved?{decision:'hold',ruleIds:['cooperative.unresolved']}:evaluation,{persisted:true}),state,support:cooperativeSupport(),...(changes?{changeFingerprints:changes}:{})};
+ }
+ let lock;
+ try{
+  lock=await fs.open(statePath+'.lock','wx',0o600);let state=await read();
+  if(!sameCheckout(state.target,target))return result(state,{decision:'hold',ruleIds:['cooperative.target']});
+  const requestFingerprint=fingerprintRequest({command,input});const prior=state.requests.find(r=>r.requestId===input.requestId);
+  if(prior){if(prior.requestFingerprint!==requestFingerprint)throw Error('Request fingerprint conflict');return result(state,{decision:'hold',ruleIds:['cooperative.replay']},{replayed:true});}
+  if(!['reconcile','result'].includes(command)&&input.expectedRevision!==state.revision)return result(state,{decision:'hold',ruleIds:[['prepare','result'].includes(command)?'cooperative.unsupported':'cooperative.revision']});
+  const currentTarget=await validateObservedTarget(cwd,await observe(cwd));
+  if(!sameCheckout(state.target,currentTarget))return result(state,{decision:'hold',ruleIds:['cooperative.target']});
+  const versions=await cooperativeVersions();
+  let git,gitError;
+  if(command==='prepare'&&input.operation==='assign-agent'&&input.arguments&&same(currentTarget,state.target)){
+   try{git=await readGit({target:currentTarget,documents:input.arguments?.documents??[]});}catch(error){gitError=error.message;}
+  }
+  const commitIntent=['result','reconcile'].includes(command)?state.intents.find(i=>i.requestId===input.intentId&&i.operation==='commit'):undefined;
+  if(command==='prepare'&&['accept','commit'].includes(input.operation)||commitIntent){
+   try{git=await readCommitGit({target:currentTarget,...(commitIntent&&input.result?.data?.commit?{commit:input.result.data.commit}:{})});}catch(error){gitError=error.message;}
+  }
+  const changes=state.tasks.length?await readChanges({state}):undefined;
+  let decision=evaluateCooperative({state,request:{command,input},evidence:{target:currentTarget,versions,git,changes}});
+  if(gitError)decision={decision:'hold',ruleIds:[input.operation==='assign-agent'?'cooperative.documents':'cooperative.git-evidence'],reason:gitError};
+  if(command==='prepare'&&decision.decision==='allow'){
+   if(decision.proposedTransition?.intent)state.intents.push(decision.proposedTransition.intent);
+   if(decision.proposedTransition?.acceptance){state.acceptances.push(decision.proposedTransition.acceptance);state.tasks.find(t=>t.id===input.taskId).status='accepted';}
+  }
+  if(['reconcile','result'].includes(command)&&input.result){
+   if(input.expectedRevision!==state.revision)state.unresolved.push({kind:'stale-result',requestId:input.requestId,intentId:input.intentId,expectedRevision:input.expectedRevision,revision:state.revision+1});
+   let intent=state.intents.find(i=>i.requestId===input.intentId);
+   decision=EXTERNAL_ACTIONS.includes(intent?.operation)?reconcileCooperativeExternal({state,intent,result:input.result,observations:{target:currentTarget}}):intent?.operation==='commit'?reconcileCooperativeCommit({state,intent,result:input.result,gitEvidence:git}):['check','review'].includes(intent?.operation)?evaluateCooperativeVerification({state,request:{...input,operation:'verification-result'},evidence:{changes}}):intent?.operation==='assign-agent'?recordCooperativeAssignmentResult({state,intent,result:input.result,observations:{target:currentTarget}}):reconcileCooperativeResult({state,intent,result:input.result,observations:{target:currentTarget}});
+   if(['assign-agent','check','review','commit',...EXTERNAL_ACTIONS].includes(intent?.operation)&&!same(versions,state.versions))decision={...decision,decision:'hold',ruleIds:['cooperative.versions']};
+   if(input.expectedRevision!==state.revision)decision={...decision,decision:'hold',ruleIds:['cooperative.revision']};
+   if((intent?.operation==='commit'||EXTERNAL_ACTIONS.includes(intent?.operation))&&input.actor.role!=='orchestrator')decision={...decision,decision:'hold',ruleIds:['cooperative.acceptance-actor']};
+   if(['check','review'].includes(intent?.operation)&&!same(currentTarget,state.target))decision={...decision,decision:'hold',ruleIds:['cooperative.target']};
+   if(intent?.operation==='commit'){
+    const verified=decision.proposedTransition;
+    // Failed reconciliation records what actually happened without changing target.
+    const observation={intentId:input.intentId,revision:state.revision+1,observation:verified?.observation??git??null,source:'local-git',...(gitError?{error:gitError}:{})};
+    if(decision.decision==='allow'){
+     state=applyCooperativeCommitTransition({state,decision});
+     intent=state.intents.find(i=>i.requestId===input.intentId);
+     const committedChanges=await readChanges({state}),commit=state.commits.at(-1);commit.postCommitFingerprint=committedChanges.tasks[intent.taskId];
+     if(committedChanges.taskSnapshots){
+      commit.snapshot=structuredClone(committedChanges.taskSnapshots[intent.taskId]);
+      const changedPaths=commit.paths.map(p=>state.target.realpath+'/'+p);
+      for(const prior of state.commits.slice(0,-1)){
+       const snapshot=prior.snapshotConnections?.at(-1)?.snapshot??prior.snapshot,current=committedChanges.taskSnapshots[prior.taskId];
+       if(!snapshot||!current||!changedPaths.some(p=>snapshot.paths.some(base=>within(base,p))))continue;
+       const projected=structuredClone(snapshot);for(const key of ['index','rows'])projected[key]=[...snapshot[key].filter(row=>!changedPaths.includes(row.path)),...current[key].filter(row=>changedPaths.includes(row.path))].sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+       prior.snapshotConnections??=[];prior.snapshotConnections.push({commit:commit.commit,requestId:input.requestId,snapshot:projected,fingerprint:fingerprintRequest(projected)});prior.postCommitFingerprint=fingerprintRequest(projected);
+      }
+     }
+     for(const entry of state.unresolved)if(entry.kind==='target-changed'&&entry.intentId===input.intentId)entry.resolvedBy=input.requestId;
+    }
+    state.commitObservations??=[];state.commitObservations.push(observation);
+    if(decision.decision!=='allow'&&verified?.result?.status==='succeeded')verified.result.status='mismatch';
+   }
+   const verification=decision.proposedTransition;
+   if(verification?.check){
+    if(decision.decision!=='allow'&&verification.check.status==='passed'){verification.check.status='unverified';verification.check.stale=true;verification.findings=[];verification.result.status='mismatch';}
+    state.checks.push(verification.check);for(const finding of verification.findings){const index=state.findings.findIndex(f=>f.id===finding.id);if(index<0)state.findings.push(finding);else state.findings[index]=finding;}
+   }
+   if(intent?.operation==='assign-agent'&&decision.decision!=='allow'&&decision.proposedTransition?.result&&['succeeded','failed'].includes(decision.proposedTransition.result.status))decision.proposedTransition.result.status='mismatch';
+   if(EXTERNAL_ACTIONS.includes(intent?.operation)&&decision.decision!=='allow'&&decision.proposedTransition?.result&&(decision.proposedTransition.result.status==='succeeded'||decision.ruleIds[0]!=='cooperative.external'))decision.proposedTransition.result.status='mismatch';
+   if(decision.decision==='allow'&&input.expectedRevision===state.revision&&['succeeded','failed','cancelled'].includes(decision.proposedTransition?.result?.status))for(const entry of state.unresolved)if(entry.kind==='stale-result'&&entry.intentId===input.intentId&&!entry.resolvedBy){entry.resolvedBy=input.requestId;entry.resolutionEvidence={intentId:input.intentId,resultRef:input.result.messageRef,revision:state.revision};}
+   const actualResult=decision.proposedTransition?.result??input.result;
+   // Preserve actual statements even when runtime/HEAD changed, without rebinding target.
+   if(!same(currentTarget,state.target)){state.targetHistory.push({target:currentTarget,revision:state.revision+1,source:'local-observation'});state.unresolved.push({kind:'target-changed',...(intent?.operation==='commit'?{intentId:input.intentId}:{}),revision:state.revision+1});}
+   if(!same(versions,state.versions))state.unresolved.push({kind:'versions-changed',revision:state.revision+1});
+   state.results.push({...actualResult,requestId:input.intentId,recordRequestId:input.requestId,actor:input.actor,source:'operator-attested'});
+   if(intent&&(['assign-agent','check','review','commit',...EXTERNAL_ACTIONS].includes(intent.operation)?decision.proposedTransition?.result&&['prepared','unknown','mismatch'].includes(intent.status):true)){
+    intent.status=actualResult.status;
+    if(decision.decision==='allow'&&actualResult.status==='succeeded'&&intent.operation==='assign-agent')state.assignments.push({intentId:intent.requestId,taskId:intent.taskId,agentId:actualResult.data.agentId,status:'active',source:'operator-attested',identityVerified:false});
+   }
+   else state.unresolved.push({kind:'unmatched-result',requestId:input.intentId,revision:state.revision+1});
+  }else if(command==='record'&&decision.decision==='allow'){
+   const entry={...input.evidence,actor:input.actor,source:'operator-attested',requestId:input.requestId,revision:state.revision+1,scopeVersion:state.scopeVersion,targetVersion:state.targetVersion};
+   if(entry.kind==='scope'){
+    if(!Array.isArray(entry.data.paths)||entry.data.paths.some(p=>!absolute(p)||!within(state.target.realpath,p)))throw Error('Scope paths must stay inside workspace');
+    state=invalidateAffectedEvidence({state,changedVersions:{scopeVersion:state.scopeVersion+1},affectedTaskIds:entry.data.affectedTaskIds});entry.scopeVersion=state.scopeVersion;state.scopes.push(entry);
+    state.unresolved.push({kind:'scope-changed',revision:state.revision+1,scopeVersion:state.scopeVersion,affectedTaskIds:state.tasks.filter(t=>t.invalidatedBy?.scopeVersion===state.scopeVersion).map(t=>t.id)});
+   }
+   if(['document','approval'].includes(entry.kind)&&state.tasks.length)state=invalidateAffectedEvidence({state,changedVersions:{[entry.kind+'Version']:entry.revision},affectedTaskIds:entry.data.affectedTaskIds});
+   if(decision.proposedTransition?.task){const task=decision.proposedTransition.task,index=state.tasks.findIndex(t=>t.id===task.id);if(index>=0){state=invalidateAffectedEvidence({state,changedVersions:{taskVersion:entry.revision},affectedTaskIds:[task.id]});state.tasks[index]=task;}else state.tasks.push(task);}
+   if(decision.proposedTransition?.finding){const finding=decision.proposedTransition.finding,index=state.findings.findIndex(f=>f.id===finding.id);if(index<0)state.findings.push(finding);else state.findings[index]=finding;}
+   state.records.push(entry);
+   if(decision.proposedTransition?.task)for(const marker of state.unresolved.filter(u=>u.kind==='scope-changed'&&!u.resolvedBy&&u.scopeVersion<=state.scopeVersion)){
+    const ids=marker.affectedTaskIds?.length?marker.affectedTaskIds:state.tasks.map(t=>t.id),proof=[];let ready=ids.length>0;
+    for(const id of ids){
+     const task=state.tasks.find(t=>t.id===id),approval=state.records.findLast(r=>r.kind==='approval'&&(!r.data.affectedTaskIds||r.data.affectedTaskIds.includes(id)));
+     if(!task||task.invalidated||task.scopeVersion!==state.scopeVersion||!approval||approval.revision<=marker.revision||approval.scopeVersion!==state.scopeVersion||approval.targetVersion!==state.targetVersion||task.approvalRef!==approval.messageRef||task.approvalVersion!==approval.data.approvalVersion||task.documentVersion!==approval.data.documentVersion){ready=false;break;}
+     const documents=approval.data.documents;
+     if(!Array.isArray(documents)||documents.length!==2||!['spec','plan'].every(kind=>documents.some(d=>d.kind===kind))){ready=false;break;}
+     try{const observed=await readGit({target:currentTarget,documents});if(!same(observed.target,currentTarget)||!observed.docsCommit||!same(observed.docsCommit.documents,documents)||documents.some(d=>d.commit!==observed.docsCommit.commit||d.approvalRef!==approval.messageRef||!observed.documents?.some(o=>o.path===d.path&&o.gitPath===d.gitPath&&o.observedHash===d.contentHash&&o.currentHash===d.contentHash))){ready=false;break;}}
+     catch{ready=false;break;}
+     const scope=state.scopes.find(s=>s.scopeVersion===state.scopeVersion);if(!scope||task.paths.some(p=>!scope.data.paths.some(base=>within(base,p)))){ready=false;break;}
+     proof.push({taskId:id,taskRef:task.messageRef,approvalRef:approval.messageRef,documents:structuredClone(documents)});
+    }
+    if(ready){marker.resolvedBy=input.requestId;marker.resolutionEvidence={taskIds:ids,contracts:proof,scopeVersion:state.scopeVersion};}
+   }
+  }
+  // A held request is durable audit, never an executable intent.
+  state.revision++;
+  const output=result(state,decision,{persisted:true});
+  state.requests.push({requestId:input.requestId,requestFingerprint,request:structuredClone({command,input}),decision:output});
+  state.audit.push({command,requestId:input.requestId,revision:state.revision,decision:output.decision,ruleIds:output.ruleIds,source:'operator-attested',actor:input.actor,...(input.intentId?{intentId:input.intentId,resolution:state.results.at(-1)?.status}:{}),...(input.operation?{operation:input.operation}:{})});
+  validateCooperativeState(state);await inspectPath(statePath);await saveDurableState({statePath,state,storage});return output;
+ }finally{if(lock){await lock.close();await fs.unlink(statePath+'.lock');}}
+}

package/lib/runtime/evaluate.mjs

@@ -1,3 +1,8 @@
+import {evaluateCooperativeExternal,reconcileCooperativeExternal,EXTERNAL_ACTIONS,unresolvedExternal} from './external.mjs';
+export {evaluateCooperativeExternal,reconcileCooperativeExternal};
+import {evaluateCooperativeAcceptance,prepareCooperativeCommit} from './acceptance.mjs';
+import {evaluateCooperativeVerification} from './verification.mjs';
+import {prepareCooperativeAssignment} from './assignment.mjs';
 /**
  * @typedef {object} GateDecision
  * @property {'allow'|'deny'|'hold'} decision
@@ -9,6 +14,7 @@
  * @property {object} coverage
  */
 import path from 'node:path';
+import {validateCooperativeState,validateCooperativeCommand} from './cooperative-schema.mjs';
 import {validateWorkflowState, validateRequest, validateEvidence} from './schema.mjs';
 import {ROLES, ROLE_OPERATIONS, GIT_OPERATIONS, EXTERNAL_OPERATIONS} from './operations.mjs';
 const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
@@ -21,7 +27,7 @@ export function evaluate(policy, state, request, evidence){
  const actor=state.identities.find(i=>i.actorRef===request.actorRef);
  if(!actor)return result('hold','runtime.identity','platform identity unresolved',['platform-identity']);
  const role=actor.role;
- const roleRule={orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',coder:'role.coder-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'}[role];
+ const roleRule={orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',implementer:'role.implementer-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'}[role];
  if(!ROLE_OPERATIONS[role]?.includes(request.operation))return result('deny',GIT_OPERATIONS.includes(request.operation)?'git.specialists-deny':roleRule,'operation forbidden for assigned role');
  const lease=state.leases.find(l=>l.actorRef===actor.actorRef);
  if(lease?.status==='retired')return result('deny','runtime.identity','retired identity');
@@ -44,7 +50,7 @@ export function evaluate(policy, state, request, evidence){
  const fact=kind=>evidence.facts?.find(f=>f.kind===kind&&f.workflowId===state.workflowId&&f.revision===state.revision&&same(f.target,state.target)&&f.policyHash===state.versions.policyHash&&evidence.provenance.some(p=>p.id===f.sourceRef));
  const task=state.tasks.find(t=>t.id===request.taskId);
  if(!task)return result('hold','runtime.assignment','task unavailable',['task']);
- if(role==='coder'&&['accepted','committed'].includes(task.status))return result('deny','runtime.identity','task execution ended');
+ if(role==='implementer'&&['accepted','committed'].includes(task.status))return result('deny','runtime.identity','task execution ended');
  if(request.operation==='temporary-write'){
   const temporary=assignment.temporary;
   if(!temporary||temporary.cleanupOwner!==request.actorRef||!Number.isFinite(Date.parse(temporary.expiresAt))||!Number.isFinite(Date.parse(evidence.observedAt))||Date.parse(temporary.expiresAt)<=Date.parse(evidence.observedAt)||!request.paths.every(p=>temporary.paths?.some(base=>within(base,p))))return result('hold','role.qa-verification','temporary scope lifetime and cleanup ownership required',['temporary-assignment']);
@@ -58,7 +64,7 @@ export function evaluate(policy, state, request, evidence){
   if(!ROLES.includes(d.role)||d.taskId!==request.taskId)return result('deny','runtime.identity','invalid assignment');
   const previous=state.identities.find(i=>i.actorRef===d.actorRef);
   if(previous&&(previous.taskId!==d.taskId||state.leases.some(l=>l.actorRef===d.actorRef&&l.status==='retired')))return result('deny','runtime.identity','identity cannot cross tasks or revive');
-  if(d.role==='coder'){
+  if(d.role==='implementer'){
    if(state.mode==='plan'){
     // T3 supplies verified Git object evidence. Local assertions never satisfy this gate.
     if(!state.documents.some(d=>d.kind==='spec')||!state.documents.some(d=>d.kind==='plan'))return result('hold','runtime.docs-commit','approved complete spec and plan required',['approved-documents','docs-only-commit']);
@@ -72,7 +78,7 @@ export function evaluate(policy, state, request, evidence){
   const expected={requestId:request.requestId,platform:request.platform,...d};
   const correlationProof=evidence.provenance.find(p=>p.id===correlation?.sourceRef&&p.source==='platform-event'&&p.verification.sourceRef===p.eventRef&&p.platform===request.platform&&p.actorRef===request.actorRef&&p.correlationRef===d.correlationRef&&p.requestId===request.requestId);
   if(d.actorRef!==undefined||!d.correlationRef||!correlationProof||!same(correlation?.data,expected))return result('hold','runtime.identity','trusted platform request correlation required',['assignment-correlation']);
-  if(!Array.isArray(d.paths)||!d.paths.length||!same([...d.paths].sort(),[...request.paths].sort())||!Array.isArray(d.operations)||!d.operations.length||d.approvalRef!==approval.id||!approval.scope.roles?.includes(d.role)||d.paths.some(p=>!task.paths.some(base=>within(base,p)))||d.operations.some(op=>!ROLE_OPERATIONS[d.role].includes(op)||!approval.scope.operations.includes(op)))return result('hold','runtime.assignment','delegated role paths operations and approval must match',['delegated-scope']);
+  if(!Array.isArray(d.paths)||!d.paths.length||!same([...d.paths].sort(),[...request.paths].sort())||!Array.isArray(d.operations)||!d.operations.length||d.approvalRef!==approval.id||!approval.scope.roles?.some(role=>role===d.role)||d.paths.some(p=>!task.paths.some(base=>within(base,p)))||d.operations.some(op=>!ROLE_OPERATIONS[d.role].includes(op)||!approval.scope.operations.includes(op)))return result('hold','runtime.assignment','delegated role paths operations and approval must match',['delegated-scope']);
   if(d.checks&&(!Array.isArray(approval.scope.checks)||d.checks.some(c=>!approval.scope.checks.some(approved=>same(approved,c)))))return result('hold','runtime.assignment','delegated checks not approved',['delegated-checks']);
   if(d.temporary&&!same(d.temporary,approval.scope.temporary))return result('hold','runtime.assignment','delegated temporary scope not approved',['delegated-temporary-scope']);
   if(state.assignments.some(a=>a.assignmentId===request.requestId||a.correlationRef===d.correlationRef))return result('hold','runtime.identity','assignment correlation already registered',['new-assignment-correlation']);
@@ -101,3 +107,33 @@ export function evaluate(policy, state, request, evidence){
  if(request.operation==='transition')return result('hold','runtime.transition','result confirmation required',['observed-result']);
  return result('allow',roleRule,'assigned operation with verified provenance');
 }
+
+/** Cooperative statements never enter provider validation or identity resolution. */
+export function evaluateCooperative({policy,state,request,evidence}={}){
+ const base={expectedRevision:state?.revision??0,coverage:{enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false}};
+ const hold=(id,reason)=>({...base,decision:'hold',ruleIds:[id],reason,requiredEvidence:[],nextActions:[],proposedTransition:null});
+ try{validateCooperativeState(state);validateCooperativeCommand(request);}catch(error){return hold('cooperative.schema',error.message);}
+ if(policy!==undefined&&policy.workflowKind!=='cooperative')return hold('cooperative.contract','Explicit cooperative policy required');
+ if(state.mode!=='plan'||request.command==='result')return hold('cooperative.unsupported','Operation is not supported in this CLI phase');
+ if(!evidence||!same(evidence.target,state.target))return hold('cooperative.target','Observed target changed');
+ if(!same(evidence.versions,state.versions))return hold('cooperative.versions','Policy or runtime changed');
+ if(request.input&&request.input.expectedRevision!==state.revision)return hold('cooperative.revision','Stale revision');
+ if(request.command==='record'&&request.input.evidence.kind==='external-approval'&&request.input.actor.role!=='orchestrator')return hold('cooperative.external-approval','Orchestrator records explicit external approval');
+ if(request.command==='prepare'){
+  if(unresolvedExternal(state))return hold('cooperative.external-unresolved','Investigate unresolved external effects before follow-up');
+  if(EXTERNAL_ACTIONS.includes(request.input.operation))return evaluateCooperativeExternal({state,request:request.input,approvalEvidence:state.records.findLast(r=>r.kind==='external-approval'&&r.messageRef===request.input.arguments?.approvalRef)});
+  if(request.input.operation==='accept')return evaluateCooperativeAcceptance({state,request:request.input,evidence});
+  if(request.input.operation==='commit')return prepareCooperativeCommit({state,request:request.input,evidence,gitEvidence:evidence.git});
+  return request.input.operation==='assign-agent'?prepareCooperativeAssignment({policy,state,request:request.input,observations:{target:evidence.target,git:evidence.git}}):evaluateCooperativeVerification({state,request:request.input,evidence});
+ }
+ if(request.command==='record'&&(['check','review','finding'].includes(request.input.evidence.kind)||request.input.evidence.kind==='acceptance-evidence'&&request.input.evidence.data.kind==='task'))return evaluateCooperativeVerification({state,request:{...request.input,operation:'verification-record'},evidence});
+ if(request.command==='status'&&(state.tasks.some(t=>t.invalidated||t.status==='committed'&&!state.commits.some(c=>c.taskId===t.id&&c.postCommitFingerprint===evidence.changes?.tasks?.[t.id]))||state.findings.some(f=>f.status!=='closed')||state.checks.some((c,index)=>!(c.scope==='task'&&state.tasks.some(t=>t.id===c.taskId&&t.status==='committed'))&&!state.checks.slice(index+1).some(next=>next.scope===c.scope&&next.taskId===c.taskId&&same(next.descriptor,c.descriptor))&&(c.stale||c.status!=='passed'||c.changeFingerprint!==(c.scope==='final'?evidence.changes?.final:evidence.changes?.tasks?.[c.taskId])))))return hold('cooperative.verification-stale','Verification or findings require current evidence');
+ return {...base,decision:'allow',ruleIds:['cooperative.recorded'],requiredEvidence:[],nextActions:[],proposedTransition:null};
+}
+
+/** Result statements preserve uncertainty. They do not authenticate native events. */
+export function reconcileCooperativeResult({state,intent,result,observations}={}){
+ const base={expectedRevision:state?.revision??0,coverage:{enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false},requiredEvidence:[],nextActions:[],proposedTransition:null};
+ try{validateCooperativeState(state);}catch(error){return {...base,decision:'hold',ruleIds:['cooperative.schema'],reason:error.message};}
+ return {...base,decision:'hold',ruleIds:[!intent?'cooperative.intent':result?.status==='unknown'?'cooperative.unknown':'cooperative.reconciliation'],requiredEvidence:[],nextActions:[],proposedTransition:null,reason:!intent?'No matching durable intent':'Recorded operator statement requires reconciliation; no execution authorized'};
+}

package/lib/runtime/external.mjs

@@ -0,0 +1,51 @@
+import {fingerprintRequest} from './store.mjs';
+import {absolute,within} from './scope.mjs';
+export const EXTERNAL_ACTIONS=Object.freeze(['push','merge','deploy','publish']);
+const keys={push:['repository','destination','refspec','sourceOid','expectedRemoteOid'],merge:['repository','changeRef','targetRef','expectedTargetOid'],deploy:['service','project','environment','artifactId','destination'],publish:['service','namespace','name','version','artifactHash','destination']};
+const text=v=>typeof v==='string'&&v.length>0;
+const same=(a,b)=>a===undefined||b===undefined?a===b:fingerprintRequest(a)===fingerprintRequest(b);
+const fields=(v,allowed)=>v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).length===allowed.length&&allowed.every(k=>Object.hasOwn(v,k));
+/** Reject credentials before audit persistence; errors never contain input values. */
+export function assertSecretFree(value){
+ if(typeof value==='string'){
+  if(/(?:[a-z][a-z0-9+.-]*:\/\/|^)[^\s/]+:[^\s/]+@|[?&#](?:access[_-]?token|token|key|password|secret|signature|credential|auth)=|\b(?:Bearer|Basic)\s+\S+/i.test(value))throw Error('Secret-free identifiers required');
+ }else if(value&&typeof value==='object')for(const [key,item] of Object.entries(value)){
+  if(/^(?:password|passwd|token|accessToken|access_token|secret|credentials?|authorization|apiKey|api_key|privateKey)$/i.test(key))throw Error('Secret-free identifiers required');assertSecretFree(item);
+ }
+}
+function descriptorValid(operation,d){
+ if(!keys[operation]||!fields(d,keys[operation])||!Object.values(d).every(v=>text(v)&&!/[\r\n\x00]/.test(v)))return false;
+ if(d.destination&&/[?#]/.test(d.destination))return false;
+ const oid=v=>/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(v);
+ if(operation==='push'&&(!oid(d.sourceOid)||!oid(d.expectedRemoteOid)))return false;
+ if(operation==='merge'&&!oid(d.expectedTargetOid))return false;
+ return operation!=='publish'||/^sha256:[a-f0-9]{64}$/.test(d.artifactHash);
+}
+const coverage={enforcement:'cooperative',provenance:'operator-attested',nativeVerified:false,remoteVerified:false};
+const decision=(state,reason,transition=null,allow=false)=>({expectedRevision:state?.revision??0,decision:allow?'allow':'hold',ruleIds:['cooperative.external'],reason,coverage:{...coverage},requiredEvidence:[],nextActions:[],proposedTransition:transition});
+export const unresolvedExternal=state=>state.intents.some(i=>EXTERNAL_ACTIONS.includes(i.operation)&&['prepared','unknown','mismatch'].includes(i.status));
+export function evaluateCooperativeExternal({state,request,approvalEvidence}={}){
+ const a=request?.arguments;
+ try{assertSecretFree(request);assertSecretFree(approvalEvidence);}catch{return decision(state,'Secret-free identifiers required');}
+ if(state?.mode!=='plan'||request?.expectedRevision!==state.revision||request.actor?.role!=='orchestrator'||!fields(a,['approvalRef','scope','descriptor'])||!descriptorValid(request.operation,a.descriptor)||!Array.isArray(a.scope)||!a.scope.length||new Set(a.scope).size!==a.scope.length||a.scope.some(p=>!absolute(p)||!within(state.target.realpath,p)))return decision(state,'Exact external action, scope and secret-free target required');
+ const approval=state.records.findLast(r=>r.kind==='external-approval'&&r.messageRef===a.approvalRef);
+ if(!approval||approval.source!=='operator-attested'||approval.scopeVersion!==state.scopeVersion||approval.targetVersion!==state.targetVersion||!same(approval,approvalEvidence)||!same(approval.data,{operation:request.operation,scope:a.scope,descriptor:a.descriptor}))return decision(state,'Exact explicit external approval required; local approval is insufficient');
+ if(unresolvedExternal(state)||state.unresolved.some(u=>!u.resolvedBy)||state.intents.some(i=>i.requestId===request.requestId||EXTERNAL_ACTIONS.includes(i.operation)&&i.approvalRef===a.approvalRef))return decision(state,'Unresolved effects or consumed approval require investigation; never retry');
+ return decision(state,'External intent only; operator execution is separate',{intent:{requestId:request.requestId,operation:request.operation,status:'prepared',scope:structuredClone(a.scope),descriptor:structuredClone(a.descriptor),approvalRef:a.approvalRef,approvalFingerprint:fingerprintRequest(approval),scopeVersion:state.scopeVersion,targetVersion:state.targetVersion,target:structuredClone(state.target),versions:structuredClone(state.versions),fingerprint:fingerprintRequest(request),source:'operator-attested'}},true);
+}
+export function reconcileCooperativeExternal({state,intent,result,observations}={}){
+ if(!intent||!EXTERNAL_ACTIONS.includes(intent.operation)||!['prepared','unknown','mismatch'].includes(intent.status))return decision(state,'Matching unresolved external intent required; replay cannot authorize another effect');
+ try{assertSecretFree(result);}catch{return decision(state,'Secret-free result required');}
+ const transition={result:{...structuredClone(result),status:'mismatch',messageRef:result?.messageRef??'invalid-result',data:{...structuredClone(result?.data??{}),remoteVerified:false},source:'operator-attested'}};
+ const reject=reason=>decision(state,reason,transition);
+ if(!result||!text(result.messageRef)||!['succeeded','failed','unknown','mismatch','cancelled'].includes(result.status))return reject('Exact external result statement required');
+ if(!fields(result.data,['operation','scope','descriptor'])||result.data.operation!==intent.operation||!same(result.data.scope,intent.scope)||!same(result.data.descriptor,intent.descriptor))return reject('External result action, scope or target mismatch');
+ transition.result={...structuredClone(result),data:{...structuredClone(result.data),remoteVerified:false},source:'operator-attested'};
+ const approval=state.records.findLast(r=>r.kind==='external-approval'&&r.messageRef===intent.approvalRef);
+ if(!same(observations?.target,intent.target)||!approval||fingerprintRequest(approval)!==intent.approvalFingerprint||state.mode!=='plan'||!same(intent.target,state.target)||!same(intent.versions,state.versions)||intent.scopeVersion!==state.scopeVersion||intent.targetVersion!==state.targetVersion){transition.result.status='mismatch';return reject('Stale external approval, target or versions');}
+ if(result.status==='succeeded')return decision(state,'Operator result recorded; no independent remote verification',transition,true);
+ if(result.status==='failed')return decision(state,'Operator confirms failure; approval remains consumed and no retry authorized',transition,true);
+ if(result.status==='cancelled'&&text(result.notExecutedEvidence?.messageRef))return decision(state,'Operator attests no execution; approval remains consumed',transition,true);
+ return reject('External effect unresolved or unsuccessful; investigate without retry');
+}
+export function cooperativeSupport(){return {phases:[{phase:1,status:'supported',areas:['durable-state','documents','assignment']},{phase:2,status:'supported',areas:['scope','verification','acceptance-commit']},{phase:3,status:'supported',areas:['external-approval','external-result','audit-recovery']}],modes:{plan:'supported','no-plan':'unsupported',omission:'unsupported'},limits:['operator-attested identity and approval','direct calls outside CLI are not blocked','no network, native or provider execution','audit is local mutable evidence','unknown effects require investigation, not retry'],remoteVerified:false};}

package/lib/runtime/gate.mjs

@@ -1,3 +1,5 @@
+import {validateGitPreflight,validateGitCommitResult} from './git-evidence.mjs';
+export {validateGitPreflight,validateGitCommitResult} from './git-evidence.mjs';
 import path from 'node:path';
 
 const reconciliations=new WeakMap();
@@ -44,10 +46,10 @@ export async function runGate({phase,state,request,gitEvidence,expectedCommit,re
   }
   if(phase==='preflight'){
    const g=gitEvidence;
-   if(!g||!same(g.target,state.target)||g.indexTree!==d.indexTree||g.stagedFingerprint!==d.fingerprint||!samePaths(g.stagedPaths,d.paths)||!validPaths(g.workingPaths)||!validPaths(g.untrackedPaths))return hold('Actual Git target index diff and exact paths required');
-   const dirty=[...g.workingPaths,...g.untrackedPaths];
+   const dirty=[...g?.workingPaths??[],...g?.untrackedPaths??[]];
    const scope=d.kind==='documents'?state.documents.map(x=>x.path):task.paths;
-   if(dirty.some(file=>scope.some(base=>within(base,path.join(state.target.realpath,...file.split('/'))))))return hold('Unstaged or untracked task changes invalidate acceptance');
+   const invalid=validateGitPreflight({target:state.target,descriptor:d,scope,gitEvidence:g});
+   if(invalid)return hold(invalid);
    if(d.kind==='documents'){
     if(!Array.isArray(g.documents)||!samePaths(g.documents.map(x=>x.gitPath),d.paths)||state.documents.some(document=>!g.documents.some(observed=>observed.gitPath===document.gitPath&&observed.path===document.path&&observed.contentHash===document.contentHash&&observed.observedHash===document.contentHash)))return hold('Observed document bytes differ from approved hashes','runtime.docs-commit');
    }
@@ -56,10 +58,8 @@ export async function runGate({phase,state,request,gitEvidence,expectedCommit,re
   if(phase!=='reconcile')return hold('Unknown Git gate phase');
   const expected=expectedCommit;
   if(!expected||expected.requestId!==request.requestId||expected.taskId!==task.id||expected.parent!==d.parent||expected.tree!==d.indexTree||expected.fingerprint!==d.fingerprint||!samePaths(expected.paths,d.paths)||expected.kind!==undefined&&expected.kind!==d.kind||expected.target!==undefined&&!same(expected.target,state.target))return hold('Preflight correlation unavailable');
-  if(!result||!oid(result.commit)||result.commit===expected.parent||result.commit.length!==expected.parent.length||result.parent!==expected.parent||result.tree!==expected.tree||!samePaths(result.paths,expected.paths)||result.head!==result.commit||!same(result.target,{...state.target,head:result.commit})||!validPaths(result.remainingPaths))return hold('Commit result unavailable or differs from expected parent tree paths and HEAD');
-  const scopedPaths=d.kind==='documents'?state.documents.map(x=>x.path):task.paths;
-  if(result.remainingPaths.some(file=>scopedPaths.some(base=>within(base,path.join(state.target.realpath,...file.split('/'))))))return hold('Committed task still has remaining changes');
-  if(expected.remainingPaths!==undefined&&!samePaths(result.remainingPaths,expected.remainingPaths))return hold('Remaining changes differ from preflight observation');
+  const invalid=validateGitCommitResult({target:state.target,expected,result,scope:d.kind==='documents'?state.documents.map(x=>x.path):task.paths});
+  if(invalid)return hold(invalid);
   const next=structuredClone(state);next.target.head=result.commit;
   next.commits=[...state.commits??[],{requestId:request.requestId,taskId:task.id,kind:d.kind,purpose:d.kind,expectedParent:expected.parent,expectedTree:expected.tree,commit:result.commit,parent:result.parent,tree:result.tree,paths:[...result.paths],fingerprint:d.fingerprint,actorRef:request.actorRef}];
   if(d.kind==='task')next.tasks.find(t=>t.id===task.id).status='committed';

package/lib/runtime/git-evidence.mjs

@@ -1,3 +1,5 @@
+import fs from 'node:fs/promises';
+import {inspectPath} from './scope.mjs';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import {spawnSync} from 'node:child_process';
@@ -112,3 +114,47 @@ function pathsForTree(bytes){
  const output=text(bytes);if(!output||!output.endsWith('\0'))throw Error('Invalid document tree');
  return output.slice(0,-1).split('\0').map(entry=>{const match=/^(\d+) (blob|tree|commit) ([a-f0-9]+)\t([\s\S]+)$/.exec(entry);if(!match||!oid(match[3])||!gitPath(match[4]))throw Error('Invalid document tree entry');return {mode:match[1],type:match[2],path:match[4]};});
 }
+
+/** Assignment observation additionally compares regular current files to Git objects.
+ * No Git facts or transport override are accepted from workflow command JSON. */
+export async function readAssignmentGitEvidence({target,documents}){
+ const evidence=await readGitEvidence({target,documents});
+ for(const document of evidence.documents){
+  await inspectPath(document.path);
+  document.currentHash=hash(await fs.readFile(document.path));
+  if(document.currentHash!==document.contentHash)throw Error('Current approved document hash mismatch');
+ }
+ return evidence;
+}
+
+/** Cooperative observations come only from local read-only Git queries. */
+export async function readCooperativeCommitGitEvidence({target,commit,gitRunner=defaultRunner}){
+ if(commit!==undefined&&!oid(commit))throw Error('Invalid commit object ID');
+ const evidence=await readGitEvidence({target,gitRunner});
+ if(commit===undefined)return evidence;
+ const run=async args=>{const r=await gitRunner({args,cwd:target.realpath});if(r?.status!==0||r.error||!(Buffer.isBuffer(r.stdout)||typeof r.stdout==='string'))throw Error('Commit evidence query failed');return Buffer.from(r.stdout);};
+ const metadata=text(await run(['show','--no-patch','--format=%H%n%P%n%T',commit])).trimEnd().split('\n');
+ if(metadata.length!==3||metadata[0]!==commit||!metadata.every(oid))throw Error('Expected exact single-parent commit');
+ const committedPaths=paths(await run(['diff-tree','--no-commit-id','--name-only','-r','-z',commit,'--']));
+ // Reobserve both HEAD and index after metadata so a concurrent mutation holds.
+ const after=await readGitEvidence({target,gitRunner});
+ if(!equal(evidence,after))throw Error('Git changed during commit observation');
+ return {...evidence,commit:{commit,parent:metadata[1],tree:metadata[2],paths:committedPaths,head:target.head}};
+}
+
+const validGitPaths=values=>Array.isArray(values)&&values.every(gitPath)&&unique(values);
+const within=(base,file)=>{const relative=path.relative(base,file);return relative===''||!path.isAbsolute(relative)&&relative!=='..'&&!relative.startsWith('..'+path.sep);};
+/** Provenance-neutral Git checks shared by trusted and cooperative callers.
+ * The caller must establish role, approval and acceptance separately. */
+export function validateGitPreflight({target,descriptor:d,scope,gitEvidence:g}){
+ if(!g||!equal(g.target,target)||!oid(d?.parent)||d.parent!==target.head||!oid(d.indexTree)||!/^sha256:[a-f0-9]{64}$/.test(d.fingerprint)||!validGitPaths(d.paths)||!d.paths.length||g.indexTree!==d.indexTree||g.stagedFingerprint!==d.fingerprint||!samePaths(g.stagedPaths,d.paths)||!validGitPaths(g.workingPaths)||!validGitPaths(g.untrackedPaths))return 'Actual Git target index diff and exact paths required';
+ if(d.paths.some(file=>!scope.some(base=>within(base,path.join(target.realpath,...file.split('/'))))))return 'Commit contains another task or unrelated changes';
+ if([...g.workingPaths,...g.untrackedPaths].some(file=>scope.some(base=>within(base,path.join(target.realpath,...file.split('/'))))))return 'Unstaged or untracked task changes invalidate acceptance';
+ return null;
+}
+export function validateGitCommitResult({target,expected,result,scope}){
+ if(!result||!oid(result.commit)||result.commit===expected.parent||result.commit.length!==expected.parent.length||result.parent!==expected.parent||result.tree!==expected.tree||!samePaths(result.paths,expected.paths)||result.head!==result.commit||!equal(result.target,{...target,head:result.commit})||!validGitPaths(result.remainingPaths))return 'Commit result unavailable or differs from expected parent tree paths and HEAD';
+ if(result.remainingPaths.some(file=>scope.some(base=>within(base,path.join(target.realpath,...file.split('/'))))))return 'Committed task still has remaining changes';
+ if(expected.remainingPaths!==undefined&&!samePaths(result.remainingPaths,expected.remainingPaths))return 'Remaining changes differ from preflight observation';
+ return null;
+}

package/lib/runtime/operations.mjs

@@ -1,6 +1,6 @@
 /** Canonical semantic operations, independent of platform tool aliases. */
-export const ROLES = Object.freeze(['orchestrator','scouter','planner','coder','qa','reviewer']);
+export const ROLES = Object.freeze(['orchestrator','scouter','planner','implementer','qa','reviewer']);
 export const GIT_OPERATIONS = Object.freeze(['stage','commit','push','merge','rebase','reset','branch-create','branch-switch','worktree-create','worktree-remove']);
 export const EXTERNAL_OPERATIONS = Object.freeze(['push','merge','deploy','publish','external-message']);
 export const OPERATIONS = Object.freeze(['read','draft','write','check','qa','review','temporary-write','operational-query','install','prepare-target','request-approval','assign-agent','accept','transition','scope-expansion','indirect-bypass',...new Set([...GIT_OPERATIONS,...EXTERNAL_OPERATIONS])]);
-export const ROLE_OPERATIONS = Object.freeze({orchestrator:['read','write','check','prepare-target','request-approval','assign-agent','accept','transition','install',...GIT_OPERATIONS,...EXTERNAL_OPERATIONS],scouter:['read'],planner:['read','draft'],coder:['read','write','check'],qa:['read','check','temporary-write'],reviewer:['read','review']});
+export const ROLE_OPERATIONS = Object.freeze({orchestrator:['read','write','check','prepare-target','request-approval','assign-agent','accept','transition','install',...GIT_OPERATIONS,...EXTERNAL_OPERATIONS],scouter:['read'],planner:['read','draft'],implementer:['read','write','check'],qa:['read','check','temporary-write'],reviewer:['read','review']});

package/lib/runtime/schema.mjs

@@ -36,6 +36,7 @@ const unique = (items,key) => items.every(x=>object(x)&&text(x[key])) && new Set
 function approval(a){return object(a)&&text(a.id)&&['user-message','human-confirmation'].includes(a.source)&&text(a.messageRef)&&hash(a.contentHash)&&object(a.scope)&&text(a.scope.taskId)&&absolute(a.scope.target)&&strings(a.scope.operations)&&a.scope.operations.every(op=>OPERATIONS.includes(op))&&strings(a.scope.paths)&&a.scope.paths.every(absolute);}
 /** Validate stored workflow data. Observed provenance must still be checked by evaluate. */
 export function validateWorkflowState(s){
+ if(object(s)&&s.workflowKind!==undefined)fail('provider state cannot use cooperative contract');
  if(!object(s)||s.schemaVersion!==1||!text(s.workflowId)||!Number.isSafeInteger(s.revision)||s.revision<0)fail('version or identity');
  if(!object(s.versions)||['policy','runtime','adapter','policyHash','runtimeHash','adapterHash'].some(k=>!text(s.versions[k])))fail('versions');
  if(['policyHash','runtimeHash','adapterHash'].some(k=>!hash(s.versions[k])))fail('hash algorithm');

package/lib/runtime/scope.mjs

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+export const absolute=value=>typeof value==='string'&&path.isAbsolute(value)&&path.normalize(value)===value;
+export const within=(base,file)=>absolute(file)&&!path.relative(base,file).split(path.sep).includes('..')&&!path.isAbsolute(path.relative(base,file));
+/** Inspect every component, including ancestors outside the ARC namespace. */
+export async function inspectPath(filename,{missing=false,directory=false}={}){
+ if(!absolute(filename))throw Error('Unsafe absolute path');
+ let cursor=path.parse(filename).root;
+ const parts=filename.slice(cursor.length).split(path.sep).filter(Boolean);
+ for(let i=0;i<parts.length;i++){
+  cursor=path.join(cursor,parts[i]);let stat;
+  try{stat=await fs.lstat(cursor);}catch(error){if(missing&&error.code==='ENOENT')return;throw error;}
+  if(stat.isSymbolicLink())throw Error('Unsafe symlink path');
+  if(i<parts.length-1||directory){if(!stat.isDirectory())throw Error('Unsafe directory type');}
+  else if(!stat.isFile())throw Error('State must be a regular file');
+ }
+}
+export function validateWorkflowId(id){if(typeof id!=='string'||!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(id))throw Error('Invalid workflow ID');return id;}
+/** Shell-free, read-only observation; inherited Git target/config overrides are removed. */
+export async function observeCooperativeTarget(cwd){
+ if(!absolute(cwd))throw Error('Absolute workspace required');await inspectPath(cwd,{directory:true});
+ const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>!key.toUpperCase().startsWith('GIT_')));
+ Object.assign(env,{GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:process.platform==='win32'?'NUL':'/dev/null',GIT_OPTIONAL_LOCKS:'0',GIT_NO_REPLACE_OBJECTS:'1',GIT_NO_LAZY_FETCH:'1',GIT_TERMINAL_PROMPT:'0'});
+ const query=(args,detached=false)=>{const r=spawnSync('git',['--no-pager','-c','core.fsmonitor=false',...args],{cwd,env,encoding:'utf8',timeout:10000,maxBuffer:1024*1024});if(detached&&r.status===1&&!r.error)return null;if(r.status!==0||r.error||!r.stdout.endsWith('\n')||r.stdout.slice(0,-1).includes('\n'))throw Error('Git target observation failed');return r.stdout.slice(0,-1);};
+ const target={realpath:query(['rev-parse','--show-toplevel']),gitCommonDir:query(['rev-parse','--path-format=absolute','--git-common-dir']),gitDir:query(['rev-parse','--absolute-git-dir']),head:query(['rev-parse','HEAD']),branch:query(['symbolic-ref','--quiet','--short','HEAD'],true)};
+ await validateObservedTarget(cwd,target);return target;
+}
+export async function validateObservedTarget(cwd,target){
+ if(!absolute(cwd)||!target||target.realpath!==cwd||!absolute(target.gitCommonDir)||!absolute(target.gitDir)||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(target.head)||!(target.branch===null||typeof target.branch==='string'&&target.branch))throw Error('Invalid observed target');
+ await inspectPath(cwd,{directory:true});await inspectPath(target.gitCommonDir,{directory:true});
+ return target;
+}
+export async function workflowStatePath(target,workflowId){
+ validateWorkflowId(workflowId);const statePath=path.join(target.gitCommonDir,'arc','workflows',workflowId,'state.json');await inspectPath(statePath,{missing:true});return statePath;
+}

package/lib/runtime/store.mjs

@@ -1,3 +1,4 @@
+import {verifiedCooperativeReconciliation} from './acceptance.mjs';
 import {verifiedReconciliation} from './gate.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -51,13 +52,33 @@ export async function transactWorkflow({statePath,expectedRevision,requestId,req
   next.revision=state.revision+1;next.requests=prior?state.requests.map(r=>r.requestId===requestId?{requestId,requestFingerprint,decision}:r):[...state.requests,{requestId,requestFingerprint,decision}];
   next.audit=[...state.audit,{requestId,revision:next.revision,decision:decision.decision,ruleIds:decision.ruleIds??[],result:'pending'}];
   validateWorkflowState(next);
-  temporary=path.join(parent,`.${path.basename(statePath)}.${crypto.randomUUID()}.tmp`);
-  const handle=await fs.open(temporary,'wx',0o600);try{await handle.writeFile(JSON.stringify(next,null,2)+'\n');await handle.sync();}finally{await handle.close();}
-  await fs.rename(temporary,statePath);temporary=undefined;
-  const directory=await fs.open(parent,'r');try{await directory.sync();}finally{await directory.close();}
+  await saveDurableState({statePath,state:next});
   return {state:next,decision,replayed:false};
  }finally{
   if(temporary)await fs.unlink(temporary).catch(()=>{});
   if(lock){await lock.close();await fs.unlink(lockPath);}
  }
 }
+
+/** Shared durability primitive. A post-rename sync error is reported as failure;
+ * the caller must re-read rather than assume rollback or repeat an effect. */
+export async function saveDurableState({statePath,state,create=false,storage={}}){
+ const parent=path.dirname(statePath),temporary=path.join(parent,`.${path.basename(statePath)}.${crypto.randomUUID()}.tmp`);
+ let exists=false;
+ try{
+  const handle=await fs.open(temporary,'wx',0o600);exists=true;
+  try{await handle.writeFile(JSON.stringify(state,null,2)+'\n');await handle.sync();}finally{await handle.close();}
+  if(create){await (storage.link??fs.link)(temporary,statePath);await fs.unlink(temporary);}else await (storage.rename??fs.rename)(temporary,statePath);
+  exists=false;
+  const directory=await fs.open(parent,'r');try{await directory.sync();}finally{await directory.close();}
+ }finally{if(exists)await fs.unlink(temporary).catch(()=>{});}
+}
+
+/** Only a locally verified cooperative commit may advance the stored target. */
+export function applyCooperativeCommitTransition({state,decision}){
+ if(decision?.decision!=='allow'||!verifiedCooperativeReconciliation(decision,state)||!decision.proposedTransition?.commit)throw Error('Verified cooperative reconciliation required');
+ const next=structuredClone(state),transition=decision.proposedTransition;
+ next.targetHistory.push({target:structuredClone(state.target),revision:state.revision+1,source:'local-observation',kind:'verified-commit-parent'});
+ next.target=structuredClone(transition.target);next.commits.push(structuredClone(transition.commit));next.tasks.find(t=>t.id===transition.commit.taskId).status='committed';
+ return next;
+}