core: resolve the output directory once a pass, not once a file

Checking that a manifest entry stays inside the output directory resolved
the whole directory from the root down, and then resolved the file from the
root down, for every entry. A run of 3000 entries walked the same ancestors
6000 times. On Windows the cost of resolving a path grows with its depth,
about 0.24 ms per component here, so that was most of what verify did.

Measured on 3000 files of 1 kB, same machine, same moment:

  working out paths          12475 ms
  opening and hashing all      626 ms
  the walk and the stats       257 ms
                             -------
  the whole of verify        13358 ms

verify now takes 0.90-1.09 s where it took 16.9-17.3 s from a ten component
path, and 0.50-0.59 s where it took 2.40-2.56 s from a three component one.
cleanup goes through the same code and gets the same saving. Linux was
already fast and is unchanged. No concurrency was added.

What was rejected, and why it matters. The recorded plan was to hash in
parallel, on the reading that the loop already did the minimum so the cost
had to be the operating system opening files. A probe that timed the real
verify beside its own loop showed 869 ms against 17295 ms on the same files
at the same moment, which is how the missing 95% was found. Hashing in
parallel would have addressed 4.7% of the run. It scales 4.75x at eight
threads, so the number exists if the reason ever does.

The first version of this was wrong in a way worth recording. Answering from
the walk below the boundary alone is quick and it is not the rule: a link
inside the output directory pointing at another file inside it has left
nothing, and this tool accepted it before. Refusing it would have been a
change to what the tool accepts, smuggled in as a change to how fast it
answers. The quick reading now only ever answers "inside" - it cannot
wrongly refuse, only wrongly accept - and anything else falls through to the
original reading. Wrongly accepting is what the junction guards already
catch.

Nothing about what verify and cleanup accept or refuse has changed. Only the
boundary is settled once. Every entry still gets its own walk below it,
asked of the filesystem at that moment, so a link planted mid-run is still
caught. Swapping the named directory itself was never caught, before or
after: the old reading resolved both ends through the new link and found
them agreeing.

Four new guards, all proven by mutation. Two of them read the source,
because there is no behaviour to assert on: putting the resolution back
inside the loop, or comparing against the directory as typed rather than its
absolute spelling, both leave every verdict correct and quietly give the
cost back. filepath.Rel refuses a relative path against an absolute one, so
the second mistake would have been slow in the field and green in the suite,
for exactly the people who type "./out" - every other containment guard here
builds its directory with t.TempDir, which is absolute.

The README carried the same wrong reading as advice - it told people the cost
was the antivirus opening each file, and quoted 22 seconds. It is corrected
here rather than left standing, because it was the one place the mistake was
being handed to somebody else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

CHANGELOG.md

@@ -14,6 +14,23 @@ because it turns other people's test suites red.
 
 ## [Unreleased]
 
+### Changed
+
+- `verify` and `cleanup` are much faster over large runs on Windows. Checking
+  that an entry stays inside the output directory used to work the directory
+  out again for every single file, and working it out is expensive on Windows -
+  more so the deeper the directory sits. It is now worked out once per command.
+  Measured on 3000 files of 1 kB: `verify` went from about 17 seconds to about
+  0.9 seconds from a deep path, and from about 2.4 seconds to about 0.5 seconds
+  from a short one. Linux was already fast and is unchanged.
+
+  Nothing about what the two commands accept or refuse has changed. A file that
+  leaves the directory through a link or a junction is still refused, and a
+  directory reached through a link still works.
+
+- The answer in the README about slow runs on Windows said the cost was the
+  antivirus opening each file. That was wrong, and it is corrected.
+
 ## [0.1.0] - 2026-08-20
 
 Initial release.

README.md

@@ -580,17 +580,24 @@ The one link in the whole program is the Donate button in the window, and
 pressing it hands the address to your browser. Your browser makes that
 connection, if you ask for it. The program never opens one.
 
