@milpa/comal 0.1.6 → 0.2.0

package/src/git-page-settlement.mjs

@@ -0,0 +1,21 @@
+// Acknowledged close/unload may precede native inventory disappearance. Poll
+// reads only on the original connection; never repeats the cleanup effects.
+import {setTimeout as sleep} from 'node:timers/promises';
+import {digest} from './operations.mjs';
+const fail=message=>Object.assign(new Error(message),{code:'GIT_PAGE_CLEANUP_UNCERTAIN'});
+const endpoint=status=>({connection_id:status.connection_id,browser_endpoint_id:status.browser_endpoint_id,ssh_host:status.ssh_host,remote_root:status.remote_root});
+export const PAGE_CLEANUP_SETTLEMENT=Object.freeze({timeout_ms:5000,poll_ms:100,max_reads:40});
+export async function settlePageAbsence({call,targetId,project,originalStatus,originalTarget,signal}){
+ const expected=endpoint(originalStatus),originalExtensions=(originalStatus.extensions||[]).filter(e=>e.project===project),extensionId=e=>e.extension_id||e.id;if(!expected.connection_id)throw fail('Original cleanup connection identity is unavailable.');
+ const deadline=AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(PAGE_CLEANUP_SETTLEMENT.timeout_ms)]);
+ try{for(let reads=0;reads<PAGE_CLEANUP_SETTLEMENT.max_reads;reads++){
+  deadline.throwIfAborted();const targets=await call('Targets',{},deadline),status=await call('Status',{},deadline);
+  if(targets.truncated||status.extensions_truncated||digest(endpoint(status))!==digest(expected))throw fail('Cleanup inventory/endpoint changed; no effect is replayed.');
+  const target=targets.targets.find(t=>t.target_id===targetId),extensions=status.extensions.filter(e=>e.project===project);
+  if(target&&originalTarget&&(target.type!==originalTarget.type||target.url!==originalTarget.url)||extensions.length>1||extensions.length===1&&(originalExtensions.length!==1||extensionId(extensions[0])!==extensionId(originalExtensions[0])))throw fail('An owned cleanup identity was replaced during settlement; no effect is replayed.');
+  if(!targets.targets.some(t=>t.target_id===targetId)&&!status.extensions.some(e=>e.project===project))return{targets,status,reads:reads+1};
+  await sleep(PAGE_CLEANUP_SETTLEMENT.poll_ms,undefined,{signal:deadline});
+ }}catch(error){if(signal?.aborted)throw signal.reason;if(deadline.aborted)throw fail('Owned native absence did not settle within its read-only deadline.');throw error;}
+ throw fail('Owned native absence did not settle within its read-only read bound.');
+}
+export const pageSettlementImplementation=()=>digest({contract:PAGE_CLEANUP_SETTLEMENT,functions:[settlePageAbsence,endpoint,fail].map(fn=>Function.prototype.toString.call(fn))});

package/src/git-page-verification.mjs

