@orkestrel/scaffold 0.0.101 → 0.0.103

package/dist/src/server/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
-import { andOf, arrayOf, attempt, boundsOf, compareValues, compileGuard, holds, isArray, isBoolean, isError, isFunction, isInteger, isNumber, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, recordShape, stringOf, stringShape, unionOf, whereOf } from "@orkestrel/contract";
-import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_CLOSING_MARKER, CATALOG_OPENING_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
+import { andOf, arrayOf, attempt, boundsOf, compareValues, compileGuard, holds, isArray, isBoolean, isDefined, isError, isFunction, isInteger, isNonNegativeInteger, isNumber, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, recordShape, stringOf, stringShape, unionOf, whereOf } from "@orkestrel/contract";
+import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_CLOSING_MARKER, CATALOG_OPENING_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeTotal, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, iterateAnswers, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -481,18 +481,61 @@ function isExactCaseFile(path) {
 	if (!isPhysicalFile(full)) return false;
 	const root = parse(full).root;
 	const segments = relative(root, full).split(sep);
-	let parent = root;
-	for (const segment of segments) {
+	return segments.every((segment, index) => {
+		const parent = join(root, ...segments.slice(0, index));
 		const entries = attempt(() => readdirSync(parent));
-		if (entries.success) {
-			if (!entries.value.includes(segment)) return false;
-		} else {
-			const actual = attempt(() => realpathSync.native(join(parent, segment)));
-			if (!actual.success || basename(actual.value) !== segment) return false;
-		}
-		parent = join(parent, segment);
-	}
-	return true;
+		if (entries.success) return entries.value.includes(segment);
+		const actual = attempt(() => realpathSync.native(join(parent, segment)));
+		return actual.success && basename(actual.value) === segment;
+	});
+}
+/**
+* Places each result at the index its entry names, in a fresh array.
+*
+* @param entries - The index and result pairs, in any order; each index a non-negative integer.
+* @returns An array holding each result at its index, whose length is the highest index plus one,
+* and where an index no entry names stays a hole.
+*
+* @remarks
+* A worker pool finishes its items out of order and can skip one, so its answer is merged by
+* position rather than by arrival: each index is written once into a fresh array, which needs no
+* sort and keeps a skipped index absent instead of closing the gap. A repeated index keeps its last
+* result.
+*
+* @example
+* ```ts
+* import { collectIndexed } from '@orkestrel/scaffold/server'
+*
+* collectIndexed([[0, 'first'], [2, 'third']]).length // 3
+* ```
+*/
+function collectIndexed(entries) {
+	return Object.assign([], Object.fromEntries(entries));
+}
+/**
+* Lists a path followed by each directory above it, nearest first.
+*
+* @param path - The host path to climb from.
+* @param limit - The most paths to list; every ancestor by default.
+* @returns The path, then `dirname` of each result in turn, ending at the first path that is its
+* own parent (`.` for a relative path, the filesystem root for an absolute one) or at `limit`.
+*
+* @remarks
+* The climb is derived from the path text alone and reads no filesystem, so a caller bounds a walk
+* by the length it asks for rather than by a counter it reassigns. The final path of an unbounded
+* list is the one `dirname` leaves unchanged.
+*
+* @example
+* ```ts
+* import { listAncestors } from '@orkestrel/scaffold/server'
+*
+* listAncestors('notes/entry/file.md') // ['notes/entry/file.md', 'notes/entry', 'notes', '.']
+* listAncestors('notes/entry/file.md', 2) // ['notes/entry/file.md', 'notes/entry']
+* ```
+*/
+function listAncestors(path, limit = Number.POSITIVE_INFINITY) {
+	const parent = dirname(path);
+	return parent === path || limit <= 1 ? [path] : [path, ...listAncestors(parent, limit - 1)];
 }
 /**
 * Tests whether a path is a physical directory this package will read or write into.
@@ -548,14 +591,15 @@ function computeFileDigest(path) {
 		if (!before.isFile() || before.nlink !== 1 || before.size > MAX_ARTIFACT_BYTES) return void 0;
 		const hash = createHash("sha256");
 		const buffer = Buffer.alloc(65536);
-		let size = 0;
+		const lengths = [];
 		for (;;) {
 			const length = readSync(handle, buffer, 0, buffer.byteLength, null);
 			if (length === 0) break;
-			size += length;
-			if (size > MAX_ARTIFACT_BYTES) return void 0;
+			lengths.push(length);
+			if (computeTotal(lengths) > MAX_ARTIFACT_BYTES) return void 0;
 			hash.update(buffer.subarray(0, length));
 		}
+		const size = computeTotal(lengths);
 		const after = fstatSync(handle);
 		if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs) return;
 		return hash.digest("hex");
@@ -577,8 +621,8 @@ function computeFileDigest(path) {
 * yet, and a lexical answer is not enough: a link anywhere in the existing
 * prefix moves the destination somewhere the text never named. So the deepest
 * existing ancestor is resolved and the remaining segments are re-joined onto
-* it. The climb is bounded by the path-depth ceiling, so an adversarial path
-* cannot make it walk indefinitely.
+* it. {@link climbRealPath} performs the climb and bounds it by the path-depth
+* ceiling, so an adversarial path cannot make it walk indefinitely.
 *
 * The caller's own text is collapsed first, which is what `resolve` does with a
 * `..` the caller wrote: it cancels the segment before it as text, before any
@@ -612,32 +656,50 @@ function computeFileDigest(path) {
 * ```
 */
 function resolveRealPath(path) {
-	if (!isFilesystemPath(path)) return void 0;
-	let current = resolve(path);
-	const pending = [];
-	for (let depth = 0; depth <= 64; depth += 1) {
-		const real = attempt(() => realpathSync(current));
-		if (real.success) {
-			let physical = real.value;
-			for (const segment of pending) physical = join(physical, segment);
-			return physical;
-		}
-		if (!matchesMissingPath(real.error)) return void 0;
-		const status = attempt(() => lstatSync(current));
-		if (status.success) {
-			if (!status.value.isSymbolicLink()) return void 0;
-			const target = attempt(() => readlinkSync(current));
-			if (!target.success) return void 0;
-			if (target.value.split(/[\\/]/u).includes("..")) return void 0;
-			current = resolve(dirname(current), target.value);
-			continue;
-		}
-		if (!matchesMissingPath(status.error)) return void 0;
-		const parent = dirname(current);
-		if (parent === current) return void 0;
-		pending.unshift(relative(parent, current));
-		current = parent;
+	return isFilesystemPath(path) ? climbRealPath(resolve(path), [], 0) : void 0;
+}
+/**
+* Climbs from an absolute path to its deepest existing ancestor and resolves it through every link.
+*
+* @param current - The absolute host path the climb reads at this depth.
+* @param pending - The absent segments already climbed past, outermost first.
+* @param depth - The steps already taken, from 0 through `MAX_PATH_DEPTH`.
+* @returns The real path of the first existing ancestor joined with `pending` and every segment the
+* climb passes, or `undefined` when `depth` is not a safe integer from 0 through `MAX_PATH_DEPTH`,
+* the climb reaches the root, a link target cannot be read or carries a `..` segment, an existing
+* entry is not a link, or an entry cannot be read.
+*
+* @remarks
+* Each step reads one path and moves the climb to one other: a dangling link redirects it to the
+* link's target with the same suffix, and an absent name moves it to the parent with that name added
+* to the suffix. One successor per step makes the climb a bounded recursion rather than a worklist,
+* and the depth argument is its bound, so an adversarial path or a link cycle answers `undefined`
+* after `MAX_PATH_DEPTH` steps instead of walking indefinitely. {@link resolveRealPath} starts the
+* climb at depth 0 with nothing pending.
+*
+* @example
+* ```ts
+* import { resolve } from 'node:path'
+* import { climbRealPath } from '@orkestrel/scaffold/server'
+*
+* climbRealPath(resolve('./packages/new/src'), [], 0) // the real path of packages, plus new/src
+* ```
+*/
+function climbRealPath(current, pending, depth) {
+	if (!Number.isSafeInteger(depth) || depth < 0 || depth > 64) return void 0;
+	const real = attempt(() => realpathSync(current));
+	if (real.success) return pending.length === 0 ? real.value : join(real.value, ...pending);
+	if (!matchesMissingPath(real.error)) return void 0;
+	const status = attempt(() => lstatSync(current));
+	if (status.success) {
+		if (!status.value.isSymbolicLink()) return void 0;
+		const target = attempt(() => readlinkSync(current));
+		if (!target.success || target.value.split(/[\\/]/u).includes("..")) return void 0;
+		return climbRealPath(resolve(dirname(current), target.value), pending, depth + 1);
 	}
+	if (!matchesMissingPath(status.error)) return void 0;
+	const parent = dirname(current);
+	return parent === current ? void 0 : climbRealPath(parent, [relative(parent, current), ...pending], depth + 1);
 }
 /**
 * Resolves a root-relative path and refuses one that leaves its root.
@@ -764,13 +826,12 @@ function listFiles(root) {
 		});
 	}
 	if (!status.value.isDirectory() || status.value.isSymbolicLink()) throw new ScaffoldError("TARGET", `Listing root is not a physical directory at ${root}`, { root });
-	const files = [];
 	const pending = [{
 		full: root,
 		path: "",
 		depth: 0
 	}];
-	let visited = 0;
+	const entries = [];
 	while (pending.length > 0) {
 		const current = pending.pop();
 		if (current === void 0) break;
@@ -785,20 +846,21 @@ function listFiles(root) {
 			for (;;) {
 				const entry = handle.readSync();
 				if (entry === null) break;
-				visited += 1;
-				if (visited > 1e5) throw new ScaffoldError("TARGET", "Listing exceeds the paths one inventory may report", {
+				const path = current.path === "" ? entry.name : `${current.path}/${entry.name}`;
+				const file = !entry.isDirectory() || entry.isSymbolicLink();
+				entries.push({
+					path,
+					file
+				});
+				if (entries.length > 1e5) throw new ScaffoldError("TARGET", "Listing exceeds the paths one inventory may report", {
 					root,
 					limit: MAX_INVENTORY_PATHS
 				});
-				const path = current.path === "" ? entry.name : `${current.path}/${entry.name}`;
 				if (!isPath(path)) throw new ScaffoldError("TARGET", `Listing found a path this package cannot plan at ${path}`, {
 					root,
 					path
 				});
-				if (!entry.isDirectory() || entry.isSymbolicLink()) {
-					files.push(path);
-					continue;
-				}
+				if (file) continue;
 				const depth = current.depth + 1;
 				if (depth >= 64) throw new ScaffoldError("TARGET", `Listing exceeds the depth one path may carry at ${path}`, {
 					root,
@@ -815,7 +877,7 @@ function listFiles(root) {
 		attempt(() => handle.closeSync());
 		if (!walked.success) throw walked.error;
 	}
-	return files.sort();
+	return entries.filter(({ file }) => file).map(({ path }) => path).sort();
 }
 /**
 * Lists a directory's descendant directories as sorted root-relative paths.
@@ -857,13 +919,12 @@ function listDirectories(root) {
 		});
 	}
 	if (!status.value.isDirectory() || status.value.isSymbolicLink()) throw new ScaffoldError("TARGET", `Listing root is not a physical directory at ${root}`, { root });
-	const directories = [];
 	const pending = [{
 		full: root,
 		path: "",
 		depth: 0
 	}];
-	let visited = 0;
+	const entries = [];
 	while (pending.length > 0) {
 		const current = pending.pop();
 		if (current === void 0) break;
@@ -878,24 +939,27 @@ function listDirectories(root) {
 			for (;;) {
 				const entry = handle.readSync();
 				if (entry === null) break;
-				visited += 1;
-				if (visited > 1e5) throw new ScaffoldError("TARGET", "Listing exceeds the paths one inventory may report", {
+				const path = current.path === "" ? entry.name : `${current.path}/${entry.name}`;
+				const directory = entry.isDirectory() && !entry.isSymbolicLink();
+				entries.push({
+					path,
+					directory
+				});
+				if (entries.length > 1e5) throw new ScaffoldError("TARGET", "Listing exceeds the paths one inventory may report", {
 					root,
 					limit: MAX_INVENTORY_PATHS
 				});
-				const path = current.path === "" ? entry.name : `${current.path}/${entry.name}`;
 				if (!isPath(path)) throw new ScaffoldError("TARGET", `Listing found a path this package cannot plan at ${path}`, {
 					root,
 					path
 				});
-				if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+				if (!directory) continue;
 				const depth = current.depth + 1;
 				if (depth >= 64) throw new ScaffoldError("TARGET", `Listing exceeds the depth one path may carry at ${path}`, {
 					root,
 					path,
 					limit: 64
 				});
-				directories.push(path);
 				pending.push({
 					full: join(current.full, entry.name),
 					path,
@@ -906,7 +970,7 @@ function listDirectories(root) {
 		attempt(() => handle.closeSync());
 		if (!walked.success) throw walked.error;
 	}
-	return directories.sort();
+	return entries.filter(({ directory }) => directory).map(({ path }) => path).sort();
 }
 /**
 * Lists the canon paths a target holds, filtered to a plan's groups.
@@ -940,14 +1004,12 @@ function listDirectories(root) {
 * ```
 */
 function listCanonPaths(target, groups) {
-	const held = [];
-	for (const member of CANON_PATHS) {
+	return CANON_PATHS.flatMap((member) => {
 		const full = resolveContainedPath(target, member);
-		if (full === void 0) continue;
-		if (isPhysicalFile(full)) held.push(member);
-		else if (isPhysicalDirectory(full)) for (const name of listFiles(full)) held.push(`${member}/${name}`);
-	}
-	return held.filter((path) => groups.includes(inferGroup(path)));
+		if (full === void 0) return [];
+		if (isPhysicalFile(full)) return [member];
+		return isPhysicalDirectory(full) ? listFiles(full).map((name) => `${member}/${name}`) : [];
+	}).filter((path) => groups.includes(inferGroup(path)));
 }
 /**
 * Removes every directory one set of deletions emptied.
@@ -980,24 +1042,13 @@ function listCanonPaths(target, groups) {
 * ```
 */
 function pruneEmptiedDirectories(target, removed) {
-	const candidates = /* @__PURE__ */ new Set();
-	for (const path of removed) {
-		let parent = dirname(path);
-		while (parent !== "." && parent !== dirname(parent) && !candidates.has(parent)) {
-			candidates.add(parent);
-			parent = dirname(parent);
-		}
-	}
-	const ordered = [...candidates].sort((left, right) => compareValues(right.split("/").length, left.split("/").length) || compareValues(left, right));
-	const pruned = [];
-	for (const candidate of ordered) {
+	return [...new Set(Iterator.from(removed).flatMap((path) => listAncestors(path).slice(1, -1)).toArray())].sort((left, right) => compareValues(right.split("/").length, left.split("/").length) || compareValues(left, right)).flatMap((candidate) => {
 		const directory = resolveContainedPath(target, candidate);
-		if (directory === void 0 || !isPhysicalDirectory(directory)) continue;
+		if (directory === void 0 || !isPhysicalDirectory(directory)) return [];
 		const entries = attempt(() => readdirSync(directory));
-		if (!entries.success || entries.value.length > 0) continue;
-		if (attempt(() => rmdirSync(directory)).success) pruned.push(candidate);
-	}
-	return pruned;
+		if (!entries.success || entries.value.length > 0) return [];
+		return attempt(() => rmdirSync(directory)).success ? [candidate] : [];
+	});
 }
 /**
 * Reads one contained file as its exact bytes in lowercase hexadecimal.
@@ -1045,12 +1096,15 @@ function readFileHex(root, path, limit = MAX_ARTIFACT_BYTES) {
 		const before = fstatSync(handle);
 		if (!before.isFile() || before.nlink !== 1 || before.size > limit) return void 0;
 		const bytes = Buffer.alloc(before.size);
-		let offset = 0;
-		while (offset < bytes.byteLength) {
-			const length = readSync(handle, bytes, offset, bytes.byteLength - offset, offset);
+		const reads = [];
+		for (;;) {
+			const position = computeTotal(reads);
+			if (position >= bytes.byteLength) break;
+			const length = readSync(handle, bytes, position, bytes.byteLength - position, position);
 			if (length === 0) break;
-			offset += length;
+			reads.push(length);
 		}
+		const offset = computeTotal(reads);
 		const overflow = readSync(handle, Buffer.alloc(1), 0, 1, offset);
 		const after = fstatSync(handle);
 		if (offset !== bytes.byteLength || overflow !== 0 || after.size !== before.size || after.mtimeMs !== before.mtimeMs) return;
@@ -1122,9 +1176,7 @@ function readSnapshot(target, paths) {
 		target,
 		limit: MAX_COLLECTION_ITEMS
 	});
-	let remaining = MAX_TOTAL_ARTIFACT_BYTES;
-	const snapshot = {};
-	for (const path of paths) {
+	const read = Iterator.from(paths).reduce((state, path) => {
 		const full = resolveContainedPath(target, path);
 		if (full === void 0) throw new ScaffoldError("INVALID", `Snapshot path leaves its target at ${path}`, {
 			target,
@@ -1132,27 +1184,32 @@ function readSnapshot(target, paths) {
 		});
 		const status = attempt(() => lstatSync(full));
 		if (!status.success) {
-			if (matchesMissingPath(status.error)) continue;
+			if (matchesMissingPath(status.error)) return state;
 			throw new ScaffoldError("TARGET", `Snapshot path cannot be inspected at ${path}`, {
 				target,
 				path,
 				error: status.error
 			});
 		}
-		if (isPhysicalDirectory(full)) {
-			snapshot[path] = "";
-			continue;
-		}
-		const hex = readFileHex(target, path, Math.min(MAX_ARTIFACT_BYTES, remaining));
+		if (isPhysicalDirectory(full)) return {
+			...state,
+			entries: [...state.entries, [path, ""]]
+		};
+		const hex = readFileHex(target, path, Math.min(MAX_ARTIFACT_BYTES, MAX_TOTAL_ARTIFACT_BYTES - computeTotal(state.spent)));
 		if (hex === void 0) throw new ScaffoldError("TARGET", `Snapshot path is not a readable file at ${path}`, {
 			target,
 			path,
 			limit: MAX_TOTAL_ARTIFACT_BYTES
 		});
-		remaining -= hex.length / 2;
-		snapshot[path] = hex;
-	}
-	return snapshot;
+		return {
+			entries: [...state.entries, [path, hex]],
+			spent: [...state.spent, hex.length / 2]
+		};
+	}, {
+		entries: [],
+		spent: []
+	});
+	return Object.fromEntries(read.entries);
 }
 /**
 * Reads a vendored host's manifest, when it carries one.
@@ -1236,20 +1293,18 @@ function readHostFloor(root) {
 	if (!isPhysicalDirectory(host)) throw new ScaffoldError("TARGET", `The vendored host root is not readable at ${host}`, { host });
 	const manifest = readHostManifest(host, source ? HOST_INVENTORY_PATH : MANIFEST_NAME);
 	if (manifest === void 0) throw new ScaffoldError("TARGET", `The vendored host carries no manifest at ${host}`, { host });
-	const bytes = {};
-	for (const entry of manifest.entries) {
-		const path = source ? entry.destination : entry.storage;
-		const hex = readFileHex(host, path);
-		if (hex === void 0 || hexToDigest(hex) !== entry.digest) throw new ScaffoldError("TARGET", `The vendored host cannot read the declared file at ${path}`, {
-			host,
-			path,
-			destination: entry.destination
-		});
-		bytes[entry.destination] = hex;
-	}
 	return {
 		manifest,
-		bytes
+		bytes: Object.fromEntries(manifest.entries.map((entry) => {
+			const path = source ? entry.destination : entry.storage;
+			const hex = readFileHex(host, path);
+			if (hex === void 0 || hexToDigest(hex) !== entry.digest) throw new ScaffoldError("TARGET", `The vendored host cannot read the declared file at ${path}`, {
+				host,
+				path,
+				destination: entry.destination
+			});
+			return [entry.destination, hex];
+		}))
 	};
 }
 /**
@@ -1329,24 +1384,21 @@ function readManifestEntry(destination, source) {
 */
 function filesToHost(files, floor) {
 	const declared = new Set(floor.manifest.entries.map((entry) => entry.destination));
-	const held = /* @__PURE__ */ new Map();
-	for (const file of files) {
-		if (file.lookup !== "found" || !declared.has(file.path)) return void 0;
-		if (!isFloorPath(file.path)) held.set(file.path, file.hex);
-	}
-	const entries = [];
-	const bytes = {};
-	for (const entry of floor.manifest.entries) {
+	const rows = [...iterateAnswers(files, (file) => file.lookup !== "found" || !declared.has(file.path) ? void 0 : isFloorPath(file.path) ? [] : [[file.path, file.hex]])];
+	if (!rows.every(isDefined)) return void 0;
+	const held = new Map(rows.flat());
+	const filled = [...iterateAnswers(floor.manifest.entries, (entry) => {
 		const hex = isFloorPath(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
-		if (hex === void 0) return void 0;
-		entries.push({
+		return hex === void 0 ? void 0 : [{
 			storage: entry.storage,
 			destination: entry.destination,
 			executable: entry.executable,
 			digest: hexToDigest(hex)
-		});
-		bytes[entry.destination] = hex;
-	}
+		}, hex];
+	})];
+	if (!filled.every(isDefined)) return void 0;
+	const entries = filled.map(([entry]) => entry);
+	const bytes = Object.fromEntries(filled.map(([entry, hex]) => [entry.destination, hex]));
 	return {
 		manifest: {
 			entries,
@@ -1394,8 +1446,7 @@ function filesToHost(files, floor) {
 function stageBytes(host, root, destinations) {
 	if (!isFilesystemPath(root)) throw new ScaffoldError("INVALID", "Staging host root is not a host path", { host: root });
 	const declared = new Map(host.manifest.entries.map((entry) => [entry.destination, entry]));
-	const staged = [];
-	for (const destination of destinations) {
+	return Iterator.from(destinations).map((destination) => {
 		const entry = declared.get(destination);
 		const hex = host.bytes[destination];
 		if (entry === void 0 || hex === void 0) throw new ScaffoldError("TARGET", `The host carries no bytes for ${destination}`, {
@@ -1425,9 +1476,8 @@ function stageBytes(host, root, destinations) {
 			host: root,
 			storage: entry.storage
 		});
-		staged.push(entry);
-	}
-	return staged;
+		return entry;
+	}).toArray();
 }
 /**
 * Stages a vendored host root from a real checkout.
@@ -1504,37 +1554,36 @@ function stageHost(checkout, host, options) {
 	const source = resolve(checkout);
 	if (!isPhysicalDirectory(source)) throw new ScaffoldError("TARGET", `Staging checkout is not a physical directory at ${source}`, { checkout: source });
 	if (!isVacant(host)) throw new ScaffoldError("TARGET", `Staging host root is not vacant at ${host}`, { host });
-	const vendored = [];
-	const roots = [];
-	const missing = [];
-	for (const path of [
+	const reads = [
 		...HOST_PATHS,
 		...CANON_PATHS,
 		...REFERENCE_PATHS
-	]) {
+	].map((path) => {
 		const full = resolveContainedPath(source, path);
 		if (full === void 0) throw new ScaffoldError("INVALID", `Vendored path leaves its checkout at ${path}`, {
 			checkout: source,
 			path
 		});
-		if (isPhysicalFile(full)) {
-			vendored.push(path);
-			continue;
-		}
-		if (!isPhysicalDirectory(full)) {
-			if (!CANON_PATHS.includes(path)) missing.push(path);
-			continue;
-		}
-		roots.push(path);
-		for (const nested of listDirectories(full)) {
-			const rooted = `${path}/${nested}`;
-			if (!matchesSensitivePath(rooted)) roots.push(rooted);
-		}
-		for (const name of listFiles(full)) {
-			const destination = `${path}/${name}`;
-			if (!matchesSensitivePath(destination)) vendored.push(destination);
-		}
-	}
+		if (isPhysicalFile(full)) return {
+			vendored: [path],
+			roots: [],
+			missing: []
+		};
+		if (!isPhysicalDirectory(full)) return {
+			vendored: [],
+			roots: [],
+			missing: CANON_PATHS.includes(path) ? [] : [path]
+		};
+		const nested = listDirectories(full);
+		return {
+			vendored: listFiles(full).map((name) => `${path}/${name}`).filter((destination) => !matchesSensitivePath(destination)),
+			roots: [path, ...nested.map((name) => `${path}/${name}`).filter((rooted) => !matchesSensitivePath(rooted))],
+			missing: []
+		};
+	});
+	const vendored = reads.flatMap((read) => read.vendored);
+	const roots = reads.flatMap((read) => read.roots).sort();
+	const missing = reads.flatMap((read) => read.missing);
 	if (missing.length > 0) throw new ScaffoldError("TARGET", "The checkout does not carry every vendored path", {
 		checkout: source,
 		missing
@@ -1554,9 +1603,8 @@ function stageHost(checkout, host, options) {
 			path
 		});
 	}
-	const stored = /* @__PURE__ */ new Set([MANIFEST_NAME]);
-	const candidates = [];
-	for (const destination of vendored) {
+	const storages = vendored.map((destination) => pathToStorage(destination));
+	const candidates = vendored.map((destination, index) => {
 		const full = resolveContainedPath(source, destination);
 		if (full === void 0) throw new ScaffoldError("INVALID", `Vendored path leaves its checkout at ${destination}`, {
 			checkout: source,
@@ -1568,16 +1616,13 @@ function stageHost(checkout, host, options) {
 			path: destination,
 			limit: MAX_ARTIFACT_BYTES
 		});
-		if (stored.has(entry.storage)) throw new ScaffoldError("TARGET", `Two vendored paths claim the storage name ${entry.storage}`, {
+		if (entry.storage === "manifest.json" || storages.indexOf(entry.storage) < index) throw new ScaffoldError("TARGET", `Two vendored paths claim the storage name ${entry.storage}`, {
 			checkout: source,
 			path: destination,
 			storage: entry.storage
 		});
-		stored.add(entry.storage);
-		candidates.push(entry);
-	}
-	candidates.sort((first, second) => first.storage < second.storage ? -1 : 1);
-	roots.sort();
+		return entry;
+	}).sort((first, second) => first.storage < second.storage ? -1 : 1);
 	const baseline = resolveContainedPath(source, options?.inventory ?? HOST_INVENTORY_PATH);
 	if (baseline === void 0) throw new ScaffoldError("INVALID", "Surface inventory leaves its checkout", {
 		checkout: source,
@@ -1597,8 +1642,7 @@ function stageHost(checkout, host, options) {
 		host: root,
 		...established.success ? {} : { error: established.error }
 	});
-	const entries = [];
-	for (const entry of candidates) {
+	const entries = candidates.map((entry) => {
 		const origin = resolveContainedPath(source, entry.destination);
 		const destination = resolveContainedPath(root, entry.storage);
 		if (origin === void 0 || destination === void 0) throw new ScaffoldError("INVALID", `Vendored path leaves its root at ${entry.destination}`, {
@@ -1622,17 +1666,16 @@ function stageHost(checkout, host, options) {
 			host: root,
 			storage: entry.storage
 		});
-		entries.push({
+		return {
 			...entry,
 			digest
-		});
-	}
+		};
+	});
 	const collisions = readSurfaceCollisions(join(root, "guides"));
-	const growth = [];
-	if (published !== void 0) for (const [name, owners] of collisions) {
+	const growth = published === void 0 ? [] : [...collisions].flatMap(([name, owners]) => {
 		const record = published.get(name);
-		if (!(record !== void 0 && owners.every((owner) => record.includes(owner)))) growth.push(`${name} staged (${owners.join(", ")}), recorded (${record?.join(", ") ?? "absent"})`);
-	}
+		return record !== void 0 && owners.every((owner) => record.includes(owner)) ? [] : [`${name} staged (${owners.join(", ")}), recorded (${record?.join(", ") ?? "absent"})`];
+	});
 	if (growth.length > 0) throw new ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
 		checkout: source,
 		host: root,
@@ -1692,26 +1735,19 @@ function readSurfaceCollisions(root) {
 		error: loaded.error
 	});
 	const guide = loaded.value;
-	const owners = /* @__PURE__ */ new Map();
-	for (const path of listFiles(root)) {
-		if (path.includes("/") || extname(path) !== ".md" || path === "README.md") continue;
+	const claims = listFiles(root).filter((path) => !path.includes("/") && extname(path) === ".md" && path !== "README.md").flatMap((path) => {
 		const text = readFileText(root, path);
 		if (text === void 0) throw new ScaffoldError("TARGET", `Surface guide cannot be read at ${path}`, {
 			root,
 			path
 		});
-		for (const symbol of guide.createGuide(text).surface()) {
-			const claimed = owners.get(symbol.name) ?? /* @__PURE__ */ new Set();
-			claimed.add(basename(path, ".md"));
-			owners.set(symbol.name, claimed);
-		}
-	}
-	const collisions = /* @__PURE__ */ new Map();
-	for (const name of [...owners.keys()].sort()) {
-		const claimed = owners.get(name);
-		if (claimed !== void 0 && claimed.size > 1) collisions.set(name, [...claimed].sort());
-	}
-	return collisions;
+		return guide.createGuide(text).surface().map((symbol) => [symbol.name, basename(path, ".md")]);
+	});
+	const grouped = Map.groupBy(claims, ([name]) => name);
+	return new Map([...grouped.keys()].sort().flatMap((name) => {
+		const owners = [...new Set((grouped.get(name) ?? []).map(([, owner]) => owner))];
+		return owners.length > 1 ? [[name, owners.sort()]] : [];
+	}));
 }
 /**
 * Reads the Surface collision baseline from a committed inventory.
@@ -2461,17 +2497,15 @@ var WriteTransaction = class {
 			paths
 		});
 		this.#target = resolve(target);
-		const expectations = /* @__PURE__ */ new Map();
-		for (const path of paths) {
+		this.#expectations = new Map(Array.from(paths, (path) => {
 			const expectation = readExpectation(this.#resolve(this.#target, path));
 			if (expectation === void 0) throw new ScaffoldError("TARGET", `The destination at ${path} is a shape this package will not write over.`, {
 				target: this.#target,
 				path
 			});
-			expectations.set(path, expectation);
-		}
-		this.#expectations = expectations;
-		const destinations = new Set([...expectations.values()].map((expectation) => expectation.path));
+			return [path, expectation];
+		}));
+		const destinations = new Set([...this.#expectations.values()].map((expectation) => expectation.path));
 		for (const precondition of preconditions ?? []) {
 			if (!destinations.has(precondition.path)) throw new ScaffoldError("INVALID", `The precondition at ${precondition.path} names no destination of this transaction.`, {
 				target: this.#target,
@@ -2660,8 +2694,14 @@ var WriteTransaction = class {
 		const taken = [];
 		const applied = attempt(() => {
 			this.#preflight();
-			for (const path of this.#staged) this.#promote(path, promoted);
-			for (const path of this.#taken) this.#take(path, taken);
+			for (const path of this.#staged) {
+				this.#promote(path);
+				promoted.push(path);
+			}
+			for (const path of this.#taken) {
+				this.#take(path);
+				taken.push(path);
+			}
 		});
 		this.#open = false;
 		if (!applied.success) {
@@ -2718,8 +2758,7 @@ var WriteTransaction = class {
 			path
 		});
 		const base = resolve(root);
-		let ancestor = dirname(destination);
-		for (let depth = 0; depth <= 64; depth += 1) {
+		for (const ancestor of listAncestors(destination, 66).slice(1)) {
 			const state = readExpectation(ancestor);
 			if (state === void 0 || state.shape === "file") throw new ScaffoldError("WRITE", `The path ${path} passes through a link or a file.`, {
 				root,
@@ -2727,9 +2766,6 @@ var WriteTransaction = class {
 				ancestor
 			});
 			if (ancestor === base) return destination;
-			const parent = dirname(ancestor);
-			if (parent === ancestor) break;
-			ancestor = parent;
 		}
 		throw new ScaffoldError("INVALID", `The path ${path} does not resolve beneath its root.`, {
 			root,
@@ -2738,41 +2774,44 @@ var WriteTransaction = class {
 	}
 	#establish(path) {
 		const destination = resolve(path);
-		const missing = [];
-		let current = destination;
-		let anchor = readAnchor(current);
-		for (let depth = 0; anchor === void 0 && depth <= 64; depth += 1) {
-			const state = readExpectation(current);
-			if (state === void 0 || state.shape !== "absent") throw new ScaffoldError("WRITE", `The directory at ${current} is not a physical directory.`, { path: destination });
-			missing.push(current);
-			const parent = dirname(current);
-			if (parent === current) throw new ScaffoldError("WRITE", `The directory at ${destination} has no existing ancestor.`, { path: destination });
-			current = parent;
-			anchor = readAnchor(current);
-		}
-		if (anchor === void 0) throw new ScaffoldError("WRITE", `The directory at ${destination} is nested past the ceiling.`, {
-			path: destination,
-			limit: 64
-		});
+		const { anchor: located, missing } = this.#locate(destination);
 		const created = [];
 		for (const segment of [...missing].reverse()) {
+			const anchor = created.at(-1) ?? located;
 			if (!matchesAnchor(anchor)) throw new ScaffoldError("WRITE", `The directory at ${anchor.path} changed while writing.`, {
 				path: destination,
 				ancestor: anchor.path
 			});
 			mkdirSync(segment);
-			this.#created.push(segment);
 			const established = readAnchor(segment);
+			this.#created.push(established ?? segment);
 			if (established === void 0) throw new ScaffoldError("WRITE", `The directory at ${segment} changed while writing.`, { path: destination });
-			anchor = established;
-			this.#created[this.#created.length - 1] = established;
 			created.push(established);
 		}
 		return {
-			anchor,
+			anchor: created.at(-1) ?? located,
 			created
 		};
 	}
+	#locate(destination) {
+		const missing = [];
+		for (const [depth, current] of listAncestors(destination, 66).entries()) {
+			const anchor = readAnchor(current);
+			if (anchor !== void 0) return {
+				anchor,
+				missing
+			};
+			if (depth > 64) break;
+			const state = readExpectation(current);
+			if (state === void 0 || state.shape !== "absent") throw new ScaffoldError("WRITE", `The directory at ${current} is not a physical directory.`, { path: destination });
+			missing.push(current);
+			if (dirname(current) === current) throw new ScaffoldError("WRITE", `The directory at ${destination} has no existing ancestor.`, { path: destination });
+		}
+		throw new ScaffoldError("WRITE", `The directory at ${destination} is nested past the ceiling.`, {
+			path: destination,
+			limit: 64
+		});
+	}
 	#preflight() {
 		for (const anchor of this.#created) {
 			if (isString(anchor)) throw new ScaffoldError("WRITE", `The directory at ${anchor} changed while writing.`, {
@@ -2793,7 +2832,7 @@ var WriteTransaction = class {
 			path
 		});
 	}
-	#promote(path, promoted) {
+	#promote(path) {
 		const expectation = this.#expectation(path);
 		if (!matchesExpectation(expectation)) throw new ScaffoldError("WRITE", `The destination at ${path} moved while writing.`, { path });
 		const staged = this.#resolve(this.#stage, path);
@@ -2804,23 +2843,19 @@ var WriteTransaction = class {
 			linkSync(expectation.path, backup);
 		}
 		renameSync(staged, expectation.path);
-		promoted.push(path);
 	}
-	#take(path, taken) {
+	#take(path) {
 		const expectation = this.#expectation(path);
 		if (!matchesExpectation(expectation)) throw new ScaffoldError("WRITE", `The destination at ${path} moved while writing.`, { path });
 		const backup = this.#resolve(this.#backup, path);
 		mkdirSync(dirname(backup), { recursive: true });
 		renameSync(expectation.path, backup);
-		taken.push(path);
 	}
 	#recover(promoted, taken) {
-		const residue = [];
-		for (const path of [...taken].reverse()) {
+		const restoring = [...[...taken].reverse().flatMap((path) => {
 			const restored = attempt(() => renameSync(this.#resolve(this.#backup, path), this.#expectation(path).path));
-			if (!restored.success) residue.push(restored.error);
-		}
-		for (const path of [...promoted].reverse()) {
+			return restored.success ? [] : [restored.error];
+		}), ...[...promoted].reverse().flatMap((path) => {
 			const expectation = this.#expectation(path);
 			const restored = attempt(() => {
 				if (expectation.shape === "absent") {
@@ -2829,21 +2864,23 @@ var WriteTransaction = class {
 				}
 				renameSync(this.#resolve(this.#backup, path), expectation.path);
 			});
-			if (!restored.success) residue.push(restored.error);
-		}
-		if (residue.length === 0) {
-			const cleared = attempt(() => rmSync(this.#root, {
-				recursive: true,
-				force: true
-			}));
-			if (!cleared.success) residue.push(cleared.error);
-		}
-		for (const created of [...this.#created].reverse()) {
+			return restored.success ? [] : [restored.error];
+		})];
+		const cleared = restoring.length === 0 ? attempt(() => rmSync(this.#root, {
+			recursive: true,
+			force: true
+		})) : void 0;
+		const clearing = cleared === void 0 || cleared.success ? [] : [cleared.error];
+		const removing = [...this.#created].reverse().flatMap((created) => {
 			const path = isString(created) ? created : created.path;
 			const removed = attempt(() => rmdirSync(path));
-			if (!removed.success && !matchesMissingPath(removed.error)) residue.push(removed.error);
-		}
-		return residue;
+			return !removed.success && !matchesMissingPath(removed.error) ? [removed.error] : [];
+		});
+		return [
+			...restoring,
+			...clearing,
+			...removing
+		];
 	}
 	#stagePath(path) {
 		const staged = this.#resolve(this.#stage, path);
@@ -3070,18 +3107,17 @@ var Materializer = class {
 		const derived = this.#derive(accepted, directory, hydrated);
 		this.#reconfirm(derived.findings, preview.findings, directory);
 		const drifted = new Map(derived.findings.map((finding) => [finding.path, finding.drift]));
-		const writes = [];
-		const skipped = [];
-		const preconditions = [];
-		for (const artifact of hydrated.artifacts) {
-			const drift = drifted.get(artifact.path);
-			if (drift !== "missing" && drift !== "stale") {
-				skipped.push(artifact.path);
-				continue;
-			}
-			preconditions.push(this.#bind(directory, artifact.path, drift === "missing"));
-			writes.push(artifact);
-		}
+		const judged = hydrated.artifacts.map((artifact) => ({
+			artifact,
+			drift: drifted.get(artifact.path)
+		}));
+		const skipped = judged.flatMap(({ artifact, drift }) => drift === "missing" || drift === "stale" ? [] : [artifact.path]);
+		const selected = judged.flatMap(({ artifact, drift }) => drift === "missing" || drift === "stale" ? [{
+			artifact,
+			missing: drift === "missing"
+		}] : []);
+		const preconditions = selected.map(({ artifact, missing }) => this.#bind(directory, artifact.path, missing));
+		const writes = selected.map(({ artifact }) => artifact);
 		return this.#apply(directory, writes, [], skipped, preconditions);
 	}
 	/**
@@ -3106,15 +3142,15 @@ var Materializer = class {
 		const writes = [];
 		const skipped = [];
 		const preconditions = [];
-		let remaining = MAX_TOTAL_ARTIFACT_BYTES;
+		const spent = [];
 		for (const fetched of accepted) {
-			const hex = fetched.lookup === "found" ? contentToHex(fetched.content) : fetched.observed === void 0 ? this.#reference(fetched.path, remaining) : void 0;
+			const hex = fetched.lookup === "found" ? contentToHex(fetched.content) : fetched.observed === void 0 ? this.#reference(fetched.path, MAX_TOTAL_ARTIFACT_BYTES - computeTotal(spent)) : void 0;
 			if (hex === void 0 || fetched.observed === hex) {
 				skipped.push(fetched.path);
 				continue;
 			}
-			remaining -= hex.length / 2;
-			if (remaining < 0) throw this.#error("TARGET", "The guide mirrors exceed the total artifact byte limit.");
+			spent.push(hex.length / 2);
+			if (computeTotal(spent) > MAX_TOTAL_ARTIFACT_BYTES) throw this.#error("TARGET", "The guide mirrors exceed the total artifact byte limit.");
 			const current = readFileHex(directory, fetched.path);
 			if (current !== fetched.observed) throw this.#error("TARGET", `The mirror at ${fetched.path} moved since it was fetched.`, {
 				target: directory,
@@ -3247,18 +3283,10 @@ var Materializer = class {
 		const derived = this.#derive(accepted, directory);
 		this.#reconfirmCandidates(derived.findings, preview.findings, directory);
 		const tracked = new Set(state.tracked);
-		const removals = [];
-		const skipped = [];
-		for (const finding of derived.findings) {
-			if (finding.drift !== "foreign") continue;
-			if (!tracked.has(finding.path) || matchesProtectedPath(finding.path)) {
-				skipped.push(finding.path);
-				continue;
-			}
-			removals.push(finding.path);
-		}
-		const preconditions = [];
-		for (const path of removals) preconditions.push(this.#bind(directory, path, false));
+		const foreign = derived.findings.filter((finding) => finding.drift === "foreign").map((finding) => finding.path);
+		const skipped = foreign.filter((path) => !tracked.has(path) || matchesProtectedPath(path));
+		const removals = foreign.filter((path) => tracked.has(path) && !matchesProtectedPath(path));
+		const preconditions = removals.map((path) => this.#bind(directory, path, false));
 		return this.#purge(directory, removals, skipped, preconditions);
 	}
 	/**
@@ -3318,49 +3346,51 @@ var Materializer = class {
 		if (this.#entries.size !== manifest.entries.length) throw this.#error("TARGET", "The vendored host manifest maps two files to one destination.", { host: root });
 	}
 	#hydrate(plan) {
-		const artifacts = [];
-		let remaining = MAX_TOTAL_ARTIFACT_BYTES;
+		const groups = [];
+		const spent = [];
 		for (const artifact of plan.artifacts) {
 			if (artifact.origin !== "host") {
-				remaining -= computeBytes(artifact.content);
-				artifacts.push(artifact);
+				spent.push(computeBytes(artifact.content));
+				groups.push([artifact]);
 				continue;
 			}
-			const expanded = this.#expand(artifact, remaining);
-			for (const one of expanded) remaining -= one.origin === "host" ? (one.hex?.length ?? 0) / 2 : computeBytes(one.content);
-			artifacts.push(...expanded);
+			const expanded = this.#expand(artifact, MAX_TOTAL_ARTIFACT_BYTES - computeTotal(spent));
+			spent.push(computeTotal(expanded.map((one) => one.origin === "host" ? (one.hex?.length ?? 0) / 2 : computeBytes(one.content))));
+			groups.push(expanded);
 		}
-		if (remaining < 0) throw this.#error("TARGET", "The hydrated plan retains more bytes than one plan may.", {
+		if (computeTotal(spent) > MAX_TOTAL_ARTIFACT_BYTES) throw this.#error("TARGET", "The hydrated plan retains more bytes than one plan may.", {
 			host: this.#root,
 			limit: MAX_TOTAL_ARTIFACT_BYTES
 		});
 		return {
 			blueprint: plan.blueprint,
 			groups: plan.groups,
-			artifacts
+			artifacts: groups.flat()
 		};
 	}
 	#derive(plan, target, hydrated = this.#hydrate(plan)) {
-		const paths = new Set(hydrated.artifacts.map((artifact) => artifact.path));
-		for (const root of this.#roots(plan)) {
-			const directory = resolveContainedPath(target, root);
-			if (directory === void 0) throw this.#error("TARGET", `The owned root at ${root} leaves its target.`, {
-				target,
-				path: root
-			});
-			for (const name of listFiles(directory)) paths.add(`${root}/${name}`);
-		}
-		for (const path of listCanonPaths(target, plan.groups)) paths.add(path);
+		const paths = /* @__PURE__ */ new Set([
+			...hydrated.artifacts.map((artifact) => artifact.path),
+			...this.#roots(plan).flatMap((root) => {
+				const directory = resolveContainedPath(target, root);
+				if (directory === void 0) throw this.#error("TARGET", `The owned root at ${root} leaves its target.`, {
+					target,
+					path: root
+				});
+				return listFiles(directory).map((name) => `${root}/${name}`);
+			}),
+			...listCanonPaths(target, plan.groups)
+		]);
 		const questions = [];
 		if (plan.groups.includes("guides")) {
 			const directory = resolveContainedPath(target, "guides");
-			let remaining = MAX_TOTAL_ARTIFACT_BYTES;
+			const spent = [];
 			for (const file of directory === void 0 ? [] : listFiles(directory)) {
 				const path = `guides/${file}`;
 				if (file.includes("/") || file === "README.md" || !file.endsWith(".md") || path === nameToGuide(plan.blueprint.name)) continue;
-				const hosted = this.#reference(path, remaining);
+				const hosted = this.#reference(path, MAX_TOTAL_ARTIFACT_BYTES - computeTotal(spent));
 				if (hosted === void 0) continue;
-				remaining -= hosted.length / 2;
+				spent.push(hosted.length / 2);
 				const present = readFileHex(target, path);
 				if (present !== void 0 && present !== hosted) questions.push({
 					field: "guides",
@@ -3385,20 +3415,15 @@ var Materializer = class {
 		return readFileHex(this.#root, path, Math.max(0, Math.min(MAX_ARTIFACT_BYTES, budget)));
 	}
 	#roots(plan) {
-		const roots = /* @__PURE__ */ new Set();
-		for (const artifact of plan.artifacts) {
-			if (artifact.origin !== "host") continue;
+		return [...new Set(plan.artifacts.flatMap((artifact) => {
+			if (artifact.origin !== "host") return [];
 			const source = artifact.source ?? artifact.path;
-			if (this.#manifest?.roots.includes(source) === true) {
-				roots.add(artifact.path);
-				continue;
-			}
-			if (this.#manifest !== void 0) continue;
+			if (this.#manifest?.roots.includes(source) === true) return [artifact.path];
+			if (this.#manifest !== void 0) return [];
 			const root = this.#root;
 			const directory = root === void 0 ? void 0 : resolveContainedPath(root, source);
-			if (directory !== void 0 && isPhysicalDirectory(directory)) roots.add(artifact.path);
-		}
-		return [...roots];
+			return directory !== void 0 && isPhysicalDirectory(directory) ? [artifact.path] : [];
+		}))];
 	}
 	#expand(artifact, remaining) {
 		const manifest = this.#manifest;
@@ -3411,15 +3436,15 @@ var Materializer = class {
 			source
 		});
 		const expanded = [];
-		let budget = remaining;
+		const spent = [];
 		for (const entry of matched) {
 			const path = this.#remap(artifact, entry.destination);
 			if (isRetainedPath(path)) {
 				expanded.push(this.#presence(artifact, path, entry.destination));
 				continue;
 			}
-			const hex = this.#read(entry, budget);
-			budget -= hex.length / 2;
+			const hex = this.#read(entry, remaining - computeTotal(spent));
+			spent.push(hex.length / 2);
 			expanded.push(this.#hydrated(artifact, path, entry.destination, hex));
 		}
 		return expanded;
@@ -3440,7 +3465,7 @@ var Materializer = class {
 			source
 		});
 		const expanded = [];
-		let budget = remaining;
+		const spent = [];
 		for (const name of listFiles(full)) {
 			const path = `${artifact.path}/${name}`;
 			const destination = `${source}/${name}`;
@@ -3448,8 +3473,8 @@ var Materializer = class {
 				expanded.push(this.#presence(artifact, path, destination));
 				continue;
 			}
-			const hex = this.#readRoot(destination, budget);
-			budget -= hex.length / 2;
+			const hex = this.#readRoot(destination, remaining - computeTotal(spent));
+			spent.push(hex.length / 2);
 			expanded.push(this.#hydrated(artifact, path, destination, hex));
 		}
 		return expanded;
@@ -3457,16 +3482,15 @@ var Materializer = class {
 	#empty(plan) {
 		const manifest = this.#manifest;
 		if (manifest === void 0) return [];
-		const directories = /* @__PURE__ */ new Set();
-		for (const artifact of plan.artifacts) {
-			if (artifact.origin !== "host") continue;
+		const directories = plan.artifacts.flatMap((artifact) => {
+			if (artifact.origin !== "host") return [];
 			const source = artifact.source ?? artifact.path;
-			for (const root of manifest.roots) {
-				if (root !== source && !root.startsWith(`${source}/`)) continue;
-				if (!manifest.entries.some((entry) => entry.destination === root || entry.destination.startsWith(`${root}/`))) directories.add(this.#remap(artifact, root));
-			}
-		}
-		return [...directories].sort();
+			return manifest.roots.flatMap((root) => {
+				if (root !== source && !root.startsWith(`${source}/`)) return [];
+				return manifest.entries.some((entry) => entry.destination === root || entry.destination.startsWith(`${root}/`)) ? [] : [this.#remap(artifact, root)];
+			});
+		});
+		return [...new Set(directories)].sort();
 	}
 	#remap(artifact, destination) {
 		const source = artifact.source ?? artifact.path;
@@ -3663,11 +3687,7 @@ var Materializer = class {
 	#fill(writes) {
 		const value = this.#value;
 		if (value === void 0) return void 0;
-		const destinations = /* @__PURE__ */ new Set();
-		for (const artifact of writes) {
-			if (artifact.origin !== "host") continue;
-			destinations.add(artifact.source ?? artifact.path);
-		}
+		const destinations = new Set(writes.flatMap((artifact) => artifact.origin === "host" ? [artifact.source ?? artifact.path] : []));
 		if (destinations.size === 0) return void 0;
 		const opened = attempt(() => mkdtempSync(join(tmpdir(), "orkestrel-scaffold-fill-")));
 		if (!opened.success) throw this.#error("WRITE", "The supplied host could not be filled into a private root.", { error: opened.error });
@@ -3737,8 +3757,7 @@ var Materializer = class {
 	}
 	#recatalog(entries) {
 		const layers = catalogToLayers(entries);
-		const placed = /* @__PURE__ */ new Map();
-		for (const [index, layer] of layers.entries()) for (const name of layer) placed.set(name, index);
+		const placed = new Map(layers.flatMap((layer, index) => layer.map((name) => [name, index])));
 		const rows = entries.map((entry) => {
 			if (entry.lookup !== "found") return [
 				`\`${entry.name}\``,
@@ -3765,11 +3784,7 @@ var Materializer = class {
 			"Runtime dependencies",
 			"Peer dependencies"
 		];
-		const widths = headers.map((header, column) => {
-			let width = Math.max(3, header.length);
-			for (const row of rows) width = Math.max(width, row[column]?.length ?? 0);
-			return width;
-		});
+		const widths = headers.map((header, column) => Math.max(3, header.length, ...rows.map((row) => row[column]?.length ?? 0)));
 		const table = [
 			headers,
 			widths.map((width) => "-".repeat(width)),
@@ -3825,6 +3840,66 @@ var Materializer = class {
 	}
 };
 //#endregion
+//#region src/server/ReadAllowance.ts
+/**
+* Represents the byte allowance one upstream call spends across every read it makes.
+*
+* @remarks
+* Each call constructs its own allowance from the reader's budget, so concurrent
+* calls never spend each other's bytes. A read that brings the call exactly to
+* its budget leaves `remaining` at zero and is accepted; the next request is
+* refused before it is sent, and a body that passes the budget is refused at the
+* chunk that overshoots.
+*
+* @example
+* ```ts
+* import { ReadAllowance } from '@orkestrel/scaffold/server'
+*
+* const allowance = new ReadAllowance(1_024)
+* allowance.spend(1_000)
+* allowance.remaining // 24
+* ```
+*/
+var ReadAllowance = class {
+	#remaining;
+	/**
+	* Constructs an allowance holding the whole budget.
+	*
+	* @param budget - The bytes the call may read in total.
+	* @throws {@link ScaffoldError} coded `INVALID` when `budget` is not a
+	* non-negative safe integer.
+	*/
+	constructor(budget) {
+		if (!isNonNegativeInteger(budget) || !Number.isSafeInteger(budget)) throw new ScaffoldError("INVALID", "The read budget is not a non-negative safe integer.", { field: "budget" });
+		this.#remaining = budget;
+	}
+	/** The bytes the call has left; negative once a read overshoots the budget. */
+	get remaining() {
+		return this.#remaining;
+	}
+	/**
+	* Spends bytes a read consumed from the allowance.
+	*
+	* @param bytes - The decoded bytes the read consumed.
+	* @returns Nothing.
+	* @throws {@link ScaffoldError} coded `INVALID` when `bytes` is not a
+	* non-negative safe integer.
+	*
+	* @example
+	* ```ts
+	* import { ReadAllowance } from '@orkestrel/scaffold/server'
+	*
+	* const allowance = new ReadAllowance(10)
+	* allowance.spend(12)
+	* allowance.remaining // -2
+	* ```
+	*/
+	spend(bytes) {
+		if (!isNonNegativeInteger(bytes) || !Number.isSafeInteger(bytes)) throw new ScaffoldError("INVALID", "The spent bytes are not a non-negative safe integer.", { field: "bytes" });
+		this.#remaining -= bytes;
+	}
+};
+//#endregion
 //#region src/server/Upstream.ts
 /**
 * Represents the reading spine: one bounded, unauthenticated, redirect-free request per answer.
@@ -3855,9 +3930,9 @@ var Materializer = class {
 * reader's own abort signal, so {@link Upstream.destroy} cancels what is in
 * flight instead of waiting for it.
 *
-* The allowance is threaded through the private reads as a mutable
-* {@link ReadAllowance} carrier rather than held on the instance, because
-* concurrent calls each own their own budget and must not spend each other's.
+* Each call constructs its own {@link ReadAllowance} from the reader's budget and passes it
+* through the private reads rather than holding it on the instance, because concurrent calls
+* each own a budget and must not spend each other's.
 *
 * @example
 * ```ts
@@ -3950,7 +4025,7 @@ var Upstream = class {
 	async lookup(dependencies) {
 		this.#assertAlive();
 		const accepted = this.#accept(dependencies, isDependencies, "dependencies");
-		const allowance = { remaining: this.#budget };
+		const allowance = new ReadAllowance(this.#budget);
 		return this.#gather(accepted, (dependency) => this.#release(dependency, allowance));
 	}
 	/**
@@ -3984,7 +4059,7 @@ var Upstream = class {
 		this.#assertAlive();
 		const accepted = this.#accept(names, isDependencyNames, "names");
 		const observed = this.#accept(current, isSnapshot, "current");
-		const allowance = { remaining: this.#budget };
+		const allowance = new ReadAllowance(this.#budget);
 		return this.#gather(accepted, (name) => this.#mirror(name, observed, allowance));
 	}
 	/**
@@ -4031,7 +4106,7 @@ var Upstream = class {
 		const accepted = this.#accept(paths, isPaths, "paths");
 		const observed = this.#accept(current, isSnapshot, "current");
 		if (accepted.length === 0) return [];
-		const allowance = { remaining: this.#budget };
+		const allowance = new ReadAllowance(this.#budget);
 		const inventory = await this.#inventory(allowance);
 		return this.#gather(accepted, (path) => this.#file(path, inventory, observed, allowance));
 	}
@@ -4064,7 +4139,7 @@ var Upstream = class {
 	*/
 	async catalog() {
 		this.#assertAlive();
-		const allowance = { remaining: this.#budget };
+		const allowance = new ReadAllowance(this.#budget);
 		const names = await this.#packages(allowance);
 		return this.#gather(names, (name) => this.#entry(name, allowance));
 	}
@@ -4233,16 +4308,10 @@ var Upstream = class {
 			lookup: "failed",
 			note: `the vendored inventory at ${url} does not match its own membership digest`
 		};
-		const digests = /* @__PURE__ */ new Map();
-		const duplicates = /* @__PURE__ */ new Set();
-		for (const entry of manifest.entries) {
-			if (digests.has(entry.destination)) duplicates.add(entry.destination);
-			digests.set(entry.destination, entry.digest);
-		}
 		return {
 			lookup: "found",
-			digests,
-			duplicates,
+			digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
+			duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
 			note: ""
 		};
 	}
@@ -4271,18 +4340,10 @@ var Upstream = class {
 		if (!isRecord(manifest)) return [];
 		const declared = manifest[section];
 		if (!isRecord(declared)) return [];
-		const edges = [];
-		for (const [name, range] of Object.entries(declared)) {
-			if (edges.length >= MAX_COLLECTION_ITEMS) break;
-			if (!isString(range) || range.length === 0 || range.length > MAX_RANGE_LENGTH) continue;
-			if (CONTROL_CHARACTER_PATTERN.test(name) || CONTROL_CHARACTER_PATTERN.test(range)) continue;
-			if (name.length === 0 || name.length > MAX_DEPENDENCY_NAME_LENGTH) continue;
-			edges.push({
-				name,
-				range
-			});
-		}
-		return edges;
+		return Object.entries(declared).flatMap(([name, range]) => !isString(range) || range.length === 0 || range.length > MAX_RANGE_LENGTH || CONTROL_CHARACTER_PATTERN.test(name) || CONTROL_CHARACTER_PATTERN.test(range) || name.length === 0 || name.length > MAX_DEPENDENCY_NAME_LENGTH ? [] : [{
+			name,
+			range
+		}]).slice(0, MAX_COLLECTION_ITEMS);
 	}
 	async #packages(allowance) {
 		const url = `${this.#registryBase}/-/org/${ORKESTREL_SCOPE}/package`;
@@ -4311,11 +4372,7 @@ var Upstream = class {
 		const parsed = parseJSON(content);
 		if (!isRecord(parsed)) return void 0;
 		const versions = parsed.versions;
-		let selected;
-		if (isRecord(versions)) for (const version of Object.keys(versions)) {
-			if (!this.#admits(range, version)) continue;
-			if (selected === void 0 || compareVersions(version, selected) > 0) selected = version;
-		}
+		const selected = isRecord(versions) ? Object.keys(versions).filter((version) => this.#admits(range, version)).reduce((highest, version) => highest === void 0 || compareVersions(version, highest) > 0 ? version : highest, void 0) : void 0;
 		if (selected !== void 0) return selected;
 		const latest = this.#latest(content);
 		return latest !== void 0 && this.#admits(range, latest) ? latest : void 0;
@@ -4343,14 +4400,12 @@ var Upstream = class {
 	#encode(path) {
 		return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 	}
-	async #readWithRetries(url, timeout, allowance, accept, binary = false) {
-		let note = "";
-		for (let round = 0; round <= this.#retries; round += 1) {
-			this.#assertAlive();
-			const outcome = binary ? await this.#request(url, timeout, allowance, accept, true) : await this.#request(url, timeout, allowance, accept);
-			if (outcome.lookup !== "failed") return outcome;
-			note = outcome.note;
-		}
+	async #readWithRetries(url, timeout, allowance, accept, binary = false, attempt = 0) {
+		this.#assertAlive();
+		const outcome = binary ? await this.#request(url, timeout, allowance, accept, true) : await this.#request(url, timeout, allowance, accept);
+		if (outcome.lookup !== "failed") return outcome;
+		if (attempt < this.#retries) return binary ? this.#readWithRetries(url, timeout, allowance, accept, true, attempt + 1) : this.#readWithRetries(url, timeout, allowance, accept, false, attempt + 1);
+		const note = outcome.note;
 		this.#error("FETCH", `The upstream read at ${url} produced no answer.`, {
 			url,
 			note
@@ -4454,14 +4509,14 @@ var Upstream = class {
 		const reader = body.getReader();
 		const decoder = binary ? void 0 : new TextDecoder("utf-8", { fatal: true });
 		const chunks = [];
-		let total = 0;
+		const sizes = [];
 		try {
 			for (;;) {
 				const chunk = await reader.read();
 				if (chunk.done) break;
-				total += chunk.value.byteLength;
-				allowance.remaining -= chunk.value.byteLength;
-				if (total > this.#limit) {
+				sizes.push(chunk.value.byteLength);
+				allowance.spend(chunk.value.byteLength);
+				if (computeTotal(sizes) > this.#limit) {
 					await reader.cancel();
 					const note = `the response passed the ${String(this.#limit)}-byte response limit`;
 					return binary ? {
@@ -4514,31 +4569,28 @@ var Upstream = class {
 		return code === void 0 ? message : `${message} (${code})`;
 	}
 	async #gather(items, run) {
-		const results = [];
-		const state = {
-			cursor: 0,
-			failure: void 0
-		};
-		const workers = Array.from({ length: Math.min(this.#concurrency, items.length) }, () => this.#drain(items, run, results, state));
-		await Promise.allSettled(workers);
-		if (state.failure !== void 0) throw state.failure.error;
-		return results;
+		const entries = items.entries();
+		const failed = new AbortController();
+		const workers = Array.from({ length: Math.min(this.#concurrency, items.length) }, () => this.#drain(entries, run, failed));
+		const settled = await Promise.allSettled(workers);
+		if (failed.signal.aborted) {
+			const reason = failed.signal.reason;
+			throw isRecord(reason) ? reason.error : reason;
+		}
+		return collectIndexed(settled.flatMap((worker) => worker.status === "fulfilled" ? worker.value : []));
 	}
-	async #drain(items, run, results, state) {
-		for (;;) {
-			if (state.failure !== void 0) return;
-			const index = state.cursor;
-			state.cursor += 1;
-			if (index >= items.length) return;
-			const item = items[index];
-			if (item === void 0) return;
+	async #drain(entries, run, failed) {
+		const produced = [];
+		for (const [index, item] of entries) {
+			if (failed.signal.aborted || item === void 0) break;
 			try {
-				results[index] = await run(item);
+				produced.push([index, await run(item)]);
 			} catch (error) {
-				state.failure ??= { error };
-				return;
+				failed.abort(Object.freeze({ error }));
+				break;
 			}
 		}
+		return produced;
 	}
 	#accept(value, guard, field) {
 		const snapshot = cloneValue(value);
@@ -4555,6 +4607,6 @@ var Upstream = class {
 	}
 };
 //#endregion
-export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, decodeHexText, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCollisions, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
+export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, ReadAllowance, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, Upstream, WriteTransaction, climbRealPath, collectIndexed, computeDigest, computeFileDigest, computeManifestDigest, decodeHexText, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listAncestors, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCollisions, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
 
 //# sourceMappingURL=index.js.map