-### Why is a run over thousands of files slow on Windows?
-
-Because something is looking at every file as it is opened, and on Windows that
-is usually the antivirus.
-
-Measured on the same build, same machine, 3000 files of 1 kB: `verify` takes
-about 22 seconds on Windows and about 0.2 seconds on Linux in a container. The
-work is identical, so what differs is the cost of opening a file. If your
-fixtures live somewhere you can add an antivirus exclusion for, that is the
-lever - the files this tool writes are synthesised from a seed and contain
-nothing to scan.
+### Why is a run over thousands of files slower on Windows?
+
+Because Windows charges more for every path it looks at, and a command that
+goes over thousands of files looks at thousands of paths.
+
+Measured on the same machine, 3000 files of 1 kB: `verify` takes about
+0.9 seconds on Windows and about 0.2 seconds on Linux in a container. How deep
+your output directory sits changes the Windows figure - the same 3000 files
+verify in about half that from a short path like `C:\fixtures`, because every
+folder above them is part of what gets looked at.
+
+An earlier version of this answer said the cost was the antivirus scanning
+each file as it was opened, and that `verify` took about 22 seconds. Measuring
+it properly showed the reading was wrong: opening and reading all 3000 files
+was a small part of that time and working out paths was most of it. That has
+been fixed, and the numbers above are what it costs now. If a scanner does
+watch the folder you generate into, an exclusion still helps - the files this
+tool writes are made up from a seed and contain nothing to find.
 
 ### What if I ask for something impossible?
 

internal/audit/audit.go

