@ornexus/neocortex 4.60.67 → 4.60.68

package/packages/client/dist/commands/refactor-characterization.js

@@ -1,21 +1,671 @@
-import{spawnSync as G}from"node:child_process";import{createHash as lt,randomBytes as dt}from"node:crypto";import{closeSync as Q,constants as R,existsSync as C,fsyncSync as K,lstatSync as $,mkdirSync as Z,mkdtempSync as ut,openSync as tt,readFileSync as H,realpathSync as W,rmSync as pt,writeFileSync as z}from"node:fs";import{tmpdir as ht}from"node:os";import{basename as mt,dirname as N,join as y,resolve as wt}from"node:path";import{mutationQaGit as et}from"./mutation-qa-git.js";import{exactCommittedRefactorFile as vt,privateRefactorDirectory as rt,readPrivateRefactorAdmission as yt,verifyRootRefactorForCharacterization as ot}from"./refactor-root.js";const A=/^[a-f0-9]{64}$/,gt=64*1024*1024,st=32,nt=128;function bt(e){const t=e.match(/^(\d+)\.(\d+)\.(\d+)$/);if(!t)return!1;const r=Number(t[1]),n=Number(t[2]);return r>22||r===22&&n>=6}function St(){return bt(process.versions.node)&&process.config.variables.node_use_amaro===!0}function b(e){return lt("sha256").update(e).digest("hex")}function D(e){return e.length>0&&e.length<=512&&/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(e)&&e.split("/").every(t=>t!=="."&&t!==".."&&![".git",".neocortex","node_modules"].includes(t.toLowerCase()))}function V(e){return[...e].sort((t,r)=>Buffer.from(t).compare(Buffer.from(r)))}function Et(e,t,r){if(!t.endsWith(".js")&&!t.endsWith(".ts"))return;let n=N(t);for(;;){const f=n==="."?"package.json":`${n}/package.json`;if(C(y(e,f))){if(!r.includes(f))throw new Error("refactor-root-tests-manifest-unbound");let s;try{s=JSON.parse(L(e,f).toString("utf8"))}catch{throw new Error("refactor-root-tests-manifest-invalid")}if(!s||typeof s!="object"||Array.isArray(s)||!["module","commonjs"].includes(s.type)||t.endsWith(".ts")&&s.type!=="module")throw new Error("refactor-root-tests-manifest-invalid");return}if(n===".")break;n=N(n)}throw new Error("refactor-root-tests-manifest-missing")}function L(e,t){if(!D(t))throw new Error("refactor-root-tests-path-invalid");const r=y(e,t),n=$(r);if(W(r)!==r||!n.isFile()||n.isSymbolicLink()||n.size<1||n.size>8*1024*1024)throw new Error("refactor-root-tests-source-unverified");const f=H(r);if(f.length<1||f.length>8*1024*1024||f.includes(0))throw new Error("refactor-root-tests-source-unverified");return new TextDecoder("utf-8",{fatal:!0}).decode(f),f}function q(e,t){if(!A.test(t))throw new Error("refactor-root-baseline-invalid");return y(rt(e),`characterization-baseline-${t}.json`)}function Y(e,t){const r=$(q(e,t));if(!r.isFile()||r.isSymbolicLink()||r.uid!==process.getuid?.()||(r.mode&63)!==0||r.size<100||r.size>64*1024)throw new Error("refactor-root-baseline-invalid");const n=H(q(e,t));if(n.length>64*1024)throw new Error("refactor-root-baseline-invalid");let f;try{f=JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(n))}catch{throw new Error("refactor-root-baseline-invalid")}if(!f||typeof f!="object"||Array.isArray(f))throw new Error("refactor-root-baseline-invalid");const s=f,a=["schemaVersion","kind","admissionSha256","sourceHead","testFiles","dependencies","causalPath","candidateSha256","outputSha256","causalOutputSha256","baselineSha256"],l=o=>Array.isArray(o)&&o.every(p=>p&&typeof p=="object"&&!Array.isArray(p)&&Object.keys(p).sort().join("\0")==="path\0sha256"&&typeof p.path=="string"&&typeof p.sha256=="string"&&D(p.path)&&A.test(p.sha256)),w=s.schemaVersion===2;if(Object.keys(s).sort().join("\0")!==(w?[...a,"runner","toolchainSha256"]:a).sort().join("\0")||s.schemaVersion!==1&&s.schemaVersion!==2||w&&(!["vitest","cpp"].includes(String(s.runner))||!A.test(String(s.toolchainSha256)))||s.kind!=="root-refactor-characterization-baseline"||!A.test(String(s.admissionSha256))||typeof s.sourceHead!="string"||!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(s.sourceHead)||!l(s.testFiles)||!l(s.dependencies)||s.testFiles.length<1||s.testFiles.length>st||s.dependencies.length>nt||typeof s.causalPath!="string"||!D(s.causalPath)||!A.test(String(s.candidateSha256))||!A.test(String(s.outputSha256))||!A.test(String(s.causalOutputSha256))||s.baselineSha256!==t)throw new Error("refactor-root-baseline-invalid");const c=s.testFiles,d=s.dependencies;if(new Set([...c,...d].map(o=>o.path)).size!==c.length+d.length||c.map(o=>o.path).join("\0")!==V(c.map(o=>o.path)).join("\0")||d.map(o=>o.path).join("\0")!==V(d.map(o=>o.path)).join("\0"))throw new Error("refactor-root-baseline-invalid");const{baselineSha256:i,...u}=s;if(b(JSON.stringify(u))!==t||!n.equals(Buffer.from(`${JSON.stringify(s)}
-`)))throw new Error("refactor-root-baseline-invalid");return s}function kt(e,t){const r=b(JSON.stringify(t)),n=q(e,r),f={...t,baselineSha256:r},s=Buffer.from(`${JSON.stringify(f)}
-`);if(C(n))Y(e,r);else{const a=tt(n,R.O_WRONLY|R.O_CREAT|R.O_EXCL|(R.O_NOFOLLOW??0),384);try{z(a,s),K(a)}finally{Q(a)}const l=tt(rt(e),R.O_RDONLY|(R.O_DIRECTORY??0));try{K(l)}finally{Q(l)}}return Y(e,r),r}function it(e){return[...e.files.map(t=>t.path),...e.schemaVersion===2?e.newFiles.map(t=>t.path):[]]}function at(e,t,r,n=[]){const f=new Map;let s=0;for(const l of[...it(t),...r]){if(n.includes(l)){try{$(y(e,l))}catch(c){if(c.code==="ENOENT")continue;throw c}throw new Error("refactor-root-tests-source-stale")}const w=L(e,l);if(s+=w.length,s>gt)throw new Error("refactor-root-tests-snapshot-too-large");f.set(l,w)}const a=b(JSON.stringify([...[...f].map(([l,w])=>[l,b(w)]),...n.map(l=>[l,null])]));return{files:f,candidateSha256:a}}function ct(){try{const e=W("/usr/bin/g++"),t=$(e);if(!e.startsWith("/usr/")||!/^[A-Za-z0-9_./+-]+$/.test(e)||!t.isFile()||t.uid!==0||(t.mode&18)!==0||t.size<1||t.size>32*1024*1024)throw new Error("invalid compiler");const r=G(e,["-dumpfullversion","-dumpversion"],{env:{PATH:"/usr/bin:/bin"},encoding:"utf8",timeout:1e4,maxBuffer:4096}),n=r.stdout?.trim();if(r.status!==0||!/^(?:11|12|13|14|15)\.[0-9]+\.[0-9]+$/.test(n))throw new Error("unsupported compiler");return{executable:e,sha256:b(JSON.stringify([e,n,b(H(e))]))}}catch{throw new Error("refactor-root-tests-toolchain-unverified")}}function Ot(e,t,r){let n="";for(const M of t){let J=N(M),F="";for(;;){const I=J==="."?"package.json":`${J}/package.json`;if(C(y(e,I))){F=I;break}if(J===".")break;J=N(J)}if(!F||n&&F!==n)throw new Error("refactor-root-tests-toolchain-unverified");n=F}if(!r.includes(n)||!r.includes("package-lock.json"))throw new Error("refactor-root-tests-toolchain-unbound");const f=L(e,n),s=L(e,"package-lock.json");let a,l;try{a=JSON.parse(f.toString("utf8")),l=JSON.parse(s.toString("utf8"))}catch{throw new Error("refactor-root-tests-toolchain-unverified")}const w=a.devDependencies?.vitest??a.dependencies?.vitest,c=l.packages,d=n==="package.json"?"":N(n),i=c?.[d],u=i?.devDependencies?.vitest??i?.dependencies?.vitest,o=c?.["node_modules/vitest"]?.version,p=c?.["node_modules/vite"]?.version;if(typeof w!="string"||w.length>80||!/^[\^~]?[0-9]+\.[0-9]+\.[0-9]+$/.test(w)||w!==u||typeof o!="string"||!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(o)||!o.startsWith("3.2.")||typeof p!="string"||!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(p)||!_t(p))throw new Error("refactor-root-tests-toolchain-unverified");const v=W(y(e,"node_modules")),g=$(v);if(mt(v)!=="node_modules"||!g.isDirectory()||g.isSymbolicLink()||g.uid!==process.getuid?.())throw new Error("refactor-root-tests-toolchain-unverified");const h=y(v,"vitest","package.json"),S=y(v,"vitest","vitest.mjs"),O=y(v,"vite","package.json"),E=$(h),_=$(S),B=$(O);if(!E.isFile()||E.isSymbolicLink()||!_.isFile()||_.isSymbolicLink()||!B.isFile()||B.isSymbolicLink()||W(h)!==h||W(S)!==S||W(O)!==O||E.size>64*1024||_.size>1024*1024||B.size>64*1024)throw new Error("refactor-root-tests-toolchain-unverified");const P=H(h),k=H(S),x=H(O);let j,T;try{j=JSON.parse(P.toString("utf8")),T=JSON.parse(x.toString("utf8"))}catch{throw new Error("refactor-root-tests-toolchain-unverified")}if(j.name!=="vitest"||j.version!==o||T.name!=="vite"||T.version!==p)throw new Error("refactor-root-tests-toolchain-unverified");return{nodeModules:v,sha256:b(JSON.stringify([b(f),b(s),b(P),b(k),b(x)]))}}function _t(e){const t=e.match(/^(\d+)\.(\d+)\.(\d+)$/);return!!t&&Number(t[1])<=7&&(Number(t[1])>6||Number(t[1])===6&&Number(t[2])>=1)}function ft(e,t,r,n,f,s,a){if(r==="python"){const c=N(t[0]),d=V([...e.keys()].filter(i=>(c==="."||i.startsWith(`${c}/`))&&/(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(i)));if(JSON.stringify(d)!==JSON.stringify(t))throw new Error("refactor-root-tests-path-invalid")}const l=W(r==="cpp"?"/usr/bin/dash":r==="python"?"/usr/bin/python3":process.execPath);if(r==="node-typescript"&&!St())throw new Error("refactor-root-tests-toolchain-unavailable");if(process.platform!=="linux"||!C("/usr/bin/bwrap")||!$("/usr/bin/bwrap").isFile()||!(l.startsWith("/usr/")||l.startsWith("/home/linuxbrew/.linuxbrew/")))throw new Error("refactor-root-tests-sandbox-unavailable");const w=ut(y(ht(),"p222-refactor-characterization-"));try{const c=y(w,"work");Z(c,{mode:448});for(const[h,S]of e){const O=y(c,h);Z(N(O),{recursive:!0,mode:448}),z(O,S,{mode:384,flag:"wx"})}if(r==="vitest"){if(!f)throw new Error("refactor-root-tests-toolchain-unavailable");Z(y(c,"node_modules"),{mode:448}),z(y(c,"p222-vitest.config.mjs"),`export default ${JSON.stringify({test:{include:t,environment:"node",silent:!0,passWithNoTests:!1,watch:!1,maxWorkers:1,fileParallelism:!1,pool:"forks",coverage:{enabled:!1}}})};
-`,{mode:384,flag:"wx"})}if(r==="cpp"){if(!s||!a||!e.has(a))throw new Error("refactor-root-tests-toolchain-unavailable");const h=s.executable,S=V([...e.keys()].filter(E=>E.endsWith(".cpp")&&E!==a&&!t.includes(E))).map(E=>`'/work/${E}'`);n&&z(y(c,"p222-cpp-causal.cpp"),`#include <cstdio>
-#include <cstdlib>
-extern "C" void __cyg_profile_func_enter(void*,void*) { std::fputs(${JSON.stringify(n+`
-`)},stderr); std::_Exit(86); }
-extern "C" void __cyg_profile_func_exit(void*,void*) {}
-`,{mode:384,flag:"wx"});const O=["set -eu","ulimit -c 0",`'${h}' -std=c++17 -O0 -UNDEBUG -I/work ${n?"-finstrument-functions -finstrument-functions-exclude-file-list=/usr/include ":""}-c '/work/${a}' -o /tmp/p222-cpp-causal.o`,...t.flatMap((E,_)=>[`'${h}' -std=c++17 -O0 -UNDEBUG -I/work '/work/${E}' ${S.join(" ")} /tmp/p222-cpp-causal.o ${n?"/work/p222-cpp-causal.cpp ":""}-o /tmp/p222-cpp-test-${_}`,`/tmp/p222-cpp-test-${_}`,`printf 'P222_CPP_TEST_PASSED_${_}\\n'`])].join(`
-`)+`
-`;z(y(c,"p222-cpp-runner.sh"),O,{mode:384,flag:"wx"})}const d=y(w,"etc");Z(d,{mode:448}),z(y(d,"passwd"),`nobody:x:65534:65534:nobody:/tmp:/bin/sh
-`,{mode:384}),z(y(d,"group"),`nogroup:x:65534:
-`,{mode:384}),z(y(d,"hosts"),`127.0.0.1 localhost
-`,{mode:384}),z(y(d,"nsswitch.conf"),`hosts: files
-`,{mode:384});const i=["--die-with-parent","--new-session","--unshare-all","--clearenv","--setenv","HOME","/tmp","--setenv","TMPDIR","/tmp","--setenv","PATH","/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin","--setenv","CI","true","--ro-bind","/usr","/usr"];r==="python"&&i.push("--setenv","PYTHONPATH","/work");for(const h of["/lib","/lib64","/bin"])C(h)&&i.push("--ro-bind",h,h);C("/home/linuxbrew/.linuxbrew")&&i.push("--ro-bind","/home/linuxbrew/.linuxbrew","/home/linuxbrew/.linuxbrew"),i.push("--dir","/etc");for(const h of["passwd","group","hosts","nsswitch.conf"])i.push("--ro-bind",y(d,h),`/etc/${h}`);i.push("--dev","/dev","--proc","/proc","--tmpfs","/tmp","--ro-bind",c,"/work"),r==="vitest"&&i.push("--ro-bind",f.nodeModules,"/work/node_modules"),i.push("--chdir","/work","--",l),r==="cpp"?i.push("/work/p222-cpp-runner.sh"):r==="python"?i.push("-B","-S","-m","unittest","discover","-s",N(t[0]),"-p","test_*.py"):r==="vitest"?i.push("/work/node_modules/vitest/vitest.mjs","run","--root","/work","--config","/work/p222-vitest.config.mjs","--configLoader=runner","--reporter=json","--no-cache","--no-file-parallelism","--maxWorkers=1"):(r==="node-typescript"&&i.push("--experimental-strip-types"),i.push("--test","--test-reporter=tap",...t));const u=G("/usr/bin/bwrap",i,{env:{PATH:"/usr/bin:/bin"},encoding:"buffer",timeout:18e4,maxBuffer:4*1024*1024});if(u.error||u.signal||u.status===null)throw new Error("refactor-root-tests-sandbox-unavailable");const o=Buffer.concat([u.stdout??Buffer.alloc(0),u.stderr??Buffer.alloc(0)]),p=r!=="python"||/^Ran [1-9][0-9]* tests? in /m.test(o.toString("utf8"));let v=!0;if(r==="vitest")try{const h=JSON.parse((u.stdout??Buffer.alloc(0)).toString("utf8"));v=Number.isSafeInteger(h.numPassedTests)&&Number(h.numPassedTests)>0&&h.numTotalTests===h.numPassedTests&&h.numFailedTests===0}catch{v=!1}const g=r!=="cpp"||t.every((h,S)=>o.toString("utf8").split(`
-`).includes(`P222_CPP_TEST_PASSED_${S}`));return{passed:u.status===0&&p&&v&&g,outputSha256:b(o),canaryObserved:n!==void 0&&(r==="cpp"?o.toString("utf8").split(`
-`).includes(n):o.includes(Buffer.from(n)))}}finally{pt(w,{recursive:!0,force:!0})}}function xt(e,t,r,n,f,s,a,l,w="native"){if(!s)throw new Error("refactor-root-run-authorization-required");if(r.length<1||r.length>st||n.length>nt||!["native","vitest","cpp"].includes(w)||f==="baseline"&&l!==void 0||f==="after"&&(!l||!A.test(l)))throw new Error("refactor-root-tests-arguments-invalid");const c=V(r),d=V(n),i=w==="cpp"?"cpp":w==="vitest"?"vitest":c.every(o=>/(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(o))&&a.endsWith(".py")?"python":c.every(o=>o.endsWith(".test.ts"))&&a.endsWith(".ts")?"node-typescript":"node";if(new Set([...c,...d]).size!==c.length+d.length||c.some(o=>!D(o)||(i==="cpp"?!o.endsWith(".test.cpp"):i==="python"?!/(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(o)||N(o)!==N(c[0]):i==="vitest"?!/\.test\.(?:ts|js|mjs)$/.test(o):i==="node-typescript"?!o.endsWith(".test.ts"):!/\.test\.(?:mjs|cjs|js)$/.test(o)))||!D(a)||(i==="cpp"?!a.endsWith(".cpp")||a.endsWith(".test.cpp"):i==="python"?!a.endsWith(".py"):i==="vitest"?!/\.(?:ts|js|mjs)$/.test(a)||/\.test\./.test(a):i==="node-typescript"?!a.endsWith(".ts")||a.endsWith(".test.ts"):!/\.(?:mjs|cjs|js)$/.test(a))||d.some(o=>!D(o)||i==="python"&&/(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(o)))throw new Error("refactor-root-tests-path-invalid");const u=wt(e);try{const o=yt(u,t),{pendingDocumentationPaths:p}=ot(u,t),v=new Set(it(o));if(c.some(m=>!v.has(m))||!o.files.some(m=>m.path===a)||c.includes(a)||d.some(m=>v.has(m)))throw new Error("refactor-root-tests-path-invalid");for(const m of[...c,a,...d])Et(u,m,d);for(const m of d)vt(u,m);const g=i==="vitest"?Ot(u,c,d):void 0,h=i==="cpp"?ct():void 0,S=g?.sha256??h?.sha256,O=et(u,["diff","--name-only","-z","--no-ext-diff","--no-textconv"]).toString("utf8").split("\0").filter(m=>m&&!m.startsWith(".neocortex/")),E=et(u,["ls-files","--others","--exclude-standard","-z"]).toString("utf8").split("\0").filter(m=>m&&!m.startsWith(".neocortex/")),_=[...O,...E].filter(m=>!c.includes(m));if(f==="baseline"&&_.length>0||f==="after"&&_.length===0)throw new Error("refactor-root-tests-phase-invalid");const B=c.map(m=>({path:m,sha256:b(L(u,m))})),P=d.map(m=>({path:m,sha256:b(L(u,m))})),k=f==="after"?Y(u,l):null;if(k&&(k.admissionSha256!==t||k.sourceHead!==o.sourceHead||k.causalPath!==a||(k.schemaVersion===2?w!==k.runner||k.toolchainSha256!==S:w!=="native")||JSON.stringify(k.testFiles)!==JSON.stringify(B)||JSON.stringify(k.dependencies)!==JSON.stringify(P)))throw new Error("refactor-root-baseline-stale");const x=at(u,o,d,p);if(k&&b(x.files.get(a))===o.files.find(m=>m.path===a).sha256)throw new Error("refactor-root-tests-phase-invalid");const j=ft(x.files,c,i,void 0,g,h,a);let T=null,M=!1;if(j.passed){const m=`P222_REFACTOR_CAUSAL_${dt(16).toString("hex")}`,X=new Map(x.files);i!=="cpp"&&X.set(a,Buffer.concat([Buffer.from(i==="python"?`raise RuntimeError(${JSON.stringify(m)})
-`:`throw new Error(${JSON.stringify(m)});
-`),x.files.get(a)]));const U=ft(X,c,i,m,g,h,a);T=U.outputSha256,M=!U.passed&&U.canaryObserved}const J=ot(u,t);if(JSON.stringify(J.pendingDocumentationPaths)!==JSON.stringify(p))throw new Error("refactor-root-tests-source-stale");const F=at(u,o,d,p);if(h&&ct().sha256!==h.sha256)throw new Error("refactor-root-tests-toolchain-stale");if(x.candidateSha256!==F.candidateSha256)throw new Error("refactor-root-tests-source-stale");let I=l??null;return f==="baseline"&&j.passed&&M&&T&&(I=kt(u,{...i==="vitest"||i==="cpp"?{schemaVersion:2,runner:i,toolchainSha256:S}:{schemaVersion:1},kind:"root-refactor-characterization-baseline",admissionSha256:t,sourceHead:o.sourceHead,testFiles:B,dependencies:P,causalPath:a,candidateSha256:x.candidateSha256,outputSha256:j.outputSha256,causalOutputSha256:T})),Object.freeze({schemaVersion:1,kind:"root-refactor-characterization-observation",phase:f,admissionSha256:t,baselineSha256:I,candidateSha256:x.candidateSha256,outputSha256:j.outputSha256,causalOutputSha256:T,testFileCount:c.length,dependencyCount:d.length,testsPassedObserved:j.passed,causalFailureObserved:M,qaAccepted:!1,gitCommitAuthorized:!1,publicSafe:!0})}catch(o){throw o instanceof Error&&o.message.startsWith("refactor-root-")?o:new Error("refactor-root-tests-unverified")}}function Wt(e){let t="",r="",n,f="",s=!1,a="",l="native",w="plain";const c=[],d=[];try{if(e[0]!=="characterize")throw new Error("refactor-root-tests-arguments-invalid");for(let o=1;o<e.length;o++){const p=e[o],v=()=>{const g=e[++o];if(!g||g.startsWith("--"))throw new Error("refactor-root-tests-arguments-invalid");return g};if(p==="--project-root"&&!t)t=v();else if(p==="--admission-sha"&&!r)r=v();else if(p==="--baseline-sha"&&!n)n=v();else if(p==="--phase"&&!f){const g=v();if(g!=="baseline"&&g!=="after")throw new Error("refactor-root-tests-arguments-invalid");f=g}else if(p==="--test-path")c.push(v());else if(p==="--dependency")d.push(v());else if(p==="--causal-path"&&!a)a=v();else if(p==="--runner"&&l==="native"){const g=v();if(g!=="vitest"&&g!=="cpp")throw new Error("refactor-root-tests-arguments-invalid");l=g}else if(p==="--authorize-run"&&!s)s=!0;else if(p==="--format"&&w==="plain")w=v();else throw new Error("refactor-root-tests-arguments-invalid")}if(!t||!r||!f||!a||!["plain","json"].includes(w))throw new Error("refactor-root-tests-arguments-invalid");const i=xt(t,r,c,d,f,s,a,n,l),u=i.testsPassedObserved&&i.causalFailureObserved;return process.stdout.write(`${JSON.stringify({ok:u,observation:i})}
-`),u?0:1}catch(i){const u=i instanceof Error&&/^refactor-root-[a-z-]+$/.test(i.message)?i.message:"refactor-root-tests-unverified";return process.stdout.write(`${JSON.stringify({ok:!1,reasonCode:u})}
-`),1}}export{Y as readRootRefactorBaseline,Wt as refactorCharacterizationCliHandler,xt as runRootRefactorCharacterization,St as supportsNativeTypeStrippingRuntime,bt as supportsNativeTypeStrippingVersion};
+/** Root-owned, no-network observation for admitted Node JS/TS, Python or C++ tests. */
+import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { mutationQaGit } from './mutation-qa-git.js';
+import { exactCommittedRefactorFile, privateRefactorDirectory, readPrivateRefactorAdmission, verifyRootRefactorForCharacterization } from './refactor-root.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const MAX_RUN_BYTES = 64 * 1024 * 1024;
+const MAX_TESTS = 32;
+const MAX_DEPENDENCIES = 128;
+/** Node's native type-stripping switch first exists in 22.6.0. */
+export function supportsNativeTypeStrippingVersion(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return major > 22 || (major === 22 && minor >= 6);
+}
+/** Distribution capability is separate from semver; some Node builds disable Amaro. */
+export function supportsNativeTypeStrippingRuntime() {
+    return supportsNativeTypeStrippingVersion(process.versions.node)
+        && process.config.variables.node_use_amaro === true;
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function safePath(path) {
+    return path.length > 0 && path.length <= 512
+        && /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(path)
+        && path.split('/').every((part) => part !== '.' && part !== '..'
+            && !['.git', '.neocortex', 'node_modules'].includes(part.toLowerCase()));
+}
+function ordered(paths) {
+    return [...paths].sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+}
+function requireExplicitJsModuleType(root, path, dependencies) {
+    if (!path.endsWith('.js') && !path.endsWith('.ts'))
+        return;
+    let directory = dirname(path);
+    while (true) {
+        const manifest = directory === '.' ? 'package.json' : `${directory}/package.json`;
+        if (existsSync(join(root, manifest))) {
+            if (!dependencies.includes(manifest))
+                throw new Error('refactor-root-tests-manifest-unbound');
+            let parsed;
+            try {
+                parsed = JSON.parse(physicalBytes(root, manifest).toString('utf8'));
+            }
+            catch {
+                throw new Error('refactor-root-tests-manifest-invalid');
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+                || !['module', 'commonjs'].includes(parsed.type)
+                || (path.endsWith('.ts') && parsed.type !== 'module')) {
+                throw new Error('refactor-root-tests-manifest-invalid');
+            }
+            return;
+        }
+        if (directory === '.')
+            break;
+        directory = dirname(directory);
+    }
+    throw new Error('refactor-root-tests-manifest-missing');
+}
+function physicalBytes(root, path) {
+    if (!safePath(path))
+        throw new Error('refactor-root-tests-path-invalid');
+    const physicalPath = join(root, path);
+    const stat = lstatSync(physicalPath);
+    if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+        || stat.size < 1 || stat.size > 8 * 1024 * 1024) {
+        throw new Error('refactor-root-tests-source-unverified');
+    }
+    const bytes = readFileSync(physicalPath);
+    if (bytes.length < 1 || bytes.length > 8 * 1024 * 1024 || bytes.includes(0)) {
+        throw new Error('refactor-root-tests-source-unverified');
+    }
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    return bytes;
+}
+function baselinePath(root, sha256) {
+    if (!SHA256.test(sha256))
+        throw new Error('refactor-root-baseline-invalid');
+    return join(privateRefactorDirectory(root), `characterization-baseline-${sha256}.json`);
+}
+export function readRootRefactorBaseline(root, sha256) {
+    const stat = lstatSync(baselinePath(root, sha256));
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+        || (stat.mode & 0o077) !== 0 || stat.size < 100 || stat.size > 64 * 1024) {
+        throw new Error('refactor-root-baseline-invalid');
+    }
+    const raw = readFileSync(baselinePath(root, sha256));
+    if (raw.length > 64 * 1024)
+        throw new Error('refactor-root-baseline-invalid');
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new Error('refactor-root-baseline-invalid');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('refactor-root-baseline-invalid');
+    }
+    const value = parsed;
+    const keys = ['schemaVersion', 'kind', 'admissionSha256', 'sourceHead', 'testFiles',
+        'dependencies', 'causalPath', 'candidateSha256', 'outputSha256',
+        'causalOutputSha256', 'baselineSha256'];
+    const filesValid = (files) => Array.isArray(files)
+        && files.every((file) => file && typeof file === 'object' && !Array.isArray(file)
+            && Object.keys(file).sort().join('\0') === 'path\0sha256'
+            && typeof file.path === 'string'
+            && typeof file.sha256 === 'string'
+            && safePath(file.path) && SHA256.test(file.sha256));
+    const boundRunner = value.schemaVersion === 2;
+    if (Object.keys(value).sort().join('\0') !== (boundRunner
+        ? [...keys, 'runner', 'toolchainSha256'] : keys).sort().join('\0')
+        || (value.schemaVersion !== 1 && value.schemaVersion !== 2)
+        || (boundRunner && (!['vitest', 'cpp'].includes(String(value.runner)) || !SHA256.test(String(value.toolchainSha256))))
+        || value.kind !== 'root-refactor-characterization-baseline'
+        || !SHA256.test(String(value.admissionSha256))
+        || typeof value.sourceHead !== 'string' || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(value.sourceHead)
+        || !filesValid(value.testFiles) || !filesValid(value.dependencies)
+        || value.testFiles.length < 1 || value.testFiles.length > MAX_TESTS
+        || value.dependencies.length > MAX_DEPENDENCIES
+        || typeof value.causalPath !== 'string' || !safePath(value.causalPath)
+        || !SHA256.test(String(value.candidateSha256)) || !SHA256.test(String(value.outputSha256))
+        || !SHA256.test(String(value.causalOutputSha256))
+        || value.baselineSha256 !== sha256)
+        throw new Error('refactor-root-baseline-invalid');
+    const tests = value.testFiles;
+    const dependencies = value.dependencies;
+    if (new Set([...tests, ...dependencies].map((file) => file.path)).size
+        !== tests.length + dependencies.length
+        || tests.map((file) => file.path).join('\0') !== ordered(tests.map((file) => file.path)).join('\0')
+        || dependencies.map((file) => file.path).join('\0')
+            !== ordered(dependencies.map((file) => file.path)).join('\0')) {
+        throw new Error('refactor-root-baseline-invalid');
+    }
+    const { baselineSha256: _digest, ...body } = value;
+    if (digest(JSON.stringify(body)) !== sha256
+        || !raw.equals(Buffer.from(`${JSON.stringify(value)}\n`))) {
+        throw new Error('refactor-root-baseline-invalid');
+    }
+    return value;
+}
+function persistBaseline(root, body) {
+    const baselineSha256 = digest(JSON.stringify(body));
+    const path = baselinePath(root, baselineSha256);
+    const record = { ...body, baselineSha256 };
+    const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+    if (existsSync(path)) {
+        readRootRefactorBaseline(root, baselineSha256);
+    }
+    else {
+        const handle = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+            | (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            writeFileSync(handle, bytes);
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+        const directoryHandle = openSync(privateRefactorDirectory(root), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+        try {
+            fsyncSync(directoryHandle);
+        }
+        finally {
+            closeSync(directoryHandle);
+        }
+    }
+    readRootRefactorBaseline(root, baselineSha256);
+    return baselineSha256;
+}
+function admittedPaths(record) {
+    return [...record.files.map((file) => file.path),
+        ...(record.schemaVersion === 2 ? record.newFiles.map((file) => file.path) : [])];
+}
+function snapshot(root, record, dependencies, pendingDocumentationPaths = []) {
+    const files = new Map();
+    let totalBytes = 0;
+    for (const path of [...admittedPaths(record), ...dependencies]) {
+        if (pendingDocumentationPaths.includes(path)) {
+            try {
+                lstatSync(join(root, path));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            throw new Error('refactor-root-tests-source-stale');
+        }
+        const bytes = physicalBytes(root, path);
+        totalBytes += bytes.length;
+        if (totalBytes > MAX_RUN_BYTES)
+            throw new Error('refactor-root-tests-snapshot-too-large');
+        files.set(path, bytes);
+    }
+    const candidateSha256 = digest(JSON.stringify([
+        ...[...files].map(([path, bytes]) => [path, digest(bytes)]),
+        ...pendingDocumentationPaths.map(path => [path, null]),
+    ]));
+    return { files, candidateSha256 };
+}
+function exactCppToolchain() {
+    try {
+        const executable = realpathSync('/usr/bin/g++');
+        const stat = lstatSync(executable);
+        if (!executable.startsWith('/usr/') || !/^[A-Za-z0-9_./+-]+$/.test(executable)
+            || !stat.isFile() || stat.uid !== 0 || (stat.mode & 0o022) !== 0
+            || stat.size < 1 || stat.size > 32 * 1024 * 1024)
+            throw new Error('invalid compiler');
+        const result = spawnSync(executable, ['-dumpfullversion', '-dumpversion'], {
+            env: { PATH: '/usr/bin:/bin' }, encoding: 'utf8', timeout: 10_000, maxBuffer: 4096,
+        });
+        const version = result.stdout?.trim();
+        if (result.status !== 0 || !/^(?:11|12|13|14|15)\.[0-9]+\.[0-9]+$/.test(version)) {
+            throw new Error('unsupported compiler');
+        }
+        return { executable, sha256: digest(JSON.stringify([executable, version,
+                digest(readFileSync(executable))])) };
+    }
+    catch {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+}
+/** Bind an installed runner to the committed manifest and lock, never run npm or project scripts. */
+function exactVitestToolchain(root, tests, dependencies) {
+    let packagePath = '';
+    for (const test of tests) {
+        let directory = dirname(test);
+        let nearest = '';
+        while (true) {
+            const candidate = directory === '.' ? 'package.json' : `${directory}/package.json`;
+            if (existsSync(join(root, candidate))) {
+                nearest = candidate;
+                break;
+            }
+            if (directory === '.')
+                break;
+            directory = dirname(directory);
+        }
+        if (!nearest || packagePath && nearest !== packagePath) {
+            throw new Error('refactor-root-tests-toolchain-unverified');
+        }
+        packagePath = nearest;
+    }
+    if (!dependencies.includes(packagePath) || !dependencies.includes('package-lock.json')) {
+        throw new Error('refactor-root-tests-toolchain-unbound');
+    }
+    const manifestBytes = physicalBytes(root, packagePath);
+    const lockBytes = physicalBytes(root, 'package-lock.json');
+    let manifest;
+    let lock;
+    try {
+        manifest = JSON.parse(manifestBytes.toString('utf8'));
+        lock = JSON.parse(lockBytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    const declared = manifest.devDependencies?.vitest
+        ?? manifest.dependencies?.vitest;
+    const packages = lock.packages;
+    const lockWorkspace = packagePath === 'package.json' ? '' : dirname(packagePath);
+    const lockedPackage = packages?.[lockWorkspace];
+    const lockedRequest = lockedPackage?.devDependencies?.vitest
+        ?? lockedPackage?.dependencies?.vitest;
+    const lockedVersion = packages?.['node_modules/vitest']?.version;
+    const lockedViteVersion = packages?.['node_modules/vite']?.version;
+    if (typeof declared !== 'string' || declared.length > 80 || !/^[\^~]?[0-9]+\.[0-9]+\.[0-9]+$/.test(declared)
+        || declared !== lockedRequest || typeof lockedVersion !== 'string'
+        || !/^[0-9]+\.[0-9]+\.[0-9]+$/.test(lockedVersion)
+        || !lockedVersion.startsWith('3.2.')
+        || typeof lockedViteVersion !== 'string'
+        || !/^[0-9]+\.[0-9]+\.[0-9]+$/.test(lockedViteVersion)
+        || !supportsViteRunnerLoader(lockedViteVersion)) {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    const nodeModules = realpathSync(join(root, 'node_modules'));
+    const modulesStat = lstatSync(nodeModules);
+    if (basename(nodeModules) !== 'node_modules' || !modulesStat.isDirectory()
+        || modulesStat.isSymbolicLink() || modulesStat.uid !== process.getuid?.()) {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    const installedPath = join(nodeModules, 'vitest', 'package.json');
+    const entryPath = join(nodeModules, 'vitest', 'vitest.mjs');
+    const vitePath = join(nodeModules, 'vite', 'package.json');
+    const installedStat = lstatSync(installedPath);
+    const entryStat = lstatSync(entryPath);
+    const viteStat = lstatSync(vitePath);
+    if (!installedStat.isFile() || installedStat.isSymbolicLink()
+        || !entryStat.isFile() || entryStat.isSymbolicLink()
+        || !viteStat.isFile() || viteStat.isSymbolicLink()
+        || realpathSync(installedPath) !== installedPath || realpathSync(entryPath) !== entryPath
+        || realpathSync(vitePath) !== vitePath
+        || installedStat.size > 64 * 1024 || entryStat.size > 1024 * 1024
+        || viteStat.size > 64 * 1024) {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    const installedBytes = readFileSync(installedPath);
+    const entryBytes = readFileSync(entryPath);
+    const viteBytes = readFileSync(vitePath);
+    let installed;
+    let vite;
+    try {
+        installed = JSON.parse(installedBytes.toString('utf8'));
+        vite = JSON.parse(viteBytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    if (installed.name !== 'vitest' || installed.version !== lockedVersion
+        || vite.name !== 'vite' || vite.version !== lockedViteVersion) {
+        throw new Error('refactor-root-tests-toolchain-unverified');
+    }
+    return { nodeModules, sha256: digest(JSON.stringify([
+            digest(manifestBytes), digest(lockBytes), digest(installedBytes), digest(entryBytes),
+            digest(viteBytes),
+        ])) };
+}
+function supportsViteRunnerLoader(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    return !!match && Number(match[1]) <= 7 && (Number(match[1]) > 6
+        || Number(match[1]) === 6 && Number(match[2]) >= 1);
+}
+function sandboxCharacterizationTests(files, tests, runtime, canary, toolchain, cppToolchain, causalPath) {
+    if (runtime === 'python') {
+        const directory = dirname(tests[0]);
+        const discoverable = ordered([...files.keys()].filter((path) => (directory === '.' || path.startsWith(`${directory}/`))
+            && /(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(path)));
+        if (JSON.stringify(discoverable) !== JSON.stringify(tests)) {
+            throw new Error('refactor-root-tests-path-invalid');
+        }
+    }
+    const executable = realpathSync(runtime === 'cpp' ? '/usr/bin/dash'
+        : runtime === 'python' ? '/usr/bin/python3' : process.execPath);
+    if (runtime === 'node-typescript' && !supportsNativeTypeStrippingRuntime()) {
+        throw new Error('refactor-root-tests-toolchain-unavailable');
+    }
+    if (process.platform !== 'linux' || !existsSync('/usr/bin/bwrap')
+        || !lstatSync('/usr/bin/bwrap').isFile()
+        || !(executable.startsWith('/usr/') || executable.startsWith('/home/linuxbrew/.linuxbrew/'))) {
+        throw new Error('refactor-root-tests-sandbox-unavailable');
+    }
+    const scratch = mkdtempSync(join(tmpdir(), 'p222-refactor-characterization-'));
+    try {
+        const work = join(scratch, 'work');
+        mkdirSync(work, { mode: 0o700 });
+        for (const [path, bytes] of files) {
+            const target = join(work, path);
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            writeFileSync(target, bytes, { mode: 0o600, flag: 'wx' });
+        }
+        if (runtime === 'vitest') {
+            if (!toolchain)
+                throw new Error('refactor-root-tests-toolchain-unavailable');
+            mkdirSync(join(work, 'node_modules'), { mode: 0o700 });
+            writeFileSync(join(work, 'p222-vitest.config.mjs'), `export default ${JSON.stringify({ test: { include: tests, environment: 'node',
+                    silent: true, passWithNoTests: false, watch: false, maxWorkers: 1,
+                    fileParallelism: false, pool: 'forks', coverage: { enabled: false } } })};\n`, { mode: 0o600, flag: 'wx' });
+        }
+        if (runtime === 'cpp') {
+            if (!cppToolchain || !causalPath || !files.has(causalPath)) {
+                throw new Error('refactor-root-tests-toolchain-unavailable');
+            }
+            const compiler = cppToolchain.executable;
+            const sources = ordered([...files.keys()].filter(path => path.endsWith('.cpp')
+                && path !== causalPath && !tests.includes(path))).map(path => `'/work/${path}'`);
+            if (canary)
+                writeFileSync(join(work, 'p222-cpp-causal.cpp'), '#include <cstdio>\n#include <cstdlib>\n'
+                    + `extern "C" void __cyg_profile_func_enter(void*,void*) { std::fputs(${JSON.stringify(canary + '\n')},stderr); std::_Exit(86); }\n`
+                    + 'extern "C" void __cyg_profile_func_exit(void*,void*) {}\n', { mode: 0o600, flag: 'wx' });
+            const script = ['set -eu', 'ulimit -c 0',
+                `'${compiler}' -std=c++17 -O0 -UNDEBUG -I/work ${canary
+                    ? '-finstrument-functions -finstrument-functions-exclude-file-list=/usr/include ' : ''}`
+                    + `-c '/work/${causalPath}' -o /tmp/p222-cpp-causal.o`,
+                ...tests.flatMap((test, index) => [
+                    `'${compiler}' -std=c++17 -O0 -UNDEBUG -I/work '/work/${test}' ${sources.join(' ')} `
+                        + `/tmp/p222-cpp-causal.o ${canary ? '/work/p222-cpp-causal.cpp ' : ''}-o /tmp/p222-cpp-test-${index}`,
+                    `/tmp/p222-cpp-test-${index}`,
+                    `printf 'P222_CPP_TEST_PASSED_${index}\\n'`,
+                ]),
+            ].join('\n') + '\n';
+            writeFileSync(join(work, 'p222-cpp-runner.sh'), script, { mode: 0o600, flag: 'wx' });
+        }
+        const etc = join(scratch, 'etc');
+        mkdirSync(etc, { mode: 0o700 });
+        writeFileSync(join(etc, 'passwd'), 'nobody:x:65534:65534:nobody:/tmp:/bin/sh\n', { mode: 0o600 });
+        writeFileSync(join(etc, 'group'), 'nogroup:x:65534:\n', { mode: 0o600 });
+        writeFileSync(join(etc, 'hosts'), '127.0.0.1 localhost\n', { mode: 0o600 });
+        writeFileSync(join(etc, 'nsswitch.conf'), 'hosts: files\n', { mode: 0o600 });
+        const args = ['--die-with-parent', '--new-session', '--unshare-all', '--clearenv',
+            '--setenv', 'HOME', '/tmp', '--setenv', 'TMPDIR', '/tmp',
+            '--setenv', 'PATH', '/home/linuxbrew/.linuxbrew/bin:/usr/bin:/bin',
+            '--setenv', 'CI', 'true', '--ro-bind', '/usr', '/usr'];
+        if (runtime === 'python')
+            args.push('--setenv', 'PYTHONPATH', '/work');
+        for (const path of ['/lib', '/lib64', '/bin']) {
+            if (existsSync(path))
+                args.push('--ro-bind', path, path);
+        }
+        if (existsSync('/home/linuxbrew/.linuxbrew')) {
+            args.push('--ro-bind', '/home/linuxbrew/.linuxbrew', '/home/linuxbrew/.linuxbrew');
+        }
+        args.push('--dir', '/etc');
+        for (const file of ['passwd', 'group', 'hosts', 'nsswitch.conf']) {
+            args.push('--ro-bind', join(etc, file), `/etc/${file}`);
+        }
+        args.push('--dev', '/dev', '--proc', '/proc', '--tmpfs', '/tmp', '--ro-bind', work, '/work');
+        if (runtime === 'vitest')
+            args.push('--ro-bind', toolchain.nodeModules, '/work/node_modules');
+        args.push('--chdir', '/work', '--', executable);
+        if (runtime === 'cpp') {
+            args.push('/work/p222-cpp-runner.sh');
+        }
+        else if (runtime === 'python') {
+            // A literal discovery directory and fixed pattern run only the admitted
+            // test files copied into the read-only snapshot. No project runner,
+            // site-packages or shell-controlled command line enters this boundary.
+            args.push('-B', '-S', '-m', 'unittest', 'discover', '-s', dirname(tests[0]), '-p', 'test_*.py');
+        }
+        else if (runtime === 'vitest') {
+            args.push('/work/node_modules/vitest/vitest.mjs', 'run', '--root', '/work', '--config', '/work/p222-vitest.config.mjs', '--configLoader=runner', '--reporter=json', '--no-cache', '--no-file-parallelism', '--maxWorkers=1');
+        }
+        else {
+            if (runtime === 'node-typescript')
+                args.push('--experimental-strip-types');
+            args.push('--test', '--test-reporter=tap', ...tests);
+        }
+        const result = spawnSync('/usr/bin/bwrap', args, {
+            env: { PATH: '/usr/bin:/bin' }, encoding: 'buffer',
+            timeout: 180_000, maxBuffer: 4 * 1024 * 1024,
+        });
+        if (result.error || result.signal || result.status === null) {
+            throw new Error('refactor-root-tests-sandbox-unavailable');
+        }
+        const output = Buffer.concat([result.stdout ?? Buffer.alloc(0), result.stderr ?? Buffer.alloc(0)]);
+        const pythonTestsObserved = runtime !== 'python'
+            || /^Ran [1-9][0-9]* tests? in /m.test(output.toString('utf8'));
+        let vitestTestsObserved = true;
+        if (runtime === 'vitest') {
+            try {
+                const report = JSON.parse((result.stdout ?? Buffer.alloc(0)).toString('utf8'));
+                vitestTestsObserved = Number.isSafeInteger(report.numPassedTests)
+                    && Number(report.numPassedTests) > 0
+                    && report.numTotalTests === report.numPassedTests
+                    && report.numFailedTests === 0;
+            }
+            catch {
+                vitestTestsObserved = false;
+            }
+        }
+        const cppTestsObserved = runtime !== 'cpp' || tests.every((_, index) => output.toString('utf8').split('\n').includes(`P222_CPP_TEST_PASSED_${index}`));
+        return { passed: result.status === 0 && pythonTestsObserved && vitestTestsObserved && cppTestsObserved,
+            outputSha256: digest(output),
+            canaryObserved: canary !== undefined && (runtime === 'cpp'
+                ? output.toString('utf8').split('\n').includes(canary) : output.includes(Buffer.from(canary))) };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+export function runRootRefactorCharacterization(projectRoot, admissionSha256, testPaths, dependencyPaths, phase, authorizeRun, causalPath, baselineSha256, runner = 'native') {
+    if (!authorizeRun)
+        throw new Error('refactor-root-run-authorization-required');
+    if (testPaths.length < 1 || testPaths.length > MAX_TESTS || dependencyPaths.length > MAX_DEPENDENCIES
+        || !['native', 'vitest', 'cpp'].includes(runner)
+        || (phase === 'baseline' && baselineSha256 !== undefined)
+        || (phase === 'after' && (!baselineSha256 || !SHA256.test(baselineSha256)))) {
+        throw new Error('refactor-root-tests-arguments-invalid');
+    }
+    const tests = ordered(testPaths);
+    const dependencies = ordered(dependencyPaths);
+    const runtime = runner === 'cpp' ? 'cpp' : runner === 'vitest' ? 'vitest'
+        : tests.every((path) => /(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(path))
+            && causalPath.endsWith('.py') ? 'python'
+            : tests.every((path) => path.endsWith('.test.ts')) && causalPath.endsWith('.ts')
+                ? 'node-typescript' : 'node';
+    if (new Set([...tests, ...dependencies]).size !== tests.length + dependencies.length
+        || tests.some((path) => !safePath(path) || (runtime === 'cpp' ? !path.endsWith('.test.cpp') : runtime === 'python'
+            ? !/(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(path) || dirname(path) !== dirname(tests[0])
+            : runtime === 'vitest' ? !/\.test\.(?:ts|js|mjs)$/.test(path)
+                : runtime === 'node-typescript' ? !path.endsWith('.test.ts')
+                    : !/\.test\.(?:mjs|cjs|js)$/.test(path)))
+        || !safePath(causalPath) || (runtime === 'cpp'
+        ? !causalPath.endsWith('.cpp') || causalPath.endsWith('.test.cpp') : runtime === 'python'
+        ? !causalPath.endsWith('.py') : runtime === 'vitest'
+        ? !/\.(?:ts|js|mjs)$/.test(causalPath) || /\.test\./.test(causalPath)
+        : runtime === 'node-typescript'
+            ? !causalPath.endsWith('.ts') || causalPath.endsWith('.test.ts')
+            : !/\.(?:mjs|cjs|js)$/.test(causalPath))
+        || dependencies.some((path) => !safePath(path) || runtime === 'python'
+            && /(?:^|\/)test_[A-Za-z0-9_]+\.py$/.test(path))) {
+        throw new Error('refactor-root-tests-path-invalid');
+    }
+    const root = resolve(projectRoot);
+    try {
+        const record = readPrivateRefactorAdmission(root, admissionSha256);
+        const { pendingDocumentationPaths } = verifyRootRefactorForCharacterization(root, admissionSha256);
+        const admitted = new Set(admittedPaths(record));
+        if (tests.some((path) => !admitted.has(path))
+            || !record.files.some((file) => file.path === causalPath)
+            || tests.includes(causalPath)
+            || dependencies.some((path) => admitted.has(path))) {
+            throw new Error('refactor-root-tests-path-invalid');
+        }
+        for (const path of [...tests, causalPath, ...dependencies]) {
+            requireExplicitJsModuleType(root, path, dependencies);
+        }
+        for (const path of dependencies)
+            exactCommittedRefactorFile(root, path);
+        const toolchain = runtime === 'vitest'
+            ? exactVitestToolchain(root, tests, dependencies) : undefined;
+        const cppToolchain = runtime === 'cpp' ? exactCppToolchain() : undefined;
+        const toolchainSha256 = toolchain?.sha256 ?? cppToolchain?.sha256;
+        const changed = mutationQaGit(root, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv'])
+            .toString('utf8').split('\0').filter((path) => path && !path.startsWith('.neocortex/'));
+        const untracked = mutationQaGit(root, ['ls-files', '--others', '--exclude-standard', '-z'])
+            .toString('utf8').split('\0').filter((path) => path && !path.startsWith('.neocortex/'));
+        const changedOutsideTests = [...changed, ...untracked].filter((path) => !tests.includes(path));
+        if ((phase === 'baseline' && changedOutsideTests.length > 0)
+            || (phase === 'after' && changedOutsideTests.length === 0)) {
+            throw new Error('refactor-root-tests-phase-invalid');
+        }
+        const testFiles = tests.map((path) => ({ path, sha256: digest(physicalBytes(root, path)) }));
+        const dependencyFiles = dependencies.map((path) => ({ path, sha256: digest(physicalBytes(root, path)) }));
+        const baseline = phase === 'after' ? readRootRefactorBaseline(root, baselineSha256) : null;
+        if (baseline && (baseline.admissionSha256 !== admissionSha256
+            || baseline.sourceHead !== record.sourceHead
+            || baseline.causalPath !== causalPath
+            || (baseline.schemaVersion === 2 ? runner !== baseline.runner
+                || baseline.toolchainSha256 !== toolchainSha256 : runner !== 'native')
+            || JSON.stringify(baseline.testFiles) !== JSON.stringify(testFiles)
+            || JSON.stringify(baseline.dependencies) !== JSON.stringify(dependencyFiles))) {
+            throw new Error('refactor-root-baseline-stale');
+        }
+        const before = snapshot(root, record, dependencies, pendingDocumentationPaths);
+        if (baseline && digest(before.files.get(causalPath))
+            === record.files.find((file) => file.path === causalPath).sha256) {
+            throw new Error('refactor-root-tests-phase-invalid');
+        }
+        const execution = sandboxCharacterizationTests(before.files, tests, runtime, undefined, toolchain, cppToolchain, causalPath);
+        let causalOutputSha256 = null;
+        let causalFailureObserved = false;
+        if (execution.passed) {
+            const canary = `P222_REFACTOR_CAUSAL_${randomBytes(16).toString('hex')}`;
+            const causalFiles = new Map(before.files);
+            if (runtime !== 'cpp')
+                causalFiles.set(causalPath, Buffer.concat([
+                    Buffer.from(runtime === 'python'
+                        ? `raise RuntimeError(${JSON.stringify(canary)})\n`
+                        : `throw new Error(${JSON.stringify(canary)});\n`),
+                    before.files.get(causalPath),
+                ]));
+            const causal = sandboxCharacterizationTests(causalFiles, tests, runtime, canary, toolchain, cppToolchain, causalPath);
+            causalOutputSha256 = causal.outputSha256;
+            causalFailureObserved = !causal.passed && causal.canaryObserved;
+        }
+        const revalidated = verifyRootRefactorForCharacterization(root, admissionSha256);
+        if (JSON.stringify(revalidated.pendingDocumentationPaths) !== JSON.stringify(pendingDocumentationPaths)) {
+            throw new Error('refactor-root-tests-source-stale');
+        }
+        const after = snapshot(root, record, dependencies, pendingDocumentationPaths);
+        if (cppToolchain && exactCppToolchain().sha256 !== cppToolchain.sha256) {
+            throw new Error('refactor-root-tests-toolchain-stale');
+        }
+        if (before.candidateSha256 !== after.candidateSha256) {
+            throw new Error('refactor-root-tests-source-stale');
+        }
+        let savedBaseline = baselineSha256 ?? null;
+        if (phase === 'baseline' && execution.passed && causalFailureObserved && causalOutputSha256) {
+            savedBaseline = persistBaseline(root, {
+                ...(runtime === 'vitest' || runtime === 'cpp'
+                    ? { schemaVersion: 2, runner: runtime,
+                        toolchainSha256: toolchainSha256 }
+                    : { schemaVersion: 1 }),
+                kind: 'root-refactor-characterization-baseline',
+                admissionSha256, sourceHead: record.sourceHead,
+                testFiles, dependencies: dependencyFiles, causalPath,
+                candidateSha256: before.candidateSha256,
+                outputSha256: execution.outputSha256, causalOutputSha256,
+            });
+        }
+        return Object.freeze({ schemaVersion: 1, kind: 'root-refactor-characterization-observation',
+            phase, admissionSha256, baselineSha256: savedBaseline,
+            candidateSha256: before.candidateSha256, outputSha256: execution.outputSha256,
+            causalOutputSha256,
+            testFileCount: tests.length, dependencyCount: dependencies.length,
+            testsPassedObserved: execution.passed, causalFailureObserved, qaAccepted: false,
+            gitCommitAuthorized: false, publicSafe: true });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-'))
+            throw error;
+        throw new Error('refactor-root-tests-unverified');
+    }
+}
+export function refactorCharacterizationCliHandler(args) {
+    let projectRoot = '';
+    let admissionSha256 = '';
+    let baselineSha256;
+    let phase = '';
+    let authorizeRun = false;
+    let causalPath = '';
+    let runner = 'native';
+    let format = 'plain';
+    const tests = [];
+    const dependencies = [];
+    try {
+        if (args[0] !== 'characterize')
+            throw new Error('refactor-root-tests-arguments-invalid');
+        for (let index = 1; index < args.length; index++) {
+            const token = args[index];
+            const next = () => {
+                const value = args[++index];
+                if (!value || value.startsWith('--'))
+                    throw new Error('refactor-root-tests-arguments-invalid');
+                return value;
+            };
+            if (token === '--project-root' && !projectRoot)
+                projectRoot = next();
+            else if (token === '--admission-sha' && !admissionSha256)
+                admissionSha256 = next();
+            else if (token === '--baseline-sha' && !baselineSha256)
+                baselineSha256 = next();
+            else if (token === '--phase' && !phase) {
+                const value = next();
+                if (value !== 'baseline' && value !== 'after')
+                    throw new Error('refactor-root-tests-arguments-invalid');
+                phase = value;
+            }
+            else if (token === '--test-path')
+                tests.push(next());
+            else if (token === '--dependency')
+                dependencies.push(next());
+            else if (token === '--causal-path' && !causalPath)
+                causalPath = next();
+            else if (token === '--runner' && runner === 'native') {
+                const value = next();
+                if (value !== 'vitest' && value !== 'cpp')
+                    throw new Error('refactor-root-tests-arguments-invalid');
+                runner = value;
+            }
+            else if (token === '--authorize-run' && !authorizeRun)
+                authorizeRun = true;
+            else if (token === '--format' && format === 'plain')
+                format = next();
+            else
+                throw new Error('refactor-root-tests-arguments-invalid');
+        }
+        if (!projectRoot || !admissionSha256 || !phase || !causalPath || !['plain', 'json'].includes(format)) {
+            throw new Error('refactor-root-tests-arguments-invalid');
+        }
+        const observation = runRootRefactorCharacterization(projectRoot, admissionSha256, tests, dependencies, phase, authorizeRun, causalPath, baselineSha256, runner);
+        const ok = observation.testsPassedObserved && observation.causalFailureObserved;
+        process.stdout.write(`${JSON.stringify({ ok, observation })}\n`);
+        return ok ? 0 : 1;
+    }
+    catch (error) {
+        const reasonCode = error instanceof Error && /^refactor-root-[a-z-]+$/.test(error.message)
+            ? error.message : 'refactor-root-tests-unverified';
+        process.stdout.write(`${JSON.stringify({ ok: false, reasonCode })}\n`);
+        return 1;
+    }
+}