@@ -0,0 +1,134 @@
+// Trusted host registration and workspace-bound page adapter. Recipes are host
+// code, not a sandbox, model-loadable modules, or retrospective attestations.
+import {randomUUID,createHash} from 'node:crypto';
+import {digest,immutable} from './operations.mjs';
+import {normalizeTask} from './workflows/chrome-task.mjs';
+import {prepareChromePageTask} from './workflows/chrome-page-task.mjs';
+import {PAGE_CASE_IMPLEMENTATION_DIGEST} from './workflows/chrome-page-cases.mjs';
+import {PAGE_LAW_IMPLEMENTATION_DIGEST} from './workflows/chrome-page-law.mjs';
+import {assertPageVerifier} from './workflows/chrome-page-verifier.mjs';
+import {hostCodeIdentity} from './git-page-identity.mjs';
+import {settlePageAbsence,pageSettlementImplementation} from './git-page-settlement.mjs';
+import {snapshotProject} from './plugins/chrome-lab/project.mjs';
+import {isPageVerification,pageReservation,pageCaseRevision,pageProofImplementation,pageRecipeReference} from './git-page-proof.mjs';
+
+const fail=(message,code='GIT_PAGE_RECIPE')=>Object.assign(new Error(message),{code});
+const descriptors=new WeakSet();
+export class GitPageRegistry {
+ #recipes=new Map(); #runtimes=new Map(); #busy=new Set(); #sealed=false;
+ acquire(resourceId){if(this.#busy.has(resourceId))throw fail('The host page resource has another active command/cleanup.','GIT_PAGE_BUSY');this.#busy.add(resourceId);let active=true;return()=>{if(active){active=false;this.#busy.delete(resourceId);}};}
+ catalog(){return [...this.#recipes.values()].map(({descriptor,purpose})=>({name:descriptor.name,revision:descriptor.revision,digest:descriptor.digest,purpose}));}
+ seal(){if(!this.#recipes.size)throw fail('Register at least one host page recipe before constructing page-enabled tools.');this.#sealed=true;return immutable(this.catalog());}
+ register({name,revision,configuration_digest,task,verifier,runtimeFactory,fixture_sha256,purpose='Host-registered bounded page check'}){
+  if(this.#sealed)throw fail('Host recipe registry is sealed for this tool catalogue. Construct a fresh registry and tool runtime to change it.','GIT_PAGE_REGISTRY_SEALED');
+  if(this.#recipes.size>=24||typeof purpose!=='string'||!purpose||purpose.length>240||!revision||revision.length>120)throw fail('Host recipe catalogue exceeds its public bound.');
+  if(!/^[a-z][a-z0-9_-]{0,79}$/.test(name||'')||typeof revision!=='string'||!revision||!/^[a-f0-9]{64}$/.test(configuration_digest||'')||typeof runtimeFactory!=='function'||!/^[a-f0-9]{64}$/.test(fixture_sha256||'')||this.#recipes.has(name))throw fail('A unique versioned host page recipe is required.');
+  const template=normalizeTask({...task,surface:'page',project:'git-page-recipe'});
+  if(!template.verification.cases?.length)throw fail('This page adapter requires an explicit complete ordered case contract.');
+  assertPageVerifier(verifier,template.verification);
+  const implementation=pageImplementation(runtimeFactory,this);
+  const value={name,revision,configuration_digest,task:template,verifier:verifier.descriptor,fixture_sha256,implementation};
+  const descriptor=immutable({...value,digest:digest(value)});descriptors.add(descriptor);
+  if(Buffer.byteLength(JSON.stringify([...this.catalog(),{name,revision,digest:descriptor.digest,purpose}]))>8000)throw fail('Host recipe public catalogue exceeds its byte bound.');
+  this.#recipes.set(name,{descriptor,verifier,runtimeFactory,purpose});return descriptor;
+ }
+ resolve(name){const entry=this.#recipes.get(name);if(!entry)throw fail('No host page recipe is registered under this name.');return entry.descriptor;}
+ bindings(verification){return isPageVerification(verification)?[this.resolve(verification.checks[0].recipe)]:undefined;}
+ references(verification){return this.bindings(verification)?.map(pageRecipeReference);}
+ assert(bindings,verification){
+  const expected=this.bindings(verification);
+  if(digest(expected?.map(pageRecipeReference)??null)!==digest(bindings??null))throw fail('The original host page recipe changed.','GIT_PAGE_RECIPE_CHANGED');return expected;
+ }
+ async adapter({context,tools,house,policy,prepared,reservation,recipe}){
+  const entry=this.#recipes.get(recipe.name);
+  if(!entry||entry.descriptor.digest!==recipe.digest||!descriptors.has(entry.descriptor)||digest(pageImplementation(entry.runtimeFactory,this))!==digest(recipe.implementation))throw fail('The original page recipe is unavailable.','GIT_PAGE_RECIPE_CHANGED');
+  const {cwd,store,session_id:sessionId,owner}=context,key=reservation.resource_id+':'+reservation.attempt_id;
+  const native=await store.load(sessionId);pageReservation(native,reservation);
+  if(reservation.kernel_identity!==context.kernel_identity||digest(reservation.host_implementation)!==digest(recipe.implementation)||reservation.case_revision!==pageCaseRevision(reservation))throw fail('The reserved page implementation/Case identity changed.','GIT_PAGE_RECIPE_CHANGED');
+  const task=normalizeTask({...recipe.task,project:'git-'+reservation.resource_id});
+  if(digest(task)!==reservation.task_digest||reservation.recipe_digest!==recipe.digest||reservation.candidate_commit!==prepared.candidate_commit||reservation.owner_digest!==digest(owner))throw fail('Page adapter does not own this reserved candidate.');
+  const source=await snapshotProject(cwd,task.directory,{signal:context.signal}),sourceDigest=digest(source.files.map(({path,sha256})=>({path,sha256})));
+  if(sourceDigest!==reservation.source_digest)throw fail('Reserved publication bytes changed.','GIT_VERIFICATION_SOURCE_CHANGED');
+  let resource=this.#runtimes.get(key);
+  if(!resource){
+   const runtime=await entry.runtimeFactory({resource_id:context.resource_id,attempt_id:context.attempt_id,cwd,owner:immutable(structuredClone(owner)),recipe});
+   if(typeof runtime?.install!=='function'||typeof runtime.close!=='function')throw fail('Host page runtime must provide workspace installation and explicit close.');
+   resource={runtime,owner:digest(owner),recipe:recipe.digest,houses:new WeakSet(),adapters:[]};this.#runtimes.set(key,resource);
+  }
+  if(resource.owner!==digest(owner)||resource.recipe!==recipe.digest)throw fail('Page runtime lease belongs to another source owner.');
+  if(resource.houses.has(house))throw fail('A page adapter is already installed on this verifier House.');
+  await resource.runtime.install({cwd,store,sessionId,house,policy,tools,signal:context.signal});resource.houses.add(house);
+  let inventory=native.rows.filter(r=>r.type==='git_page_runtime_inventory');
+  if(!inventory.length){
+   if(native.rows.some(r=>r.type==='house_proposal'&&r.call_id===reservation.publish_call_id))throw fail('Original pre-publication inventory is missing.','GIT_PAGE_EVIDENCE');
+   const targets=JSON.parse(await tools.execute('plugin__chrome-lab__Targets',{})),status=JSON.parse(await tools.execute('plugin__chrome-lab__Status',{}));
+   if(targets.truncated||status.extensions_truncated)throw fail('Native ownership inventory is truncated.','GIT_PAGE_EVIDENCE');
+   const value={targets:targets.targets,extensions:status.extensions,other_extensions_count:status.other_extensions_count};await store.append(sessionId,{type:'git_page_runtime_inventory',source:'git_page_host',reservation_digest:digest(reservation),inventory:value,inventory_digest:digest(value)});inventory=[{inventory:value,inventory_digest:digest(value),reservation_digest:digest(reservation)}];
+  }
+  if(inventory.length!==1||inventory[0].reservation_digest!==digest(reservation)||inventory[0].inventory_digest!==digest(inventory[0].inventory))throw fail('Original native ownership inventory changed.','GIT_PAGE_EVIDENCE');
+  const originalInventory=inventory[0].inventory;
+  const workflow=await prepareChromePageTask({cwd,store,sessionId,house,policy,executor:tools.executor,task,verifier:entry.verifier,source:'host_git_page_recipe',caseRevision:reservation.case_revision,caseImplementation:recipe.implementation.case});
+  const originals=new Map(['ChromePublish','ChromeTest','ChromePageCase','ChromePageBehavior'].map(name=>[name,house.registry.get(name)]));
+  const execute=async(name,callId,signal)=>{
+   for(const [name,operation] of originals)if(house.registry.get(name)!==operation)throw fail('Original page operation was replaced.','GIT_PAGE_EVIDENCE');
+   return JSON.parse(await workflow.wrap(tools.executor).execute(name,{}, {callId,signal}));
+  };
+  const adapter={task,source_digest:sourceDigest,async run(signal){
+   const book=await store.load(sessionId);
+   if(book.rows.some(r=>r.type==='house_proposal'&&(r.call_id===reservation.publish_call_id||r.call_id===reservation.test_call_id)))throw fail('An original page effect was already proposed; it is not replayed.','GIT_VERIFICATION_UNCERTAIN');
+   await execute('ChromePublish',reservation.publish_call_id,signal);
+   const published=await store.load(sessionId),state=published.rows.findLast(r=>r.type==='chrome_task_checkpoint')?.state;
+   if(!state?.binding||state.source_digest!==sourceDigest||!state.deployment||state.deployment.file_manifest_sha256!==state.file_manifest_sha256)throw fail('The original deployed candidate is unavailable.');
+   await store.append(sessionId,{type:'git_page_publication_bound',source:'git_page_host',reservation_digest:digest(reservation),source_digest:sourceDigest,binding:state.binding,publication:{attempt_id:state.attempt_id,file_manifest_sha256:state.file_manifest_sha256,extension_id:state.deployment.extension_id}});
+   return execute('ChromeTest',reservation.test_call_id,signal);
+  },final:(callId,signal)=>execute('ChromeTest',callId,signal),async cleanup(){
+   const book=await store.load(sessionId),state=book.rows.findLast(r=>r.type==='chrome_task_checkpoint')?.state;
+   if(!state?.binding||!state.deployment)throw fail('Owned page cleanup lacks its original publication.','GIT_PAGE_CLEANUP');
+   workflow.dispose();
+   const prefix='plugin__chrome-lab__',remove=house.guard('git-page-cleanup',view=>{
+    if(!view.operation.startsWith(prefix))return false;
+    const name=view.operation.slice(prefix.length);
+    return ['Targets','Status'].includes(name)||name==='CloseTab'&&view.input.target_id===state.binding.target_id||name==='Unload'&&view.input.project===task.project;
+   },{revision:'comal-git-page-cleanup-v1',configuration_digest:digest({project:task.project,binding:state.binding,extension_id:state.deployment.extension_id})});
+   try{
+    const call=async(name,input={},signal=context.signal)=>JSON.parse(await tools.execute(prefix+name,input,{signal}));
+    const targets=await call('Targets');if(targets.truncated)throw fail('Owned cleanup target inventory is truncated.','GIT_PAGE_CLEANUP');
+    const target=targets.targets.find(t=>t.target_id===state.binding.target_id);
+    if(target&&(target.type!=='page'||target.url!==state.binding.url))throw fail('Owned cleanup target was replaced.','GIT_PAGE_CLEANUP');
+    const status=await call('Status'),extensions=status.extensions.filter(e=>e.project===task.project);
+    if(status.extensions_truncated||extensions.length>1||extensions.length===1&&(extensions[0].extension_id||extensions[0].id)!==state.deployment.extension_id)throw fail('Owned cleanup extension was replaced.','GIT_PAGE_CLEANUP');
+    if(target){const closed=await call('CloseTab',{target_id:state.binding.target_id});if(closed.success!==true&&!(closed.closed===true&&closed.already_closed===true&&closed.target_id===state.binding.target_id))throw fail('Owned tab close was not acknowledged.','GIT_PAGE_CLEANUP');}
+    if(extensions.length){const unloaded=await call('Unload',{project:task.project});if(unloaded.unloaded!==true||unloaded.extension_id!==state.deployment.extension_id)throw fail('Owned extension unload was not acknowledged.','GIT_PAGE_CLEANUP');}
+    const settled=await settlePageAbsence({call,targetId:state.binding.target_id,project:task.project,originalStatus:status,originalTarget:target,signal:context.signal}),afterTargets=settled.targets,afterStatus=settled.status;
+    if(afterTargets.truncated||afterStatus.extensions_truncated||afterTargets.targets.some(t=>t.target_id===state.binding.target_id)||afterStatus.extensions.some(e=>e.project===task.project))throw fail('Owned resource absence was not observed.','GIT_PAGE_CLEANUP');
+    const foreign={targets:afterTargets.targets.filter(t=>t.target_id!==state.binding.target_id),extensions:afterStatus.extensions.filter(e=>e.project!==task.project),other_extensions_count:afterStatus.other_extensions_count},beforeForeign={targets:originalInventory.targets.filter(t=>t.target_id!==state.binding.target_id),extensions:originalInventory.extensions.filter(e=>e.project!==task.project),other_extensions_count:originalInventory.other_extensions_count};
+    if(digest(foreign)!==digest(beforeForeign))throw fail('Foreign native inventory changed; no foreign cleanup is attempted.','GIT_PAGE_CLEANUP');
+    await store.append(sessionId,{type:'git_page_cleanup',source:'git_page_host',reservation_digest:digest(reservation),target_id:state.binding.target_id,extension_id:state.deployment.extension_id,owned_absent:true,settlement_reads:settled.reads,observable_other_resources_unchanged:true,unrelated_extension_identity:'not_enumerated',before_inventory_digest:digest(originalInventory),after_inventory_digest:digest(foreign)});
+   }finally{remove();}
+  },dispose:()=>workflow.dispose()};
+  resource.adapters.push(adapter);return adapter;
+ }
+ // Explicit host lifecycle. Closing the transport does not claim remote tab or
+ // extension deletion. The host runtime must retain/report its owned cleanup.
+ async close(resourceId,attemptId,{cleanup=true}={}){
+  const key=resourceId+':'+attemptId,resource=this.#runtimes.get(key);if(!resource)return{closed:false};
+  if(cleanup&&resource.adapters.length){if(resource.cleanupAttempted)throw fail('Cleanup was already attempted. Original effects are not replayed; retain and inspect their native results.','GIT_PAGE_CLEANUP_UNCERTAIN');resource.cleanupAttempted=true;await resource.adapters.at(-1).cleanup();}
+  for(const adapter of resource.adapters)adapter.dispose();await resource.runtime.close();this.#runtimes.delete(key);return{closed:true};
+ }
+ async closeAll(options){for(const key of [...this.#runtimes.keys()]){const at=key.lastIndexOf(':');await this.close(key.slice(0,at),key.slice(at+1),options);}}
+}
+
+export async function reservePageCheck({context,prepared,recipe,check,phase}){
+ const task=normalizeTask({...recipe.task,project:'git-'+context.resource_id});
+ const snapshot=await snapshotProject(context.cwd,task.directory,{signal:context.signal});
+ if(snapshot.files.find(file=>file.path===task.fixture.file)?.sha256!==recipe.fixture_sha256)throw fail('The host-owned page fixture differs from its original recipe.','GIT_PAGE_FIXTURE_CHANGED');
+ const value={
+  format:'comal-git-page-check/1',resource_id:context.resource_id,attempt_id:context.attempt_id,check_id:check.id,
+  owner_digest:digest(context.owner),candidate_commit:prepared.candidate_commit,source_identity:prepared.source_identity,
+  recipe_digest:recipe.digest,task_digest:digest(task),source_digest:digest(snapshot.files.map(({path,sha256})=>({path,sha256}))),file_manifest_sha256:physicalHash(snapshot),
+  publish_call_id:randomUUID(),test_call_id:randomUUID(),native_binding:context.binding,host_implementation:recipe.implementation,kernel_identity:context.kernel_identity,
+ };return phase('page_reservation',{...value,case_revision:pageCaseRevision(value)});
+}
+
+function pageImplementation(runtimeFactory,registry){return {format:'comal-git-page-implementation/1',case:PAGE_CASE_IMPLEMENTATION_DIGEST,law:PAGE_LAW_IMPLEMENTATION_DIGEST,workflow:digest(Function.prototype.toString.call(prepareChromePageTask)),adapter:hostCodeIdentity(registry,GitPageRegistry),identity_function:digest(Function.prototype.toString.call(hostCodeIdentity)),runtime_factory:digest(Function.prototype.toString.call(runtimeFactory)),proof:pageProofImplementation(),settlement:pageSettlementImplementation()};}
+const physicalHash=snapshot=>{const json=JSON.stringify(snapshot.files.map(({path,sha256})=>({path,sha256})));return createHash('sha256').update(json).digest('hex');};

package/src/git-plumbing.mjs

@@ -0,0 +1,212 @@
+import {spawn,execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {mkdir,lstat,stat,realpath,readFile,readlink,access} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {processDead,processIdentity} from './process-lock.mjs';
+import {ensurePrivateDirectory,assertPrivateDirectory} from './private-fs.mjs';
+import assert from 'node:assert/strict';
+import {performance} from 'node:perf_hooks';
+import {constants} from 'node:fs';
+import {createHash} from 'node:crypto';
+const exec=promisify(execFile);
+export const gitFailure=(message,code='GIT_RESOURCE_UNCERTAIN')=>Object.assign(new Error(message),{code});
+export async function privateGitDirectory(directory){
+ directory=path.resolve(directory);let ancestor=directory;
+ for(;;){try{if(await realpath(ancestor)!==ancestor)throw gitFailure('Git host state has a noncanonical ancestor.');break;}catch(error){if(error.code!=='ENOENT')throw error;ancestor=path.dirname(ancestor);}}
+ try{await ensurePrivateDirectory(directory);await assertPrivateDirectory(directory);}catch{throw gitFailure('Git host state requires a private canonical directory.');}
+ return directory;
+}
+const baseArgs=['--no-pager','--no-optional-locks','--literal-pathspecs','-c','core.fsmonitor=false','-c','core.hooksPath=/dev/null','-c','core.autocrlf=false','-c','commit.gpgsign=false'];
+export function gitHostEnvironment(extra={}){
+ return{...Object.fromEntries(Object.entries(process.env).filter(([key])=>!key.startsWith('GIT_'))),GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0',GIT_OPTIONAL_LOCKS:'0',LC_ALL:'C',...extra};
+}
+export function gitWorkerGone(fact){
+ if(!fact?.identity||!processDead(fact.identity))return false;
+ if(process.platform==='win32')return false; // A dead worker alone cannot prove its descendant is gone.
+ if(fact.process_group!==fact.identity.pid)return false;
+ try{process.kill(-fact.process_group,0);return false;}catch(error){return error.code==='ESRCH';}
+}
+export async function readGit(cwd,args,{signal,gitDir,env={},maxOutput=4*1024*1024,allowed=[]}={}){
+ if(!['rev-parse','show-ref','for-each-ref','ls-tree','ls-files','cat-file','check-ref-format'].includes(args[0])&&!(args[0]==='worktree'&&args[1]==='list'))throw gitFailure('This Git command is not on the native observation surface.','GIT_COMMAND_SCOPE');
+ if(args[0]==='cat-file'&&!['blob','commit','tree','-s','-t','-e'].includes(args[1]))throw gitFailure('Git object inspection cannot request project conversions.','GIT_COMMAND_SCOPE');
+ try{return{code:0,stdout:(await exec('git',[...baseArgs,...gitDir?['--git-dir='+gitDir]:[],...args],{cwd,env:gitHostEnvironment(env),signal,timeout:15000,maxBuffer:maxOutput,encoding:'buffer'})).stdout};}
+ catch(error){if(allowed.includes(error.code))return{code:error.code,stdout:error.stdout||Buffer.alloc(0)};if(signal?.aborted)throw signal.reason;throw gitFailure('Git observation failed or exceeded its bound.','GIT_OBSERVATION_FAILED');}
+}
+// Two fixed source-selected callers share one executor. No serialized backend.
+export async function mutateGit(cwd,args,options={}){return mutateGitCommand(cwd,args,options,false);}
+export async function mutateGitWithChildWitness(cwd,args,options={}){return mutateGitCommand(cwd,args,options,true);}
+async function mutateGitCommand(cwd,args,{signal,gitDir,env={},input,maxOutput=4*1024*1024,allowed=[],recordWorker,recordChild,commandId,timeoutMs=30000}={},observed=false){
+ const originalDeadline=observed?performance.now()+timeoutMs:null;
+ if(!['init','hash-object','update-index','write-tree','commit-tree','update-ref','worktree','read-tree','merge-tree'].includes(args[0])||args[0]==='merge-tree'&&!gitDir||args[0]==='hash-object'&&(!args.includes('--no-filters')||!args.includes('--stdin')))throw gitFailure('This Git command is not on the bounded native mutation surface.','GIT_COMMAND_SCOPE');
+ if(typeof recordWorker!=='function')throw gitFailure('A durable worker gate is required.');
+ if(observed){
+  assert(Number.isFinite(timeoutMs)&&timeoutMs>0&&timeoutMs<=30000);
+  if(process.platform!=='linux')throw gitFailure('Native child witness is Linux-only.','GIT_CHILD_PLATFORM');
+  assertGitCommandId(commandId);if(typeof recordChild!=='function')throw gitFailure('A durable child recorder is required.','GIT_CHILD_RECORDER_REQUIRED');
+  args=structuredClone(args);env=structuredClone(env);allowed=structuredClone(allowed);
+  if(input!==undefined){assert(Buffer.isBuffer(input)||input instanceof Uint8Array);input=Buffer.from(input);}
+ }
+ signal?.throwIfAborted();
+ const nativeArgs=observed?[...baseArgs,...gitDir?['--git-dir='+gitDir]:[],...args]:null;
+ const gate=observed&&gitCommandNeedsInputGate(args),inputHash=observed?shaInput(input):null,nativeHash=observed?shaInput(Buffer.from(JSON.stringify(nativeArgs))):null;
+ const expectedExe=gate?await selectedGitExecutable(gitHostEnvironment(env),cwd):null;
+ signal?.throwIfAborted();if(observed&&performance.now()>=originalDeadline)throw gitFailure('Original Git command deadline expired before worker spawn.','GIT_COMMAND_INTERRUPTED');
+ const child=spawn(process.execPath,[fileURLToPath(new URL('./git-process-worker.mjs',import.meta.url))],{cwd,detached:process.platform!=='win32',stdio:['ignore','ignore','pipe','ipc'],serialization:'advanced',windowsHide:true});
+ let result,workerFact,readySeen=false,spawnSeen=false,released=false,closed=false,cancelled=false,dispatched=false,killTimer,stderr='',gateError,gating=Promise.resolve();child.stderr.on('data',b=>{if(stderr.length<8192)stderr+=b;});
+ const abort=()=>{if(observed&&cancelled)return;cancelled=true;if(child.connected)child.send(observed?{format:GIT_INPUT_GATE_PROTOCOL,type:'cancel',command_id:commandId}:{type:'cancel'},()=>{});else child.kill('SIGTERM');killTimer=setTimeout(()=>{if(!closed){try{process.platform==='win32'?child.kill('SIGKILL'):process.kill(-child.pid,'SIGKILL');}catch{}}},500);};
+ const timer=setTimeout(abort,observed?Math.max(0,originalDeadline-performance.now()):timeoutMs);signal?.addEventListener('abort',abort,{once:true});
+ try{
+  return await new Promise((resolve,reject)=>{
+   child.on('error',error=>{gateError=error;});
+   child.on('message',message=>{
+    if(message.type==='ready'){
+     if(observed&&readySeen){gateError??=gitFailure('Duplicate native worker readiness.','GIT_COMMAND_PROTOCOL');abort();return;}readySeen=true;
+     if(observed&&!message.protocols?.includes(GIT_INPUT_GATE_PROTOCOL)){gateError=gitFailure('Native worker protocol is unavailable.','GIT_COMMAND_PROTOCOL');abort();return;}
+     gating=(async()=>{try{
+      if(cancelled||signal?.aborted){abort();return;}
+      // This await is the command's execution frontier. A failed recorder must
+      // never release the IPC gate, even if the worker itself is alive.
+      if(observed){assert.equal(message.identity?.pid,child.pid);assert.equal(message.process_group,child.pid);for(const k of ['host','boot','namespace'])assert.equal(message.identity[k],processIdentity[k]);}
+      workerFact=Object.freeze({identity:Object.freeze({...message.identity}),process_group:message.process_group});
+      if(observed)await recordWorker(structuredClone(workerFact),Object.freeze({format:GIT_INPUT_GATE_PROTOCOL,command_id:commandId,input_sha256:inputHash,native_args:Object.freeze([...nativeArgs]),input_gate:gate}));
+      else await recordWorker({identity:message.identity,process_group:message.process_group});
+      signal?.throwIfAborted();if(observed&&performance.now()>=originalDeadline){abort();return;}if(cancelled){abort();return;}
+      dispatched=true;child.send(observed?{format:GIT_INPUT_GATE_PROTOCOL,type:'execute',command_id:commandId,cwd,args:nativeArgs,env:gitHostEnvironment(env),input,maxOutput}:{type:'execute',cwd,args:[...baseArgs,...gitDir?['--git-dir='+gitDir]:[],...args],env:gitHostEnvironment(env),input,maxOutput},error=>{if(error){gateError=error;abort();}});
+     }catch(error){gateError=error;abort();}})();
+    }else if(observed&&message.type==='spawned'){
+     if(spawnSeen){gateError=gitFailure('Duplicate child spawn observation.','GIT_COMMAND_PROTOCOL');abort();return;}spawnSeen=true;
+     gating=gating.then(async()=>{try{
+      signal?.throwIfAborted();if(cancelled)return;assert(gate&&dispatched);assertProtocolMessage(message,'spawned',commandId,'child_pid');
+      const before=await gitChildIdentity(message.child_pid,workerFact,nativeArgs,expectedExe);
+      const witness={format:GIT_INPUT_GATE_PROTOCOL,command_id:commandId,worker:structuredClone(workerFact),child:before,input_sha256:inputHash,args_sha256:nativeHash};
+      assertGitChildWitness(witness,{command_id:commandId,worker:workerFact,input_sha256:inputHash,native_args:nativeArgs});
+      signal?.throwIfAborted();if(performance.now()>=originalDeadline){abort();return;}if(cancelled)return;
+      await recordChild(structuredClone(witness)); // Durable join plus current host frame, never model callback.
+      signal?.throwIfAborted();if(performance.now()>=originalDeadline){abort();return;}if(cancelled)return;
+      assert.deepEqual(await gitChildIdentity(message.child_pid,workerFact,nativeArgs,expectedExe),before,'Native Git child identity changed before stdin release');
+      signal?.throwIfAborted();if(performance.now()>=originalDeadline){abort();return;}if(cancelled)return;
+      released=true;child.send({format:GIT_INPUT_GATE_PROTOCOL,type:'release_stdin',command_id:commandId},error=>{if(error){gateError=error;abort();}});
+     }catch(error){gateError??=error;abort();}});
+    }else if(message.type==='result'){
+     try{if(observed){assertProtocolMessage(message,'result',commandId,'code,signal,overflow,spawnError,stdout,stderr,input_released');assert(!result,'Duplicate native result');if(gate&&message.code===0&&!message.spawnError&&!message.signal)assert(released&&message.input_released===true,'Successful input command has no original input release');}result=message;}
+     catch(error){gateError??=error;abort();}
+    }else if(observed){gateError??=gitFailure('Unknown native worker message.','GIT_COMMAND_PROTOCOL');abort();}
+   });
+   child.on('close',async()=>{
+    closed=true;
+    await gating;
+    if(gateError){reject(observed&&signal?.aborted?signal.reason:gateError);return;}
+    if(observed&&performance.now()>=originalDeadline)cancelled=true;
+    if(cancelled||signal?.aborted){reject(signal?.reason||gitFailure('Git command was cancelled or exceeded its deadline.','GIT_COMMAND_INTERRUPTED'));return;}
+    if(!result||result.spawnError||result.overflow||result.signal||result.code!==0&&!allowed.includes(result.code)){
+     const failure=gitFailure('Git command failed; inspect its prepared resource before proposing another effect. '+(result?.overflow?'Output bound exceeded.':result?.spawnError||result?.stderr?.toString('utf8').slice(0,1000)||stderr.slice(0,300)),'GIT_COMMAND_FAILED');
+     if(result&&!result.spawnError&&!result.overflow&&!result.signal&&Number.isInteger(result.code))failure.git_exit={code:result.code,stdout:result.stdout};reject(failure);return;
+    }
+    resolve({code:result.code,stdout:result.stdout});
+   });
+  });
+ }catch(error){if(!dispatched&&closed)error.git_dispatch='not_released';throw error;}
+ finally{clearTimeout(timer);clearTimeout(killTimer);signal?.removeEventListener('abort',abort);}
+}
+
+export const GIT_INPUT_GATE_PROTOCOL='comal-git-command-input-gate/2';
+const shaInput=b=>createHash('sha256').update(b??Buffer.alloc(0)).digest('hex');
+export function assertGitCommandId(id){assert.match(id,/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/);}
+export function gitCommandNeedsInputGate(args){
+ assert(Array.isArray(args)&&args.every(x=>typeof x==='string'&&!x.includes('\0')));
+ return args[0]==='hash-object'&&args.includes('--stdin')||args[0]==='update-index'&&args.includes('--index-info')||args[0]==='commit-tree'&&!args.some(x=>x==='-m'||x==='-F'||x.startsWith('-m')||x.startsWith('-F'));
+}
+export function gitWorkerInputGate(args){assert.deepEqual(args.slice(0,baseArgs.length),baseArgs);let rest=args.slice(baseArgs.length);if(rest[0]?.startsWith('--git-dir='))rest=rest.slice(1);return gitCommandNeedsInputGate(rest);}
+export function assertProtocolMessage(message,type,id,extra=''){
+ assert(message&&typeof message==='object'&&!Array.isArray(message));assert.deepEqual(Object.keys(message).sort(),['format','type','command_id',...(extra?extra.split(','):[])].sort());
+ assert.equal(message.format,GIT_INPUT_GATE_PROTOCOL);assert.equal(message.type,type);assert.equal(message.command_id,id);assertGitCommandId(id);
+}
+// Grammar/lifecycle state only. It cannot spawn/select work or certify a PID.
+export function createGitInputReleaseState(id){
+ assertGitCommandId(id);let phase='awaiting_spawn';return Object.freeze({
+  spawned(pid){assert.equal(phase,'awaiting_spawn');assert(Number.isSafeInteger(pid)&&pid>1);phase='awaiting_release';},
+  release(message){assertProtocolMessage(message,'release_stdin',id);assert.equal(phase,'awaiting_release');phase='released';},
+  cancel(message){assertProtocolMessage(message,'cancel',id);assert.notEqual(phase,'cancelled');phase='cancelled';},
+  released(){return phase==='released';}
+ });
+}
+export function assertGitChildWitness(value,prepared){
+ assert.deepEqual(Object.keys(value).sort(),['args_sha256','child','command_id','format','input_sha256','worker']);
+ assert.equal(value.format,GIT_INPUT_GATE_PROTOCOL);assertGitCommandId(value.command_id);assert.equal(value.command_id,prepared.command_id);assert.deepEqual(value.worker,prepared.worker);
+ assert.equal(value.input_sha256,prepared.input_sha256);assert.equal(value.args_sha256,shaInput(Buffer.from(JSON.stringify(prepared.native_args))));
+ const c=value.child,w=prepared.worker;assert.deepEqual(Object.keys(c).sort(),['argv','boot','executable','host','namespace','pid','ppid','process_group','start']);
+ assert(Number.isSafeInteger(c.pid)&&c.pid>1&&c.pid!==w.identity.pid);assert.equal(c.ppid,w.identity.pid);assert.equal(c.process_group,w.process_group);assert.equal(w.process_group,w.identity.pid);
+ for(const k of ['host','boot','namespace']){assert.equal(typeof c[k],'string');assert(c[k].length>0);assert.equal(c[k],w.identity[k]);}
+ assert.match(c.start,/^[0-9]+$/);assert(typeof c.executable==='string'&&path.isAbsolute(c.executable)&&path.resolve(c.executable)===c.executable);assert.deepEqual(c.argv.slice(1),prepared.native_args);assert.equal(c.argv[0],'git');
+}
+export function assertGitPreparedInputCommand(row){
+ assert.equal(row.dispatch_protocol,GIT_INPUT_GATE_PROTOCOL);assertGitCommandId(row.command_id);
+ assert.match(row.input_sha256,/^[a-f0-9]{64}$/);assert.deepEqual(row.native_args.slice(0,baseArgs.length),baseArgs);
+ let args=row.native_args.slice(baseArgs.length);if(args[0]?.startsWith('--git-dir='))args=args.slice(1);
+ assert.deepEqual(args,row.args);assert.equal(row.input_gate,gitCommandNeedsInputGate(row.args));
+ assert.deepEqual(Object.keys(row.worker).sort(),['identity','process_group']);assert.deepEqual(Object.keys(row.worker.identity).sort(),['boot','host','namespace','pid','start','version']);assert.equal(row.worker.identity.version,1);
+ for(const k of ['host','boot','namespace'])assert(typeof row.worker.identity[k]==='string'&&row.worker.identity[k].length>0);assert.match(row.worker.identity.start,/^[0-9]+$/);
+ assert.equal(row.worker.process_group,row.worker.identity.pid);assert(Number.isSafeInteger(row.worker.identity.pid)&&row.worker.identity.pid>1);
+}
+// Structural law for new rows only; load() separately authenticates its full
+// journal/resource/owner. Pure return is not permission or native attestation.
+export function assertGitChildJournal(rows){
+ const native=new Map(),spawned=new Set(),ended=new Set(),actions=new Set();
+ const keys=(row,names)=>assert.deepEqual(Object.keys(row).sort(),[...names,...(Object.hasOwn(row,'recovered_append_lock')?['recovered_append_lock']:[])].sort());
+ for(const row of rows){
+  if(row.type==='git_action_prepared')actions.add(JSON.stringify([row.action,row.attempt]));
+  if(row.type==='git_command_prepared'&&row.dispatch_protocol!==undefined){
+   keys(row,['type','action','attempt','command_id','args','input_sha256','worker','dispatch_protocol','native_args','input_gate','source','mechanism','timestamp','audit']);
+   assert(actions.has(JSON.stringify([row.action,row.attempt])));assertGitPreparedInputCommand(row);assert(!native.has(row.command_id));native.set(row.command_id,row);
+  }else if(row.type==='git_command_spawned'){
+   keys(row,['type','action','attempt','command_id','prepared_sha256','witness','source','mechanism','timestamp','audit']);
+   const p=native.get(row.command_id);assert(p&&p.input_gate&&!spawned.has(row.command_id)&&!ended.has(row.command_id),'Unbound, duplicate or late spawned child');
+   assert.equal(row.action,p.action);assert.equal(row.attempt,p.attempt);assert.equal(row.prepared_sha256,p.audit.sha256);assertGitChildWitness(row.witness,p);spawned.add(row.command_id);
+  }else if(row.type==='git_command_returned'&&native.has(row.command_id)){
+   const p=native.get(row.command_id);assert(!ended.has(row.command_id));assert.equal(row.action,p.action);assert.equal(row.attempt,p.attempt);
+   const extras=['output_sha256','dispatch','scope'].filter(k=>Object.hasOwn(row,k));keys(row,['type','action','attempt','command_id','code','source','mechanism','timestamp','audit',...extras]);
+   if(row.dispatch!==undefined){assert.equal(row.dispatch,'not_released');assert.equal(row.scope,'no_git_process_started');assert.equal(row.code,null);assert(!Object.hasOwn(row,'output_sha256'));assert(!spawned.has(row.command_id),'Spawned command falsely says not released');}
+   else{assert(Number.isInteger(row.code));assert.match(row.output_sha256,/^[a-f0-9]{64}$/);if(row.scope!==undefined)assert.equal(row.scope,'native_git_exit_observed');if(p.input_gate)assert(spawned.has(row.command_id),'Input result lacks durable spawn');}
+   ended.add(row.command_id);
+  }
+ }
+}
+async function selectedGitExecutable(env,cwd){
+ for(const entry of(env.PATH??'').split(path.delimiter)){
+  const candidate=path.resolve(cwd,entry||'.','git');try{await access(candidate,constants.X_OK);const file=await realpath(candidate);assert((await lstat(file)).isFile());return file;}catch(e){if(['ENOENT','ENOTDIR','EACCES'].includes(e.code))continue;throw e;}
+ }
+ throw gitFailure('Actual native Git executable is unavailable.','GIT_COMMAND_PROTOCOL');
+}
+async function gitChildIdentity(pid,worker,args,expectedExe){
+ assert(Number.isSafeInteger(pid)&&pid>1);const base='/proc/'+pid,raw=await readFile(base+'/stat','utf8'),f=raw.slice(raw.lastIndexOf(')')+2).trim().split(/\s+/);
+ assert(!['Z','X','x'].includes(f[0]),'Native Git child is not live');assert.equal(Number(f[1]),worker.identity.pid);assert.equal(Number(f[2]),worker.process_group);
+ const executable=await realpath(base+'/exe');assert.equal(executable,expectedExe);const a=await stat(base+'/exe'),b=await stat(expectedExe);assert.equal(a.dev,b.dev);assert.equal(a.ino,b.ino);
+ const argv=(await readFile(base+'/cmdline')).toString().split('\0');assert.equal(argv.pop(),'');assert.equal(argv[0],'git');assert.deepEqual(argv.slice(1),args);
+ const identity={pid,ppid:Number(f[1]),process_group:Number(f[2]),start:f[19],host:processIdentity.host,boot:(await readFile('/proc/sys/kernel/random/boot_id','utf8')).trim(),namespace:await readlink(base+'/ns/pid'),executable,argv};
+ for(const k of ['host','boot','namespace'])assert.equal(identity[k],worker.identity[k]);return identity;
+}
+
+// Reads repository objects through a house-owned bare repository. Project merge
+// drivers, filters, includes and signing programs are never its configuration.
+export class GitPlumbing {
+ constructor({cwd,directory,repository,mutate}){Object.assign(this,{cwd,directory,repository,mutate});}
+ async prepare(signal){
+  const common=(await readGit(this.cwd,['rev-parse','--path-format=absolute','--git-common-dir'],{signal})).stdout.toString().replace(/\n$/,'');
+  if(await realpath(common)!==this.repository.common_directory)throw gitFailure('The repository identity changed.','GIT_REPOSITORY_CHANGED');
+  await privateGitDirectory(this.directory);this.bare=path.join(this.directory,'plumbing.git');this.empty=path.join(this.directory,'empty-template');await privateGitDirectory(this.empty);
+  try{const info=await lstat(this.bare);if(!info.isDirectory()||info.isSymbolicLink())throw gitFailure('Plumbing metadata is not an owned directory.');}
+  catch(error){if(error.code!=='ENOENT')throw error;await this.mutate(['init','--bare','--quiet','--object-format='+this.repository.object_format,'--template='+this.empty,this.bare],{signal});}
+  const config=await readFile(path.join(this.bare,'config'),'utf8');
+  // Only Git init's closed baseline is admitted. In particular no include,
+  // driver, command, worktree, proxy, extension or credential is inherited.
+  const baseline=this.repository.object_format==='sha256'?'\tobjectformat = sha256':'';
+  for(const line of config.trim().split(/\r?\n/))if(!/^\[(core|extensions)\]$/.test(line)&&!/^\s*(repositoryformatversion = [01]|filemode = (true|false)|bare = true)\s*$/.test(line)&&!(process.platform==='win32'&&/^\s*(symlinks = false|ignorecase = true)\s*$/.test(line))&&line!==baseline)throw gitFailure('Plumbing configuration changed; no project code was executed.');
+  const format=(await readGit(this.cwd,['rev-parse','--show-object-format'],{signal,gitDir:this.bare})).stdout.toString().trim();if(format!==this.repository.object_format)throw gitFailure('Plumbing object format differs.');
+  this.objectDirectory=path.resolve((await readGit(this.cwd,['rev-parse','--path-format=absolute','--git-path','objects'],{signal})).stdout.toString().replace(/\n$/,''));
+  if(await realpath(this.objectDirectory)!==this.objectDirectory)throw gitFailure('Git object directory is noncanonical.');
+ }
+ options(options={}){return{...options,gitDir:this.bare,env:{GIT_OBJECT_DIRECTORY:this.objectDirectory,...options.env}};}
+ read(args,options){return readGit(this.cwd,args,this.options(options));}
+ write(args,options){return this.mutate(args,this.options(options));}
+}

package/src/git-process-worker.mjs

@@ -0,0 +1,50 @@
+// Host-only v1 worker plus fixed Linux v2 original-input gate. No shell/loader.
+import {spawn} from 'node:child_process';
+import {processIdentity} from './process-lock.mjs';
+import {GIT_INPUT_GATE_PROTOCOL,assertProtocolMessage,gitWorkerInputGate,createGitInputReleaseState} from './git-plumbing.mjs';
+let launched=false,child,stopping=false,protocol2=null,releaseState,pendingInput,inputWasReleased=false;
+const stop=()=>{
+ if(stopping)return;stopping=true;
+ if(process.platform!=='win32'){
+  process.removeAllListeners('SIGTERM');
+  try{process.kill(-process.pid,'SIGTERM');}catch{process.exit(1);}
+ }else if(child){child.kill();}else process.exit(1);
+};
+process.on('disconnect',stop);process.on('SIGTERM',stop);
+// One actual Git spawn/output executor for the two source-selected protocols.
+function launch(message,observed){
+ const {cwd,args,env,input,maxOutput}=message,gate=observed&&gitWorkerInputGate(args);
+ child=spawn('git',args,{cwd,env,stdio:['pipe','pipe','pipe'],windowsHide:true});
+ const out=[],err=[];let length=0,errLength=0,overflow=false,spawnError;
+ child.on('error',error=>{spawnError=error.message;});
+ child.stdout.on('data',buffer=>{length+=buffer.length;if(length>maxOutput){overflow=true;child.kill();}else out.push(buffer);});
+ child.stderr.on('data',buffer=>{if(errLength<8192){err.push(buffer.subarray(0,8192-errLength));errLength+=buffer.length;}});
+ child.stdin.on('error',()=>{});
+ if(observed){pendingInput=input;child.once('spawn',()=>{try{
+  if(gate){releaseState.spawned(child.pid);process.send({format:GIT_INPUT_GATE_PROTOCOL,type:'spawned',command_id:protocol2,child_pid:child.pid},error=>{if(error)stop();});}
+  else{child.stdin.end(pendingInput||undefined);pendingInput=undefined;}
+ }catch{stop();}});}else child.stdin.end(input||undefined);
+ child.on('close',(code,signal)=>{
+  pendingInput=undefined;
+  if(!process.connected){process.exit(1);return;}
+  if(observed)process.send({format:GIT_INPUT_GATE_PROTOCOL,type:'result',command_id:protocol2,code,signal,overflow,spawnError,stdout:Buffer.concat(out),stderr:Buffer.concat(err),input_released:inputWasReleased},()=>{process.removeAllListeners('disconnect');process.disconnect();});
+  else process.send({type:'result',code,signal,overflow,spawnError,stdout:Buffer.concat(out),stderr:Buffer.concat(err)},()=>{process.removeAllListeners('disconnect');process.disconnect();});
+ });
+}
+function version2(message){
+ try{
+  if(message.type==='cancel'){assertProtocolMessage(message,'cancel',message.command_id);if(protocol2){if(message.command_id!==protocol2)throw Error('Stale cancel');releaseState.cancel(message);}stop();return;}
+  if(message.type==='release_stdin'){
+   if(!protocol2||message.command_id!==protocol2)throw Error('No matching spawned command');releaseState.release(message);inputWasReleased=true;child.stdin.end(pendingInput||undefined);pendingInput=undefined;return;
+  }
+  assertProtocolMessage(message,'execute',message.command_id,'cwd,args,env,input,maxOutput');
+  if(process.platform!=='linux'||launched)throw Error('Unavailable or repeated native protocol');launched=true;protocol2=message.command_id;releaseState=createGitInputReleaseState(protocol2);launch(message,true);
+ }catch{stop();}
+}
+process.on('message',message=>{
+ if(message?.format===GIT_INPUT_GATE_PROTOCOL){version2(message);return;}
+ if(protocol2){stop();return;}
+ if(message?.type==='cancel'){stop();return;}
+ if(message?.type!=='execute'||launched)return;launched=true;launch(message,false);
+});
+process.send({type:'ready',identity:processIdentity,process_group:process.platform==='win32'?null:process.pid,protocols:process.platform==='linux'?[GIT_INPUT_GATE_PROTOCOL]:[]});

package/src/git-source.mjs

@@ -0,0 +1,110 @@
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {lstat,open,readlink,realpath} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {createHash} from 'node:crypto';
+import path from 'node:path';
+import {digest,immutable} from './operations.mjs';
+
+const exec=promisify(execFile),hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+const fail=(message,code='GIT_SOURCE_UNSUPPORTED')=>Object.assign(new Error(message),{code});
+const protectedRoot=/^(?:\.git|\.comal|\.harness|\.analysis)(?:\/|$)/;
+function text(bytes){const value=bytes.toString('utf8');if(!Buffer.from(value).equals(bytes))throw fail('Git source names require lossless UTF-8.');return value;}
+const line=bytes=>text(bytes).replace(/\n$/,'');
+const blobHash=(bytes,format)=>createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+function environment(){
+ const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>!key.startsWith('GIT_')));
+ return{...env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0',GIT_OPTIONAL_LOCKS:'0',LC_ALL:'C'};
+}
+async function git(cwd,args,signal,allowed=[]){
+ try{return(await exec('git',['--no-pager','--no-optional-locks','--literal-pathspecs','-c','core.fsmonitor=false','-c','core.hooksPath=/dev/null','-c','status.submoduleSummary=false',...args],{cwd,env:environment(),signal,timeout:10000,maxBuffer:4*1024*1024,encoding:'buffer'})).stdout;}
+ catch(error){if(allowed.includes(error.code))return null;if(signal?.aborted)throw signal.reason;throw fail('Git inspection failed or exceeded its bound. No partial identity was issued.','GIT_INSPECT_FAILED');}
+}
+async function fileHash(file,budget,signal,format){
+ const before=await lstat(file,{bigint:true}).catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+ if(!before)return{kind:'absent'};
+ if(before.isSymbolicLink()){const bytes=await readlink(file,{encoding:'buffer'});if(bytes.length>budget.remaining)throw fail('Git source exceeds the total byte bound.','GIT_SOURCE_BOUND');budget.remaining-=bytes.length;return{kind:'symlink',sha256:hash(bytes),...(format?{blob_oid:blobHash(bytes,format)}:{})};}
+ if(!before.isFile())throw fail('Git source contains a nonregular file.');
+ if(before.size>BigInt(budget.remaining))throw fail('Git source exceeds the total byte bound.','GIT_SOURCE_BOUND');
+ const handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+ try{
+  const opened=await handle.stat({bigint:true});
+  if(opened.ino!==before.ino||opened.dev!==before.dev)throw fail('Source changed while opening.','GIT_SOURCE_CHANGED');
+  const sha=createHash('sha256'),blob=format?createHash(format).update(`blob ${before.size}\0`):null,buffer=Buffer.alloc(128*1024);let bytes=0;
+  for(;;){signal.throwIfAborted();const result=await handle.read(buffer,0,buffer.length,null);if(!result.bytesRead)break;bytes+=result.bytesRead;if(bytes>budget.remaining)throw fail('Git source exceeds the total byte bound.','GIT_SOURCE_BOUND');const chunk=buffer.subarray(0,result.bytesRead);sha.update(chunk);blob?.update(chunk);}
+  const after=await handle.stat({bigint:true});
+  if(before.size!==after.size||before.mtimeNs!==after.mtimeNs||before.ctimeNs!==after.ctimeNs||before.mode!==after.mode||BigInt(bytes)!==after.size)throw fail('Source changed during hashing.','GIT_SOURCE_CHANGED');
+  budget.remaining-=bytes;return{kind:'file',bytes,executable:Boolean(before.mode&0o111n),sha256:sha.digest('hex'),...(blob?{blob_oid:blob.digest('hex')}:{})};
+ }finally{await handle.close();}
+}
+async function metadata(cwd,signal){
+ const head=await git(cwd,['rev-parse','--verify','--quiet','HEAD'],signal,[1]),branch=await git(cwd,['symbolic-ref','--quiet','HEAD'],signal,[1]);
+ const indexPath=line(await git(cwd,['rev-parse','--path-format=absolute','--git-path','index'],signal));
+ const index=await fileHash(indexPath,{remaining:64*1024*1024},signal);
+ if(!['file','absent'].includes(index.kind))throw fail('Git index is not a bounded regular file.');
+ // status/diff of a working tree can execute project clean filters. Object and
+ // index listings do not refresh/convert source; raw blob hashes are computed here.
+ const committed=head?await git(cwd,['ls-tree','-r','-z','--full-tree','HEAD'],signal):Buffer.alloc(0);
+ const tracked=await git(cwd,['ls-files','--stage','-z'],signal),listed=await git(cwd,['ls-files','--others','--exclude-standard','-z'],signal);
+ // Host journals/worktrees are not source. Apply the same exclusion before
+ // stability comparison, so sibling allocation cannot look like source drift.
+ const names=text(listed).split('\0').filter(name=>name&&!protectedRoot.test(name));
+ const untracked=Buffer.from(names.length?names.join('\0')+'\0':'');
+ return{head:head?line(head):null,branch:branch?line(branch):null,index_sha256:index.sha256??null,tracked,untracked,committed};
+}
+const metadataStamp=m=>digest({...m,tracked:hash(m.tracked),untracked:hash(m.untracked),committed:hash(m.committed)});
+async function observation(cwd,limits,signal){
+ const before=await metadata(cwd,signal),entries=text(before.tracked).split('\0').filter(Boolean).map(line=>{
+  const match=/^(\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([\s\S]+)$/.exec(line);if(!match)throw fail('Unsupported Git index record.');
+  if(match[1]==='160000')throw fail('Submodule identity requires a separate resource contract.');
+  return{path:match[4],mode:match[1],oid:match[2],stage:Number(match[3])};
+ });
+ const others=text(before.untracked).split('\0').filter(Boolean).filter(file=>!protectedRoot.test(file));
+ if(entries.some(e=>protectedRoot.test(e.path)))throw fail('Tracked host state requires a separate resource contract.');
+ const names=[...new Set([...entries.map(e=>e.path),...others])].sort();
+ if(names.length>limits.maxFiles)throw fail('Git source exceeds the complete path bound.','GIT_SOURCE_BOUND');
+ const budget={remaining:limits.maxBytes},files=[];
+ for(const name of names){
+  signal.throwIfAborted();
+  if(path.isAbsolute(name)||name.split('/').some(part=>part==='..'||part==='')||name.includes('\0'))throw fail('Noncanonical Git source path.');
+  // Never follow a directory symlink outside the host-bound workspace.
+  const file=path.join(cwd,name);let ancestor=path.dirname(file),parent;
+  for(;;){try{parent=await realpath(ancestor);break;}catch(error){if(error.code!=='ENOENT'||ancestor===cwd)throw error;ancestor=path.dirname(ancestor);}}
+  const relative=path.relative(cwd,parent);if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative))throw fail('Git source parent escapes the workspace.');
+  files.push({path:name,...await fileHash(file,budget,signal,limits.objectFormat)});
+ }
+ const after=await metadata(cwd,signal);if(metadataStamp(before)!==metadataStamp(after))throw fail('Git metadata changed during source observation.','GIT_SOURCE_CHANGED');
+ const committed=text(before.committed).split('\0').filter(Boolean).map(record=>{
+  const match=/^(\d{6}) (blob|commit) ([a-f0-9]{40}|[a-f0-9]{64})\t([\s\S]+)$/.exec(record);if(!match||match[1]==='160000')throw fail('Unsupported committed resource (submodule or tree record).');
+  return{path:match[4],mode:match[1],oid:match[3],stage:0};
+ });
+ const indexDiffers=digest(entries)!==digest(committed),byPath=new Map(files.map(file=>[file.path,file]));
+ const rawDiffers=entries.some(entry=>{
+  const file=byPath.get(entry.path);return entry.stage!==0||file?.blob_oid!==entry.oid||entry.mode==='120000'&&file.kind!=='symlink'||entry.mode!=='120000'&&(file.kind!=='file'||file.executable!==(entry.mode==='100755'));
+ });
+ return{head:before.head,branch:before.branch,index_sha256:before.index_sha256,dirty:indexDiffers||rawDiffers||others.length>0,index_differs_from_head:indexDiffers,raw_worktree_differs_from_index:rawDiffers,untracked_count:others.length,git_status:'not_run; raw bytes compared without project filters or newline conversion',index_entries:entries,files};
+}
+
+export async function inspectGitSource({cwd,signal,maxFiles=2000,maxBytes=64*1024*1024,timeoutMs=15000,afterObservation}={}){
+ const deadline=AbortSignal.timeout(timeoutMs),abort=signal?AbortSignal.any([signal,deadline]):deadline;
+ abort.throwIfAborted();const canonical=await realpath(cwd);
+ const root=await realpath(line(await git(canonical,['rev-parse','--show-toplevel'],abort)));
+ if(root!==canonical)throw fail('GitInspect requires the repository root as the Comal workspace; parent source was not inspected.');
+ const common=await realpath(line(await git(root,['rev-parse','--path-format=absolute','--git-common-dir'],abort))),format=line(await git(root,['rev-parse','--show-object-format'],abort));
+ if(!['sha1','sha256'].includes(format))throw fail('Unsupported Git object format.');
+ const limits={maxFiles,maxBytes,objectFormat:format},first=await observation(root,limits,abort);
+ await afterObservation?.(immutable(structuredClone(first)));abort.throwIfAborted();
+ const second=await observation(root,limits,abort);
+ if(digest(first)!==digest(second))throw fail('Git source did not remain stable across two complete observations.','GIT_SOURCE_CHANGED');
+ const repository={root,common_directory:common,object_format:format},identity=digest({repository,source:second});
+ return{repository,repository_id:digest({common_directory:common,object_format:format}),source_identity:identity,observation:'stable_double_read_not_atomic_snapshot',...second,limits,excluded:'ignored untracked files, untracked root host state, ignored dependencies and external resources'};
+}
+
+export function registerGitSourceOperations(house){
+ if(house.registry.get('GitInspect'))return;
+ house.registry.add({name:'GitInspect',description:'Read the complete bounded Git source identity at the workspace root: HEAD, index and dirty/untracked bytes. Two stable observations; refuses drift, truncation and unsupported submodules. No shell, hooks, filters, fetch, commit or checkout. Identity is not verification.',input_schema:{type:'object',properties:{},additionalProperties:false},effects:{workspace:'read',external:'none',process:'read',authority:'none'},run:async(_,options)=>{
+  const identity=await inspectGitSource({cwd:options.workspace?.cwd||house.cwd,signal:options.signal});
+  options.observe({kind:'git_source_identity',...identity});
+  const{files,index_entries,...summary}=identity;return JSON.stringify({...summary,paths:files.length,index_entries:index_entries.length});
+ }});
+}