@@ -108,10 +108,16 @@ func (e *EscapeError) Error() string {
 // the second half of the rule docs/SECURITY.md section 2.4 states: a name from
 // somebody else's file is a name, and where it lands is settled after the links
 // have been followed rather than by reading the string.
-func resolved(dir string, f manifest.File) (string, error) {
-	full := filepath.Join(dir, filepath.FromSlash(f.Path))
-	if core.EscapesAfterResolving(dir, full) {
-		return "", &EscapeError{Dir: dir, Path: f.Path}
+//
+// The boundary is worked out once by the caller and handed in, rather than
+// worked out here from the directory name. Passing it as a value is what makes
+// resolving it per entry impossible to write by accident: there is no directory
+// string in scope to resolve. See core.Boundary for what that is worth in
+// seconds, and observation O117 for the measurement.
+func resolved(b core.Boundary, f manifest.File) (string, error) {
+	full := filepath.Join(b.Dir(), filepath.FromSlash(f.Path))
+	if b.Escapes(full) {
+		return "", &EscapeError{Dir: b.Dir(), Path: f.Path}
 	}
 	return full, nil
 }
@@ -149,6 +155,7 @@ func Claimed(m *manifest.Manifest) []manifest.File {
 // directory is the one answer this must never give.
 func Verify(ctx context.Context, dir string, m *manifest.Manifest, skip string) ([]Difference, error) {
 	claimed := Claimed(m)
+	boundary := core.NewBoundary(dir)
 
 	present, err := walk(dir)
 	if err != nil {
@@ -164,7 +171,7 @@ func Verify(ctx context.Context, dir string, m *manifest.Manifest, skip string)
 		}
 		seen[f.Path] = true
 
-		full, err := resolved(dir, f)
+		full, err := resolved(boundary, f)
 		if err != nil {
 			return nil, err
 		}

internal/audit/cleanup.go

@@ -7,6 +7,7 @@ import (
 	"io/fs"
 	"os"
 
+	"github.com/donislawdev/TestingFilesGenerator/internal/core"
 	"github.com/donislawdev/TestingFilesGenerator/internal/manifest"
 )
 
@@ -59,12 +60,14 @@ func (c Candidate) Removable(force bool) bool {
 // prints this list. A person gets to read what is about to disappear before it
 // does, and CLI.md section 9 rules out asking them interactively.
 func Inspect(ctx context.Context, dir string, m *manifest.Manifest) ([]Candidate, error) {
+	boundary := core.NewBoundary(dir)
+
 	var out []Candidate
 	for _, f := range Claimed(m) {
 		if err := ctx.Err(); err != nil {
 			return out, err
 		}
-		full, err := resolved(dir, f)
+		full, err := resolved(boundary, f)
 		if err != nil {
 			// Nothing is inspected and nothing is offered. A list that points
 			// outside the directory is not a list this tool acts on, and the
@@ -131,6 +134,23 @@ type Outcome struct {
 // was removed stays removed, and the caller reports both halves - there is no
 // undo, so the report is the only record.
 func Remove(ctx context.Context, dir string, cands []Candidate, force bool) ([]Outcome, error) {
+	// This pass works the boundary out for itself rather than taking Inspect's,
+	// which is the same rule as the one below: the two passes are separated by
+	// however long somebody spends reading the preview, and nothing learned
+	// before that pause is carried across it.
+	//
+	// Inside this pass the boundary is settled once. What that does and does not
+	// cover is worth being exact about, because this is the one operation here
+	// that destroys data. Every entry still gets its own walk below the
+	// boundary, asked of the filesystem at the moment that entry is removed - so
+	// a link planted under the directory mid-run is still caught. What is not
+	// re-asked is the directory the person named. Swapping that for a link
+	// halfway through was never caught: the old reading resolved both ends
+	// through the new link and found them agreeing, so it reported "inside" too.
+	// Redirections above the boundary are the caller's own, as the comment on
+	// crossesUnresolvedLink says.
+	boundary := core.NewBoundary(dir)
+
 	var out []Outcome
 	for _, c := range cands {
 		if err := ctx.Err(); err != nil {
@@ -148,7 +168,7 @@ func Remove(ctx context.Context, dir string, cands []Candidate, force bool) ([]O
 		// separated by however long a person spends reading the preview, and
 		// this is the one operation in the tool that destroys data - so the
 		// question is put to the filesystem in the state it is in now.
-		full, err := resolved(dir, manifest.File{Path: c.Path})
+		full, err := resolved(boundary, manifest.File{Path: c.Path})
 		if err != nil {
 			return out, err
 		}

internal/core/filename.go

@@ -96,27 +96,128 @@ func hasVolumeName(p string) bool {
 // paths on purpose, and a workspace that is itself a link has to keep working.
 // The question is only where the path ends up.
 func EscapesAfterResolving(dir, full string) bool {
-	base, err := resolveAsFarAsItExists(dir)
+	return NewBoundary(dir).Escapes(full)
+}
+
+// Boundary is the directory a run was pointed at, with the links on the way
+// followed once instead of once per entry.
+//
+// It exists for speed, and the speed is not a detail. Judging one entry used to
+// resolve the whole directory from the root down, and a run judges thousands of
+// them. Measured on 2026-08-20 with 3000 entries, verify on Windows:
+// resolving the directory again for every entry was 5665 ms of a 13.4 s run,
+// and resolving each file from the root down was another 8703 ms - against
+// 626 ms to actually open and hash all 3000 files. On Windows the cost of
+// filepath.EvalSymlinks grows with the depth of the path, about 0.24 ms per
+// component here, so both numbers are really the same mistake: walking the
+// same ancestors over and over. The full measurement is observation O117.
+//
+// What it does NOT cache is the part that does the work. Every entry still gets
+// its own walk below the boundary, asking the filesystem in the state it is in
+// at that moment - see crossesUnresolvedLink. Only the boundary itself is
+// settled once, and that is the directory the person named, whose own
+// redirections are their business rather than ours.
+type Boundary struct {
+	named    string
+	abs      string
+	resolved string
+	known    bool
+}
+
+// NewBoundary follows the links on the way to dir, once.
+//
+// The absolute spelling is kept beside the name because filepath.Rel refuses to
+// compare a relative path against an absolute one, and the directory arrives
+// however the person typed it - "tfg verify ./tfg-out/manifest.json" is the
+// ordinary way to run this. Without it the cheap comparison in Escapes would
+// fail for exactly the people who type the shorter thing, fall back to the
+// expensive reading, and be slow in the field while every guard here stayed
+// green: they all build their directories with t.TempDir, which is absolute.
+func NewBoundary(dir string) Boundary {
+	b := Boundary{named: dir, abs: dir}
+	if abs, err := filepath.Abs(dir); err == nil {
+		b.abs = abs
+	}
+	r, err := resolveAsFarAsItExists(dir)
 	if err != nil {
 		// Nothing could be resolved, so nothing can be judged. Saying "it
 		// escapes" would refuse an ordinary run on a path we simply could not
 		// examine, and the caller checks the text separately.
+		return b
+	}
+	b.resolved, b.known = r, true
+	return b
+}
+
+// Dir is the directory as the caller named it, before any link was followed.
+func (b Boundary) Dir() string { return b.named }
+
+// Escapes reports whether full lands outside this boundary once the links on
+// the way have been followed.
+//
+// It gives the same answer as resolving both ends, in every case. The saving is
+// not a different rule, it is the same rule reached without walking the
+// ancestors again, and it only applies to the case where nothing redirects at
+// all - which is every ordinary run.
+//
+// The reasoning, because getting it wrong here is a containment bug. When a
+// path is written inside the directory we were given and no step below that
+// directory redirects anywhere, the path as written IS the real path: the
+// ancestors resolve to the boundary we already resolved, and the steps below it
+// resolve to themselves. So it is inside, and resolving it could not have said
+// otherwise.
+//
+// The moment a step below the boundary does redirect, that shortcut stops
+// holding and the thorough reading decides. It has to, and this was nearly got
+// wrong: a link inside the directory that points at another file inside the
+// same directory is NOT an escape, and the old reading allows it - it follows
+// the link, lands inside, and says so. Refusing it here because a link was
+// seen would turn a contained directory into a hard refusal, which is a change
+// to what this tool accepts rather than a change to how fast it answers.
+func (b Boundary) Escapes(full string) bool {
+	if !b.known {
+		return false
+	}
+	target, err := filepath.Abs(full)
+	if err != nil {
 		return false
 	}
+	// Written inside the directory we were given, and nothing below that
+	// directory redirects anywhere. Then the path as written is the real path,
+	// and resolving it from the root down could not have said otherwise.
+	if rel, err := filepath.Rel(b.abs, target); err == nil && !climbsOut(rel) && !crossesUnresolvedLink(b.resolved, rel) {
+		return false
+	}
+	// Anything else is a question rather than an answer, and the thorough
+	// reading is what answers it. A path written outside the name can still be
+	// inside once the links are followed, and a redirection below the boundary
+	// can point either way.
+	return b.escapesTheThoroughWay(full)
+}
+
+// escapesTheThoroughWay is the original reading: resolve both ends and compare
+// them. Kept for a full path that was not written inside the directory, where
+// the cheap comparison above has no shared prefix to work from.
+func (b Boundary) escapesTheThoroughWay(full string) bool {
 	target, err := resolveAsFarAsItExists(full)
 	if err != nil {
 		return false
 	}
-	rel, err := filepath.Rel(base, target)
+	rel, err := filepath.Rel(b.resolved, target)
 	if err != nil {
 		// Different volumes have no relative path between them, which is as
 		// far outside as it gets.
 		return true
 	}
-	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+	if climbsOut(rel) {
 		return true
 	}
-	return crossesUnresolvedLink(base, rel)
+	return crossesUnresolvedLink(b.resolved, rel)
+}
+
+// climbsOut reports whether a relative path steps above what it is relative to.
+func climbsOut(rel string) bool {
+	return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
 }
 
 // crossesUnresolvedLink reports whether any step from base down to rel is a