@orkestrel/scaffold 0.0.47 → 0.0.49

package/dist/src/server/index.js

@@ -1,8 +1,9 @@
-import { andOf, arrayOf, attempt, boundsOf, holds, isArray, isBoolean, isError, isFunction, isInteger, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf } from "@orkestrel/contract";
-import { CATALOG_AGENT_PATH, CONTROL_CHARACTER_PATTERN, EXECUTABLE_PATHS, 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, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, replaceManifestRanges } from "../core/index.js";
+import { andOf, arrayOf, attempt, boundsOf, holds, isArray, isBoolean, isError, isFunction, isInteger, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf, unionOf } from "@orkestrel/contract";
+import { CATALOG_AGENT_PATH, CONTROL_CHARACTER_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, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDeferredPath, isDependency, isDependencyName, isHex, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, replaceManifestRanges } from "../core/index.js";
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, parse, relative, resolve, sep } from "node:path";
+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";
+import { basename, dirname, extname, join, parse, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/server/constants.ts
@@ -43,13 +44,13 @@ var RESERVED_SEGMENT_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9]|conin\$|co
 */
 var DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 /**
-* The Git branch syntax the guide endpoint accepts.
+* The Git branch syntax the repository endpoint accepts.
 *
 * @remarks
 * A branch is caller-supplied and reaches a URL path, so it is closed to
 * alphanumerics, dot, underscore, hyphen, and the separator, must open with an
 * alphanumeric, and may carry no `..` anywhere. That last refusal is what stops
-* a branch from walking out of the guide directory it addresses.
+* a branch from walking out of the repository path it addresses.
 */
 var BRANCH_PATTERN = /^(?!.*\.\.)[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 /**
@@ -83,7 +84,7 @@ var MAX_PATH_DEPTH = 64;
 var MAX_INVENTORY_PATHS = 1e5;
 /** Maximum characters one caller-supplied upstream endpoint may carry. */
 var MAX_ENDPOINT_LENGTH = 2048;
-/** Maximum characters one guide branch may carry. */
+/** Maximum characters one repository branch may carry. */
 var MAX_BRANCH_LENGTH = 255;
 /**
 * Maximum simultaneous upstream requests.
@@ -225,10 +226,10 @@ var isEndpoint = stringOf({
 	max: MAX_ENDPOINT_LENGTH
 });
 /**
-* Narrow a value to a Git branch the guide endpoint accepts.
+* Narrow a value to a Git branch the repository endpoint accepts.
 *
 * @remarks
-* A branch reaches the guide URL's path, so the syntax is closed rather than
+* A branch reaches the repository URL's path, so the syntax is closed rather than
 * merely bounded and no `..` is admitted anywhere in it.
 *
 * @example
@@ -270,6 +271,24 @@ var isTimeout = andOf(isInteger, boundsOf(1, MAX_UPSTREAM_TIMEOUT));
 * ```
 */
 var isDependencyNames = andOf(isCollection, arrayOf(isDependencyName));
+/**
+* Narrow a value to a bounded list of target-relative paths.
+*
+* @remarks
+* Composed from the core collection and path guards rather than restated, so
+* the containment law that keeps a caller-supplied path inside its target has
+* exactly one home. It bounds what a caller may hand a public method, which is
+* why it is not {@link isInventory}: that one bounds what a checkout may hold.
+*
+* @example
+* ```ts
+* import { isPaths } from '@orkestrel/scaffold/server'
+*
+* isPaths(['AGENTS.md']) // true
+* isPaths(['../secrets']) // false
+* ```
+*/
+var isPaths = andOf(isCollection, arrayOf(isPath));
 /** Narrow a value to a bounded list of declared runtime dependencies. */
 var isDependencies = andOf(isCollection, arrayOf(isDependency));
 /** Narrow a value to a bounded list of fetched guide mirrors. */
@@ -289,13 +308,19 @@ var isCatalogEntries = andOf(isCollection, arrayOf(isCatalogEntry));
 * ```ts
 * import { isManifestEntry } from '@orkestrel/scaffold/server'
 *
-* isManifestEntry({ storage: 'AGENTS.md', destination: 'AGENTS.md', executable: false }) // true
+* isManifestEntry({
+*   storage: 'AGENTS.md',
+*   destination: 'AGENTS.md',
+*   executable: false,
+*   digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+* }) // true
 * ```
 */
 var isManifestEntry = recordOf({
 	storage: isPath,
 	destination: isPath,
-	executable: isBoolean
+	executable: isBoolean,
+	digest: isDigest
 });
 /**
 * Narrow a value to one {@link HostManifest}.
@@ -311,7 +336,33 @@ var isHostManifest = recordOf({
 	digest: isDigest
 });
 /**
-* Narrow a value to a {@link Repository}.
+* Narrow a value to one {@link Host}.
+*
+* @remarks
+* A whole vendored host handed in as a value is as untrusted as one read from a
+* directory a caller named, so both halves are guarded: the manifest by the same
+* membership law a read root is held to, and the bytes by the core snapshot law,
+* which bounds the fill and reads every key as a path and every value as exact
+* lowercase hexadecimal. Whether those halves agree with each other is the
+* reader's question rather than this one's, because a guard has only `false` to
+* say and a mismatch has a path to name.
+*
+* @example
+* ```ts
+* import { isHost } from '@orkestrel/scaffold/server'
+*
+* const digest = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+*
+* isHost({ manifest: { entries: [], roots: [], digest }, bytes: {} }) // true
+* isHost({ manifest: { entries: [], roots: [], digest } }) // false
+* ```
+*/
+var isHost = recordOf({
+	manifest: isHostManifest,
+	bytes: isSnapshot
+});
+/**
+* Narrow a value to a {@link Worktree}.
 *
 * @remarks
 * Both path lists are target-relative, so both are measured by the core path
@@ -321,13 +372,13 @@ var isHostManifest = recordOf({
 *
 * @example
 * ```ts
-* import { isRepository } from '@orkestrel/scaffold/server'
+* import { isWorktree } from '@orkestrel/scaffold/server'
 *
-* isRepository({ tracked: ['AGENTS.md'], dirty: [] }) // true
-* isRepository({ tracked: ['../secrets'], dirty: [] }) // false
+* isWorktree({ tracked: ['AGENTS.md'], dirty: [] }) // true
+* isWorktree({ tracked: ['../secrets'], dirty: [] }) // false
 * ```
 */
-var isRepository = recordOf({
+var isWorktree = recordOf({
 	tracked: andOf(isInventory, arrayOf(isPath)),
 	dirty: andOf(isInventory, arrayOf(isPath))
 });
@@ -349,6 +400,12 @@ var isMaterializerHooks = recordOf({
 /**
 * Narrow a value to {@link MaterializerOptions}.
 *
+* @remarks
+* `host` admits both representations of one vendored root: a directory path and
+* a whole {@link Host} value. They share a key because they are one setting
+* stated two ways rather than two settings, so nothing downstream has to
+* reconcile a pair that could disagree.
+*
 * @example
 * ```ts
 * import { isMaterializerOptions } from '@orkestrel/scaffold/server'
@@ -358,7 +415,7 @@ var isMaterializerHooks = recordOf({
 * ```
 */
 var isMaterializerOptions = recordOf({
-	host: isFilesystemPath,
+	host: unionOf(isFilesystemPath, isHost),
 	on: isMaterializerHooks,
 	error: isFunction
 }, true);
@@ -372,6 +429,7 @@ var isMaterializerOptions = recordOf({
 var isUpstreamHooks = recordOf({
 	release: isFunction,
 	mirror: isFunction,
+	file: isFunction,
 	error: isFunction,
 	destroy: isFunction
 }, true);
@@ -391,12 +449,12 @@ var isUpstreamHooks = recordOf({
 * ```ts
 * import { isUpstreamOptions } from '@orkestrel/scaffold/server'
 *
-* isUpstreamOptions({ guides: { branch: 'main' }, concurrency: 4 }) // true
+* isUpstreamOptions({ repository: { branch: 'main' }, concurrency: 4 }) // true
 * isUpstreamOptions({ concurrency: 0 }) // false
 * ```
 */
 var isUpstreamOptions = recordOf({
-	guides: recordOf({
+	repository: recordOf({
 		base: isEndpoint,
 		branch: isBranch,
 		timeout: isTimeout
@@ -473,7 +531,7 @@ function matchesGitPath(path) {
 * directories. It is the inversion the contract asks for: the candidate set
 * is re-derived from the plan and narrowed by what git tracks, and the audit
 * must agree with that derivation rather than supply the set itself.
-* Repository metadata is protected because losing history is not a repair,
+* Git metadata is protected because losing history is not a repair,
 * and a target's own `src` and `app` trees are protected because a
 * workspace's source is the one thing scaffold never plans and never owns. A
 * plan the compiler emits never maps a protected root, so this guard exists
@@ -504,7 +562,7 @@ function matchesProtectedPath(path) {
 * The vendoring deny-list. A host root is staged from a real checkout, so the
 * refusal is stated over the path rather than over the file's content: a
 * credential is recognizable by where it sits and what it is called long before
-* anything reads it. Repository metadata is included through
+* anything reads it. Git metadata is included through
 * {@link matchesGitPath}, so one call answers the whole question and no caller
 * has to remember to ask twice.
 *
@@ -601,6 +659,25 @@ function computeDigest(content) {
 	return createHash("sha256").update(content, "utf8").digest("hex");
 }
 /**
+* Projects exact bytes stated in hexadecimal to their SHA-256 digest.
+*
+* @param hex - The exact lowercase hexadecimal bytes to digest.
+* @returns Sixty-four lowercase hexadecimal digits.
+* @throws `ScaffoldError('INVALID', …)` when `hex` is not exact bounded
+* lowercase hexadecimal text.
+*
+* @example
+* ```ts
+* import { hexToDigest } from '@orkestrel/scaffold/server'
+*
+* hexToDigest('68690a') // '98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4'
+* ```
+*/
+function hexToDigest(hex) {
+	if (!isHex(hex)) throw new ScaffoldError("INVALID", "Digest input is not exact hexadecimal bytes", { hex });
+	return createHash("sha256").update(Buffer.from(hex, "hex")).digest("hex");
+}
+/**
 * Compute the digest of a vendored host's declared membership.
 *
 * @param entries - The ordered file membership declarations.
@@ -627,7 +704,8 @@ function computeManifestDigest(entries, roots) {
 		entries: entries.map((entry) => ({
 			storage: entry.storage,
 			destination: entry.destination,
-			executable: entry.executable
+			executable: entry.executable,
+			digest: entry.digest
 		})),
 		roots: [...roots]
 	}));
@@ -1269,6 +1347,7 @@ function readSnapshot(target, paths) {
 * Read a vendored host's manifest, when it carries one.
 *
 * @param host - The vendored host root to read.
+* @param name - The root-relative manifest path. Default: `manifest.json`.
 * @returns The manifest, or `undefined` when the host carries none.
 * @throws `ScaffoldError('INVALID', …)` when `host` is not a host path.
 * @throws `ScaffoldError('TARGET', …)` when the manifest is there but cannot be
@@ -1294,9 +1373,8 @@ function readSnapshot(target, paths) {
 * readHostManifest('./dist/host') // the manifest, or undefined for a raw root
 * ```
 */
-function readHostManifest(host) {
+function readHostManifest(host, name = MANIFEST_NAME) {
 	if (!isFilesystemPath(host)) throw new ScaffoldError("INVALID", "Host root is not a host path", { host });
-	const name = MANIFEST_NAME;
 	const full = resolveContainedPath(host, name);
 	if (full === void 0) throw new ScaffoldError("INVALID", `Host manifest leaves its root at ${host}`, { host });
 	const status = attempt(() => lstatSync(full));
@@ -1315,6 +1393,55 @@ function readHostManifest(host) {
 	return manifest;
 }
 /**
+* Reads the installed vendored host floor as a value.
+*
+* @param root - The vendored host root. Default: the installed package's
+* vendored root, resolved from this module's location.
+* @returns The verified manifest and the exact bytes of every declared entry.
+* @throws `ScaffoldError('TARGET', …)` when the root is not a readable physical
+* directory, its manifest is absent or unreadable, the manifest does not verify,
+* or a declared file is unreadable or misses its digest.
+*
+* @remarks
+* Reads the same default floor the {@link Materializer} uses. Each declared
+* file is addressed through the manifest's storage name and retained under its
+* destination, so the returned value has the same shape as the installed root.
+* When this module executes from TypeScript source, the committed inventory is
+* the manifest and each checkout destination supplies its bytes. The emitted
+* module reads the staged `manifest.json` file and each storage path instead.
+*
+* @example
+* ```ts
+* import { readHostFloor } from '@orkestrel/scaffold/server'
+*
+* readHostFloor().manifest // the installed floor's verified membership
+* ```
+*/
+function readHostFloor(root) {
+	const location = fileURLToPath(import.meta.url);
+	const module = dirname(location);
+	const source = root === void 0 && extname(location) === ".ts";
+	const host = root ?? resolve(module, source ? "../.." : "../../host");
+	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
+	};
+}
+/**
 * Derive one vendored-host manifest entry from a file in a checkout.
 *
 * @param destination - The target-relative path the file is written to.
@@ -1338,20 +1465,155 @@ function readHostManifest(host) {
 * import { readManifestEntry } from '@orkestrel/scaffold/server'
 *
 * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
-* // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false }
+* // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
 * ```
 */
 function readManifestEntry(destination, source) {
-	if (!isPhysicalFile(source)) return void 0;
-	const status = attempt(() => lstatSync(source));
-	if (!status.success || status.value.size > MAX_ARTIFACT_BYTES) return void 0;
+	const digest = computeFileDigest(source);
+	if (digest === void 0) return void 0;
 	return {
 		storage: pathToStorage(destination),
 		destination,
-		executable: matchesExecutablePath(destination)
+		executable: matchesExecutablePath(destination),
+		digest
+	};
+}
+/**
+* Assemble a whole vendored host from live files and the installed floor.
+*
+* @param files - The host-owned vendored files read from the repository, one
+* row per path.
+* @param floor - The installed host floor, which fixes the membership a fill
+* may draw from and supplies the bytes owned by another surface.
+* @returns The assembled host, or `undefined` when any row produced no answer or
+* names a path the floor does not declare, or when a host-owned path is absent.
+*
+* @remarks
+* The one place the host-owned all-or-nothing rule is decided, so no verb
+* restates it. The host surface contributes one baseline: a fill carries live
+* bytes for every path that surface writes, or it is nothing. A row that failed,
+* went missing, names an undeclared path, or leaves a host-owned path absent
+* answers `undefined`. Deferred paths are presence-only and retain the installed
+* floor bytes that their catalog or mirror surface owns; repair never writes
+* those floor bytes. One `Host` can therefore carry live host bytes beside floor
+* bytes without mixing baselines within a surface.
+*
+* The emitted entries keep the release's own order and its storage and
+* executable declarations, and carry digests recomputed over the bytes the fill
+* actually holds. That is what lets a reader verify the value against itself,
+* and it is why an undeclared path is refused rather than added: membership
+* moves with a release, never with a fetch.
+*
+* @example
+* ```ts
+* import { filesToHost } from '@orkestrel/scaffold/server'
+*
+* filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
+* // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+* ```
+*/
+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 (!isDeferredPath(file.path)) held.set(file.path, file.hex);
+	}
+	const entries = [];
+	const bytes = {};
+	for (const entry of floor.manifest.entries) {
+		const hex = isDeferredPath(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
+		if (hex === void 0) return void 0;
+		entries.push({
+			storage: entry.storage,
+			destination: entry.destination,
+			executable: entry.executable,
+			digest: hexToDigest(hex)
+		});
+		bytes[entry.destination] = hex;
+	}
+	return {
+		manifest: {
+			entries,
+			roots: floor.manifest.roots,
+			digest: computeManifestDigest(entries, floor.manifest.roots)
+		},
+		bytes
 	};
 }
 /**
+* Stage the named destinations of a value host into a private root.
+*
+* @param host - The host whose bytes are written, keyed by destination.
+* @param root - The private directory to fill; it must already be a directory
+* this process may write into.
+* @param destinations - The destinations to stage, each declared by `host`.
+* @returns The entry staged for each destination, in the order requested.
+* @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or a
+* storage name leaves it.
+* @throws `ScaffoldError('TARGET', …)` when a destination is one the host does
+* not declare, carries no bytes, or carries bytes that miss its declared digest.
+* @throws `ScaffoldError('WRITE', …)` when a file cannot be written or does not
+* read back as the bytes it was given.
+*
+* @remarks
+* Each file lands under the storage name the manifest declares and takes the
+* executable bit that manifest records, so a root filled from a value is the
+* same shape as one staged from a checkout and a reader cannot tell them apart.
+* That is what lets a mutation copy real files with real modes from bytes a
+* caller supplied, instead of degrading them to plain text writes.
+*
+* The bytes are digested before the write and the staged file after it, so a
+* value that disagrees with its own manifest is told apart from a write that
+* did not land.
+*
+* @example
+* ```ts
+* import { stageBytes } from '@orkestrel/scaffold/server'
+*
+* stageBytes(host, '/tmp/orkestrel-host-a1b2', ['scripts/codex.sh'])
+* // [{ storage: 'scripts/codex.sh', destination: 'scripts/codex.sh', executable: true, digest: '…' }]
+* ```
+*/
+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) {
+		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}`, {
+			host: root,
+			destination
+		});
+		if (hexToDigest(hex) !== entry.digest) throw new ScaffoldError("TARGET", `The host bytes for ${destination} miss its digest`, {
+			host: root,
+			destination
+		});
+		const full = resolveContainedPath(root, entry.storage);
+		if (full === void 0) throw new ScaffoldError("INVALID", `Host storage leaves its root at ${entry.storage}`, {
+			host: root,
+			storage: entry.storage
+		});
+		const written = attempt(() => {
+			mkdirSync(dirname(full), { recursive: true });
+			writeFileSync(full, Buffer.from(hex, "hex"), { flag: "wx" });
+			if (entry.executable) chmodSync(full, 493);
+		});
+		if (!written.success) throw new ScaffoldError("WRITE", `Host bytes could not be staged at ${entry.storage}`, {
+			host: root,
+			storage: entry.storage,
+			error: written.error
+		});
+		if (computeFileDigest(full) !== entry.digest) throw new ScaffoldError("WRITE", `Staged host bytes at ${entry.storage} did not read back`, {
+			host: root,
+			storage: entry.storage
+		});
+		staged.push(entry);
+	}
+	return staged;
+}
+/**
 * Stage a vendored host root from a real checkout.
 *
 * @param checkout - The checkout the vendored paths are read from.
@@ -1441,7 +1703,7 @@ function stageHost(checkout, host) {
 		missing
 	});
 	const stored = /* @__PURE__ */ new Set([MANIFEST_NAME]);
-	const entries = [];
+	const candidates = [];
 	for (const destination of vendored) {
 		const full = resolveContainedPath(source, destination);
 		if (full === void 0) throw new ScaffoldError("INVALID", `Vendored path leaves its checkout at ${destination}`, {
@@ -1460,9 +1722,9 @@ function stageHost(checkout, host) {
 			storage: entry.storage
 		});
 		stored.add(entry.storage);
-		entries.push(entry);
+		candidates.push(entry);
 	}
-	entries.sort((first, second) => first.storage < second.storage ? -1 : 1);
+	candidates.sort((first, second) => first.storage < second.storage ? -1 : 1);
 	roots.sort();
 	const root = resolve(host);
 	const established = attempt(() => mkdirSync(root, { recursive: true }));
@@ -1470,7 +1732,8 @@ function stageHost(checkout, host) {
 		host: root,
 		...established.success ? {} : { error: established.error }
 	});
-	for (const entry of entries) {
+	const entries = [];
+	for (const entry of candidates) {
 		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}`, {
@@ -1489,6 +1752,15 @@ function stageHost(checkout, host) {
 			storage: entry.storage,
 			error: copied.error
 		});
+		const digest = computeFileDigest(destination);
+		if (digest === void 0) throw new ScaffoldError("WRITE", `Vendored file could not be verified at ${entry.storage}`, {
+			host: root,
+			storage: entry.storage
+		});
+		entries.push({
+			...entry,
+			digest
+		});
 	}
 	const manifest = {
 		entries,
@@ -1510,6 +1782,67 @@ function stageHost(checkout, host) {
 	return entries;
 }
 /**
+* Stages the committed inventory of the files a vendored host carries.
+*
+* @param checkout - The checkout whose vendored paths are inventoried.
+* @param path - The host path where the JSON inventory is written.
+* @returns The validated manifest written to `path`.
+* @throws `ScaffoldError('INVALID', …)` when `path` is not a host path.
+* @throws `ScaffoldError('WRITE', …)` when a temporary host or the inventory
+* cannot be written or removed.
+* @throws `ScaffoldError('TARGET', …)` when the staged inventory does not read
+* back through the manifest validator.
+*
+* @remarks
+* Uses {@link stageHost} as the single vendored-path expansion. The temporary
+* host supplies the same entries, roots, per-file digests, and membership
+* digest as the published host while the requested output remains one JSON
+* file.
+*
+* @example
+* ```ts
+* import { stageInventory } from '@orkestrel/scaffold/server'
+*
+* stageInventory(process.cwd(), 'host.json') // the committed host inventory
+* ```
+*/
+function stageInventory(checkout, path) {
+	if (!isFilesystemPath(path)) throw new ScaffoldError("INVALID", "Inventory destination is not a host path", { path });
+	const temporary = attempt(() => mkdtempSync(join(tmpdir(), "orkestrel-scaffold-host-")));
+	if (!temporary.success) throw new ScaffoldError("WRITE", "Inventory staging root could not be established", {
+		path,
+		error: temporary.error
+	});
+	const staged = attempt(() => {
+		stageHost(checkout, temporary.value);
+		const manifest = readHostManifest(temporary.value);
+		if (manifest === void 0) throw new ScaffoldError("TARGET", "The staged inventory carries no manifest", { path });
+		const target = resolve(path);
+		const published = attempt(() => {
+			mkdirSync(dirname(target), { recursive: true });
+			writeFileSync(target, `${JSON.stringify(manifest, null, "	")}\n`, "utf8");
+		});
+		if (!published.success) throw new ScaffoldError("WRITE", `Inventory could not be written at ${target}`, {
+			path: target,
+			error: published.error
+		});
+		const text = readFileText(dirname(target), basename(target), MAX_MANIFEST_BYTES);
+		const verified = text === void 0 ? void 0 : parseJSONAs(text, isHostManifest);
+		if (verified === void 0 || verified.digest !== computeManifestDigest(verified.entries, verified.roots)) throw new ScaffoldError("TARGET", `Inventory does not read back at ${target}`, { path: target });
+		return verified;
+	});
+	const removed = attempt(() => rmSync(temporary.value, {
+		recursive: true,
+		force: true
+	}));
+	if (!removed.success) throw new ScaffoldError("WRITE", `Inventory staging root could not be removed`, {
+		path: temporary.value,
+		error: removed.error
+	});
+	if (!staged.success) throw staged.error;
+	return staged.value;
+}
+/**
 * Capture one directory's physical identity.
 *
 * @param path - The resolved directory path to capture.
@@ -2195,6 +2528,12 @@ var WriteTransaction = class {
 * case, so a manifest naming `agents.md` for a stored `AGENTS.md` is refused on
 * a case-insensitive filesystem rather than silently resolved.
 *
+* That host arrives as a directory path or as a whole {@link Host} value, and
+* every verb reads one immutable host either way. A value is owned, verified
+* against its own membership and digests, and read in memory; a write fills it
+* into a private root and copies from there, so the executable declarations the
+* release fixed reach the target from either representation.
+*
 * What a mutation guarantees is exactly what {@link WriteTransaction}
 * guarantees, and no more: a caught failure part way through a commit rolls the
 * whole commit back, no destination ever receives half-written bytes, and a
@@ -2220,25 +2559,34 @@ var Materializer = class Materializer {
 	static #opening = "<!-- orkestrel:catalog -->";
 	static #closing = "<!-- /orkestrel:catalog -->";
 	#emitter;
-	#host;
+	#root;
+	#value;
 	#manifest;
 	#entries;
 	#destroyed = false;
 	/**
 	* Construct a materializer over one vendored host root.
 	*
-	* @param options - The vendored host root, the initial listeners, and the
-	* listener-error handler.
+	* @param options - The vendored host, in either representation, the initial
+	* listeners, and the listener-error handler.
 	* @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
 	* is not an option bag this materializer accepts, and `TARGET` when the host
-	* carries a manifest that cannot be read or does not match what it stores.
+	* carries a manifest that cannot be read, does not match what it stores, or
+	* is a value that does not agree with the bytes beside it.
 	*
 	* @remarks
-	* `host` defaults to this package's own vendored root, resolved from this
-	* module's own location so it never depends on the caller's working
-	* directory. A host carrying no manifest is read as a raw checkout and every
+	* A `host` path defaults to this package's own vendored root, resolved from
+	* this module's own location so it never depends on the caller's working
+	* directory. A root carrying no manifest is read as a raw checkout and every
 	* artifact maps onto it one to one.
 	*
+	* A `host` value is owned before it is read and then held immutable, so the
+	* bytes this check measured are the bytes every later read returns. It is
+	* verified the way a root is, against the same membership law: the manifest
+	* digest must cover the membership beside it, no two entries may claim one
+	* destination, and the fill must carry exactly one hashing byte string per
+	* declared entry.
+	*
 	* The host is read here rather than on first use, so a broken vendored root
 	* fails at construction where the caller can still act on it, and so nothing
 	* has to carry a second flag recording whether the read has happened yet.
@@ -2249,15 +2597,27 @@ var Materializer = class Materializer {
 			...options?.on === void 0 ? {} : { on: options.on },
 			...options?.error === void 0 ? {} : { error: options.error }
 		});
-		this.#host = options?.host ?? resolve(dirname(fileURLToPath(import.meta.url)), "../../host");
-		const read = attempt(() => readHostManifest(this.#host));
-		if (!read.success) throw this.#error("TARGET", "The vendored host carries a manifest that cannot be read.", {
-			host: this.#host,
-			error: read.error
-		});
-		this.#manifest = read.value;
-		this.#entries = new Map((read.value?.entries ?? []).map((entry) => [entry.destination, entry]));
-		if (read.value !== void 0) this.#reconcile(read.value);
+		const supplied = options?.host ?? readHostFloor();
+		if (supplied !== void 0 && !isFilesystemPath(supplied)) {
+			const value = this.#own(supplied);
+			this.#value = value;
+			this.#root = void 0;
+			this.#manifest = value.manifest;
+			this.#entries = new Map(value.manifest.entries.map((entry) => [entry.destination, entry]));
+			this.#verify(value);
+		} else {
+			const root = supplied;
+			this.#value = void 0;
+			this.#root = root;
+			const read = attempt(() => readHostManifest(root));
+			if (!read.success) throw this.#error("TARGET", "The vendored host carries a manifest that cannot be read.", {
+				host: root,
+				error: read.error
+			});
+			this.#manifest = read.value;
+			this.#entries = new Map((read.value?.entries ?? []).map((entry) => [entry.destination, entry]));
+			if (read.value !== void 0) this.#reconcile(read.value, root);
+		}
 	}
 	/** The materializer's observation channel. */
 	get emitter() {
@@ -2453,7 +2813,7 @@ var Materializer = class Materializer {
 	*
 	* @param plan - The compiled plan that decides which paths are foreign.
 	* @param audit - The preview returned by this materializer's `audit` method; it must agree with the candidate set this call re-derives.
-	* @param repository - The target's git state; only a tracked path is ever deleted.
+	* @param worktree - The target's git state; only a tracked path is ever deleted.
 	* @param target - The directory to delete from.
 	* @returns The paths removed.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
@@ -2474,11 +2834,11 @@ var Materializer = class Materializer {
 	* any foreign finding, including one the deletion itself would skip, because a
 	* preview stale anywhere is stale evidence.
 	*/
-	remove(plan, audit, repository, target) {
+	remove(plan, audit, worktree, target) {
 		this.#assertAlive();
 		const accepted = this.#accept(plan, isPlan, "plan");
 		const preview = this.#accept(audit, isAudit, "audit");
-		const state = this.#accept(repository, isRepository, "repository");
+		const state = this.#accept(worktree, isWorktree, "worktree");
 		const directory = this.#accept(target, isFilesystemPath, "target");
 		if (state.dirty.length > 0) throw this.#error("TARGET", `The target at ${directory} carries uncommitted changes.`, {
 			target: directory,
@@ -2521,20 +2881,41 @@ var Materializer = class Materializer {
 		this.#emitter.emit("destroy");
 		this.#emitter.destroy();
 	}
-	#reconcile(manifest) {
-		const walked = attempt(() => listFiles(this.#host));
+	#own(host) {
+		const owned = cloneValue(host);
+		if (isHost(owned)) return owned;
+		throw this.#error("INVALID", "The host argument is not the exact shape this materializer accepts.", { field: "host" });
+	}
+	#verify(host) {
+		const { entries, roots } = host.manifest;
+		if (host.manifest.digest !== computeManifestDigest(entries, roots)) throw this.#error("TARGET", "The vendored host manifest does not cover the membership beside it.");
+		if (this.#entries.size !== entries.length) throw this.#error("TARGET", "The vendored host manifest maps two files to one destination.");
+		if (new Set(entries.map((entry) => entry.storage)).size !== entries.length) throw this.#error("TARGET", "The vendored host manifest maps two destinations to one file.");
+		const held = Object.keys(host.bytes);
+		if (held.length !== entries.length) throw this.#error("TARGET", "The vendored host does not carry what its manifest declares.", {
+			held: held.length,
+			declared: entries.length
+		});
+		for (const entry of entries) {
+			const hex = host.bytes[entry.destination];
+			if (hex === void 0) throw this.#error("TARGET", `The vendored host carries no bytes for ${entry.destination}.`, { destination: entry.destination });
+			if (hexToDigest(hex) !== entry.digest) throw this.#error("TARGET", `The vendored host carries bytes for ${entry.destination} that miss its digest.`, { destination: entry.destination });
+		}
+	}
+	#reconcile(manifest, root) {
+		const walked = attempt(() => listFiles(root));
 		if (!walked.success) throw this.#error("TARGET", "The vendored host cannot be inventoried.", {
-			host: this.#host,
+			host: root,
 			error: walked.error
 		});
 		const declared = [...manifest.entries.map((entry) => entry.storage), "manifest.json"].sort();
 		const stored = walked.value;
 		if (stored.length !== declared.length || stored.some((name, index) => name !== declared[index])) throw this.#error("TARGET", "The vendored host does not store what its manifest declares.", {
-			host: this.#host,
+			host: root,
 			stored: stored.length,
 			declared: declared.length
 		});
-		if (this.#entries.size !== manifest.entries.length) throw this.#error("TARGET", "The vendored host manifest maps two files to one destination.", { host: this.#host });
+		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 = [];
@@ -2550,7 +2931,7 @@ var Materializer = class Materializer {
 			artifacts.push(...expanded);
 		}
 		if (remaining < 0) throw this.#error("TARGET", "The hydrated plan retains more bytes than one plan may.", {
-			host: this.#host,
+			host: this.#root,
 			limit: MAX_TOTAL_ARTIFACT_BYTES
 		});
 		return {
@@ -2584,7 +2965,8 @@ var Materializer = class Materializer {
 				continue;
 			}
 			if (this.#manifest !== void 0) continue;
-			const directory = resolveContainedPath(this.#host, source);
+			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];
@@ -2596,7 +2978,7 @@ var Materializer = class Materializer {
 		const matched = manifest.entries.filter((entry) => entry.destination === source || entry.destination.startsWith(`${source}/`));
 		const rooted = manifest.roots.some((root) => root === source || root.startsWith(`${source}/`));
 		if (matched.length === 0 && !rooted) throw this.#error("TARGET", `The vendored host does not carry ${source}.`, {
-			host: this.#host,
+			host: this.#root,
 			source
 		});
 		const expanded = [];
@@ -2607,29 +2989,30 @@ var Materializer = class Materializer {
 				expanded.push(this.#presence(artifact, path, entry.destination));
 				continue;
 			}
-			if (this.#deferred(path)) {
+			if (isDeferredPath(path)) {
 				expanded.push(this.#presence(artifact, path, entry.destination));
 				continue;
 			}
-			const hex = this.#read(entry.storage, budget);
+			const hex = this.#read(entry, budget);
 			budget -= hex.length / 2;
 			expanded.push(this.#hydrated(artifact, path, entry.destination, hex));
 		}
 		return expanded;
 	}
 	#expandRaw(artifact, source, remaining) {
-		const full = resolveContainedPath(this.#host, source);
+		const root = this.#root;
+		const full = root === void 0 ? void 0 : resolveContainedPath(root, source);
 		if (full === void 0) throw this.#error("TARGET", `The host source at ${source} leaves its root.`, {
-			host: this.#host,
+			host: this.#root,
 			source
 		});
 		if (isPhysicalFile(full)) {
 			if (WORKSPACE_OWNED_PATHS.includes(artifact.path)) return [this.#presence(artifact, artifact.path, source)];
-			if (this.#deferred(artifact.path)) return [this.#presence(artifact, artifact.path, source)];
-			return [this.#hydrated(artifact, artifact.path, source, this.#read(source, remaining))];
+			if (isDeferredPath(artifact.path)) return [this.#presence(artifact, artifact.path, source)];
+			return [this.#hydrated(artifact, artifact.path, source, this.#readRoot(source, remaining))];
 		}
 		if (!isPhysicalDirectory(full)) throw this.#error("TARGET", `The host source at ${source} is not a readable file.`, {
-			host: this.#host,
+			host: this.#root,
 			source
 		});
 		const expanded = [];
@@ -2641,11 +3024,11 @@ var Materializer = class Materializer {
 				expanded.push(this.#presence(artifact, path, destination));
 				continue;
 			}
-			if (this.#deferred(path)) {
+			if (isDeferredPath(path)) {
 				expanded.push(this.#presence(artifact, path, destination));
 				continue;
 			}
-			const hex = this.#read(destination, budget);
+			const hex = this.#readRoot(destination, budget);
 			budget -= hex.length / 2;
 			expanded.push(this.#hydrated(artifact, path, destination, hex));
 		}
@@ -2669,15 +3052,12 @@ var Materializer = class Materializer {
 		const source = artifact.source ?? artifact.path;
 		if (destination === source) return artifact.path;
 		if (!destination.startsWith(`${source}/`)) throw this.#error("TARGET", `The vendored destination ${destination} is outside ${source}.`, {
-			host: this.#host,
+			host: this.#root,
 			source,
 			destination
 		});
 		return `${artifact.path}/${destination.slice(source.length + 1)}`;
 	}
-	#deferred(path) {
-		return path === CATALOG_AGENT_PATH || path.startsWith("guides/") && path.endsWith(".md");
-	}
 	#presence(artifact, path, destination) {
 		return {
 			path,
@@ -2699,10 +3079,20 @@ var Materializer = class Materializer {
 			hex
 		};
 	}
-	#read(storage, budget) {
-		const hex = readFileHex(this.#host, storage, Math.max(0, Math.min(MAX_ARTIFACT_BYTES, budget)));
+	#read(entry, budget) {
+		const held = this.#value?.bytes[entry.destination];
+		if (held === void 0) return this.#readRoot(entry.storage, budget);
+		if (held.length / 2 > Math.max(0, Math.min(MAX_ARTIFACT_BYTES, budget))) throw this.#error("TARGET", `The vendored host cannot be read at ${entry.destination}.`, {
+			destination: entry.destination,
+			limit: MAX_ARTIFACT_BYTES
+		});
+		return held;
+	}
+	#readRoot(storage, budget) {
+		const root = this.#root;
+		const hex = root === void 0 ? void 0 : readFileHex(root, storage, Math.max(0, Math.min(MAX_ARTIFACT_BYTES, budget)));
 		if (hex === void 0) throw this.#error("TARGET", `The vendored host cannot be read at ${storage}.`, {
-			host: this.#host,
+			host: this.#root,
 			storage
 		});
 		return hex;
@@ -2808,20 +3198,49 @@ var Materializer = class Materializer {
 			skipped,
 			removed: []
 		});
-		const transaction = this.#open(target, paths, preconditions);
-		const staged = attempt(() => {
-			for (const artifact of writes) if (artifact.origin === "host") this.#copy(transaction, artifact);
-			else transaction.write(artifact.path, artifact.content);
-			for (const path of directories) transaction.establish(path);
-		});
-		const written = this.#close(transaction, staged, target);
-		for (const path of written) this.#emitter.emit("write", path);
-		return this.#finish({
-			target,
-			written,
-			skipped,
-			removed: []
+		const filled = this.#fill(writes);
+		try {
+			const transaction = this.#open(target, paths, preconditions);
+			const staged = attempt(() => {
+				for (const artifact of writes) if (artifact.origin === "host") this.#copy(transaction, artifact, filled ?? this.#root);
+				else transaction.write(artifact.path, artifact.content);
+				for (const path of directories) transaction.establish(path);
+			});
+			const written = this.#close(transaction, staged, target);
+			for (const path of written) this.#emitter.emit("write", path);
+			return this.#finish({
+				target,
+				written,
+				skipped,
+				removed: []
+			});
+		} finally {
+			if (filled !== void 0) rmSync(filled, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	#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);
+		}
+		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 });
+		const root = opened.value;
+		const stored = attempt(() => stageBytes(value, root, [...destinations]));
+		if (stored.success) return root;
+		rmSync(root, {
+			recursive: true,
+			force: true
 		});
+		this.#emitter.emit("error", stored.error);
+		throw stored.error;
 	}
 	#purge(target, removals, skipped, preconditions) {
 		if (removals.length === 0) return this.#finish({
@@ -2865,13 +3284,13 @@ var Materializer = class Materializer {
 		this.#emitter.emit("error", committed.error);
 		throw committed.error;
 	}
-	#copy(transaction, artifact) {
+	#copy(transaction, artifact, root) {
 		const destination = artifact.source ?? artifact.path;
 		const entry = this.#entries.get(destination);
 		const storage = entry === void 0 ? destination : entry.storage;
-		const source = resolveContainedPath(this.#host, storage);
+		const source = root === void 0 ? void 0 : resolveContainedPath(root, storage);
 		if (source === void 0) throw this.#error("TARGET", `The vendored source at ${storage} leaves its root.`, {
-			host: this.#host,
+			host: root,
 			storage
 		});
 		transaction.copy(artifact.path, source, entry?.executable === true);
@@ -2968,6 +3387,11 @@ var Materializer = class Materializer {
 * there is no fleet to report, so an unreachable or malformed list is a coded
 * `FETCH` failure.
 *
+* The vendored-file inventory is the other read a whole call rests on, and it
+* fails the other way: it fails every row of its call rather than throwing, so
+* the caller receives one whole dead answer it can replace with one whole
+* baseline instead of a mixture it would have to reconcile.
+*
 * Requests are unauthenticated because every fleet repository is public, and
 * they follow no redirect, so a misconfigured or hostile endpoint cannot move a
 * read to another host. Each one is bounded by its endpoint's timeout and by the
@@ -2988,19 +3412,20 @@ var Materializer = class Materializer {
 * ```
 */
 var Upstream = class Upstream {
-	static #defaultGuide = "https://raw.githubusercontent.com";
+	static #defaultRepository = "https://raw.githubusercontent.com";
 	static #defaultRegistry = "https://registry.npmjs.org";
 	static #defaultBranch = "main";
 	static #defaultTimeout = 1e4;
 	static #defaultConcurrency = 6;
 	static #defaultRetries = 0;
 	static #scope = "orkestrel";
+	static #vendor = "scaffold";
 	static #unreadable = "the answer carries no readable latest version";
 	static #packument = "application/vnd.npm.install-v1+json";
 	#emitter;
-	#guideBase;
-	#guideBranch;
-	#guideTimeout;
+	#repositoryBase;
+	#repositoryBranch;
+	#repositoryTimeout;
 	#registryBase;
 	#registryTimeout;
 	#concurrency;
@@ -3010,7 +3435,7 @@ var Upstream = class Upstream {
 	#controller = new AbortController();
 	#destroyed = false;
 	/**
-	* Construct a reader over one guide host and one registry.
+	* Construct a reader over one raw content host and one registry.
 	*
 	* @param options - The endpoints, the request bounds, the initial
 	* listeners, and the listener-error handler.
@@ -3034,9 +3459,9 @@ var Upstream = class Upstream {
 			...options?.on === void 0 ? {} : { on: options.on },
 			...options?.error === void 0 ? {} : { error: options.error }
 		});
-		this.#guideBase = this.#endpoint(options?.guides?.base ?? Upstream.#defaultGuide, "guides");
-		this.#guideBranch = options?.guides?.branch ?? Upstream.#defaultBranch;
-		this.#guideTimeout = options?.guides?.timeout ?? Upstream.#defaultTimeout;
+		this.#repositoryBase = this.#endpoint(options?.repository?.base ?? Upstream.#defaultRepository, "repository");
+		this.#repositoryBranch = options?.repository?.branch ?? Upstream.#defaultBranch;
+		this.#repositoryTimeout = options?.repository?.timeout ?? Upstream.#defaultTimeout;
 		this.#registryBase = this.#endpoint(options?.registry?.base ?? Upstream.#defaultRegistry, "registry");
 		this.#registryTimeout = options?.registry?.timeout ?? Upstream.#defaultTimeout;
 		this.#concurrency = options?.concurrency ?? Upstream.#defaultConcurrency;
@@ -3114,6 +3539,54 @@ var Upstream = class Upstream {
 		return this.#gather(accepted, (name) => this.#mirror(name, observed, allowance));
 	}
 	/**
+	* Read each named vendored file from the repository, beside the target bytes it answers for.
+	*
+	* @param paths - The target-relative vendored paths to read.
+	* @param current - The target files as exact bytes, keyed by the same paths.
+	* @returns One file verdict per path, in input order.
+	* @throws {@link ScaffoldError} coded `INVALID` when `paths` is not a bounded
+	* list of target-relative paths or `current` is not a snapshot, and
+	* `DESTROYED` when the reader is torn down before or during the call.
+	*
+	* @remarks
+	* The committed inventory is read once per call and decides every row, so a
+	* path whose declared digest already matches the target's own bytes is `found`
+	* without a request and the call spends nothing on it. An inventory that
+	* produces no answer fails every row of the call rather than leaving some rows
+	* live and some dead, which is what leaves the caller one whole baseline to
+	* fall back to. A path the inventory does not name is `missing`.
+	*
+	* A fetched response's decoded content is verified against the digest the
+	* inventory declares for that path, before any character decoding. Transport
+	* encoding is transparent and does not enter the comparison, so content that
+	* does not hash to the inventory's claim fails its row rather than reaching a
+	* write. That is integrity against a single committed baseline, not
+	* authenticity: it detects truncated, substituted, or stale content, and it
+	* says nothing about who published the inventory.
+	*
+	* A guide mirror is never answered here whatever the caller asks for and
+	* whatever the target holds, because those bytes belong to `fetch` and to the
+	* mirror verb that writes them.
+	*
+	* @example
+	* ```ts
+	* import { Upstream } from '@orkestrel/scaffold/server'
+	*
+	* const upstream = new Upstream()
+	* await upstream.read(['AGENTS.md'], { 'AGENTS.md': '2320416745' })
+	* upstream.destroy()
+	* ```
+	*/
+	async read(paths, current) {
+		this.#assertAlive();
+		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 inventory = await this.#inventory(allowance);
+		return this.#gather(accepted, (path) => this.#file(path, inventory, observed, allowance));
+	}
+	/**
 	* Catalog the published fleet from the registry's organization package list.
 	*
 	* @returns One row per published package, sorted by name.
@@ -3190,14 +3663,14 @@ var Upstream = class Upstream {
 		return parsed.href.replace(/\/+$/u, "");
 	}
 	async #release(dependency, allowance) {
-		const outcome = await this.#read(this.#registryURL(dependency.name), this.#registryTimeout, allowance, Upstream.#packument);
+		const outcome = await this.#readWithRetries(this.#registryURL(dependency.name), this.#registryTimeout, allowance, Upstream.#packument);
 		const latest = outcome.lookup === "found" ? this.#releaseVersion(outcome.content, dependency.range) : void 0;
 		const tagged = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
 		const major = tagged === void 0 ? void 0 : extractVersion(tagged)?.[0];
 		const release = latest === void 0 ? {
 			name: dependency.name,
 			range: dependency.range,
-			lookup: outcome.lookup === "missing" ? "missing" : "failed",
+			lookup: outcome.lookup === "found" ? "unmatched" : outcome.lookup,
 			note: outcome.lookup === "found" ? Upstream.#unreadable : outcome.note,
 			...major === void 0 ? {} : { major }
 		} : {
@@ -3212,7 +3685,7 @@ var Upstream = class Upstream {
 	}
 	async #mirror(name, current, allowance) {
 		const path = nameToGuide(name);
-		const outcome = await this.#read(this.#guideURL(name), this.#guideTimeout, allowance);
+		const outcome = await this.#readWithRetries(this.#guideURL(name), this.#repositoryTimeout, allowance);
 		const observed = current[path];
 		const mirror = outcome.lookup === "found" ? {
 			name,
@@ -3230,8 +3703,102 @@ var Upstream = class Upstream {
 		this.#emitter.emit("mirror", mirror);
 		return mirror;
 	}
+	async #file(path, inventory, current, allowance) {
+		const file = await this.#answer(path, inventory, current[path], allowance);
+		this.#emitter.emit("file", file);
+		return file;
+	}
+	async #answer(path, inventory, observed, allowance) {
+		const carried = observed === void 0 ? {} : { observed };
+		if (inventory.lookup !== "found") return {
+			path,
+			lookup: inventory.lookup,
+			note: inventory.note,
+			...carried
+		};
+		if (inferGroup(path) === "guides") return {
+			path,
+			lookup: "missing",
+			note: `${path} is a guide mirror the fleet serves`,
+			...carried
+		};
+		if (inventory.duplicates.has(path)) return {
+			path,
+			lookup: "failed",
+			note: `the inventory names ${path} more than once`,
+			...carried
+		};
+		const digest = inventory.digests.get(path);
+		if (digest === void 0) return {
+			path,
+			lookup: "missing",
+			note: `the inventory does not name ${path}`,
+			...carried
+		};
+		if (observed !== void 0 && hexToDigest(observed) === digest) return {
+			path,
+			lookup: "found",
+			hex: observed,
+			...carried
+		};
+		const outcome = await this.#readWithRetries(this.#vendorURL(path), this.#repositoryTimeout, allowance, void 0, true);
+		if (outcome.lookup !== "found") return {
+			path,
+			lookup: outcome.lookup,
+			note: outcome.note,
+			...carried
+		};
+		if (hexToDigest(outcome.hex) !== digest) return {
+			path,
+			lookup: "failed",
+			note: `the bytes served for ${path} do not match the digest the inventory declares`,
+			...carried
+		};
+		return {
+			path,
+			lookup: "found",
+			hex: outcome.hex,
+			...carried
+		};
+	}
+	async #inventory(allowance) {
+		const url = this.#vendorURL(HOST_INVENTORY_PATH);
+		const empty = {
+			digests: /* @__PURE__ */ new Map(),
+			duplicates: /* @__PURE__ */ new Set()
+		};
+		const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
+		if (outcome.lookup !== "found") return {
+			...empty,
+			lookup: outcome.lookup,
+			note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`
+		};
+		const manifest = parseJSONAs(outcome.content, isHostManifest);
+		if (manifest === void 0) return {
+			...empty,
+			lookup: "failed",
+			note: `the vendored inventory at ${url} is not a readable manifest`
+		};
+		if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots)) return {
+			...empty,
+			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,
+			note: ""
+		};
+	}
 	async #entry(name, allowance) {
-		const outcome = await this.#read(this.#registryURL(name), this.#registryTimeout, allowance, Upstream.#packument);
+		const outcome = await this.#readWithRetries(this.#registryURL(name), this.#registryTimeout, allowance, Upstream.#packument);
 		const version = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
 		if (version !== void 0) return {
 			name,
@@ -3241,7 +3808,7 @@ var Upstream = class Upstream {
 		};
 		return {
 			name,
-			lookup: outcome.lookup === "missing" ? "missing" : "failed",
+			lookup: outcome.lookup === "found" ? "unmatched" : outcome.lookup,
 			note: outcome.lookup === "found" ? Upstream.#unreadable : outcome.note
 		};
 	}
@@ -3269,7 +3836,7 @@ var Upstream = class Upstream {
 	}
 	async #packages(allowance) {
 		const url = `${this.#registryBase}/-/org/${Upstream.#scope}/package`;
-		const outcome = await this.#read(url, this.#registryTimeout, allowance);
+		const outcome = await this.#readWithRetries(url, this.#registryTimeout, allowance);
 		if (outcome.lookup !== "found") throw this.#error("FETCH", `The organization package list at ${url} produced no answer.`, {
 			url,
 			note: outcome.note
@@ -3315,15 +3882,22 @@ var Upstream = class Upstream {
 		return `${this.#registryBase}/${encodeURIComponent(name).replaceAll("%40", "@")}`;
 	}
 	#guideURL(name) {
-		const branch = this.#guideBranch.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+		const branch = this.#encode(this.#repositoryBranch);
 		const repository = encodeURIComponent(name.slice(name.lastIndexOf("/") + 1));
-		return `${this.#guideBase}/${Upstream.#scope}/${repository}/refs/heads/${branch}/${nameToGuide(name)}`;
+		return `${this.#repositoryBase}/${Upstream.#scope}/${repository}/refs/heads/${branch}/${nameToGuide(name)}`;
+	}
+	#vendorURL(path) {
+		const branch = this.#encode(this.#repositoryBranch);
+		return `${this.#repositoryBase}/${Upstream.#scope}/${Upstream.#vendor}/refs/heads/${branch}/${this.#encode(path)}`;
 	}
-	async #read(url, timeout, allowance, accept) {
+	#encode(path) {
+		return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+	}
+	async #readWithRetries(url, timeout, allowance, accept, binary = false) {
 		let note = "";
-		for (let attempt = 0; attempt <= this.#retries; attempt += 1) {
+		for (let round = 0; round <= this.#retries; round += 1) {
 			this.#assertAlive();
-			const outcome = await this.#request(url, timeout, allowance, accept);
+			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;
 		}
@@ -3331,18 +3905,29 @@ var Upstream = class Upstream {
 			url,
 			note
 		});
-		return {
+		return binary ? {
 			lookup: "failed",
-			content: "",
+			hex: "",
 			note
-		};
-	}
-	async #request(url, timeout, allowance, accept) {
-		if (allowance.remaining <= 0) return {
+		} : {
 			lookup: "failed",
 			content: "",
-			note: `the call spent its ${String(this.#budget)}-byte allowance`
+			note
 		};
+	}
+	async #request(url, timeout, allowance, accept, binary = false) {
+		if (allowance.remaining <= 0) {
+			const note = `the call spent its ${String(this.#budget)}-byte allowance`;
+			return binary ? {
+				lookup: "failed",
+				hex: "",
+				note
+			} : {
+				lookup: "failed",
+				content: "",
+				note
+			};
+		}
 		try {
 			const response = await fetch(url, {
 				signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
@@ -3351,7 +3936,11 @@ var Upstream = class Upstream {
 			});
 			if (response.status === 404) {
 				await response.body?.cancel();
-				return {
+				return binary ? {
+					lookup: "missing",
+					hex: "",
+					note: "HTTP 404"
+				} : {
 					lookup: "missing",
 					content: "",
 					note: "HTTP 404"
@@ -3359,39 +3948,61 @@ var Upstream = class Upstream {
 			}
 			if (response.status >= 300 && response.status < 400) {
 				await response.body?.cancel();
-				return {
+				const note = `HTTP ${String(response.status)}, and a redirect is never followed`;
+				return binary ? {
+					lookup: "failed",
+					hex: "",
+					note
+				} : {
 					lookup: "failed",
 					content: "",
-					note: `HTTP ${String(response.status)}, and a redirect is never followed`
+					note
 				};
 			}
 			if (!response.ok) {
 				await response.body?.cancel();
-				return {
+				const note = `HTTP ${String(response.status)}`;
+				return binary ? {
+					lookup: "failed",
+					hex: "",
+					note
+				} : {
 					lookup: "failed",
 					content: "",
-					note: `HTTP ${String(response.status)}`
+					note
 				};
 			}
-			return await this.#body(response, allowance);
+			return binary ? await this.#body(response, allowance, true) : await this.#body(response, allowance);
 		} catch (error) {
 			this.#assertAlive();
-			return {
+			const note = this.#note(error);
+			return binary ? {
+				lookup: "failed",
+				hex: "",
+				note
+			} : {
 				lookup: "failed",
 				content: "",
-				note: this.#note(error)
+				note
 			};
 		}
 	}
-	async #body(response, allowance) {
+	async #body(response, allowance, binary = false) {
 		const body = response.body;
-		if (body === null) return {
-			lookup: "failed",
-			content: "",
-			note: `HTTP ${String(response.status)}, and the answer carries no body`
-		};
+		if (body === null) {
+			const note = `HTTP ${String(response.status)}, and the answer carries no body`;
+			return binary ? {
+				lookup: "failed",
+				hex: "",
+				note
+			} : {
+				lookup: "failed",
+				content: "",
+				note
+			};
+		}
 		const reader = body.getReader();
-		const decoder = new TextDecoder("utf-8", { fatal: true });
+		const decoder = binary ? void 0 : new TextDecoder("utf-8", { fatal: true });
 		const chunks = [];
 		let total = 0;
 		try {
@@ -3402,30 +4013,44 @@ var Upstream = class Upstream {
 				allowance.remaining -= chunk.value.byteLength;
 				if (total > this.#limit) {
 					await reader.cancel();
-					return {
+					const note = `the response passed the ${String(this.#limit)}-byte response limit`;
+					return binary ? {
+						lookup: "failed",
+						hex: "",
+						note
+					} : {
 						lookup: "failed",
 						content: "",
-						note: `the response passed the ${String(this.#limit)}-byte response limit`
+						note
 					};
 				}
 				if (allowance.remaining < 0) {
 					await reader.cancel();
-					return {
+					const note = `the call spent its ${String(this.#budget)}-byte allowance`;
+					return binary ? {
+						lookup: "failed",
+						hex: "",
+						note
+					} : {
 						lookup: "failed",
 						content: "",
-						note: `the call spent its ${String(this.#budget)}-byte allowance`
+						note
 					};
 				}
-				chunks.push(decoder.decode(chunk.value, { stream: true }));
+				chunks.push(decoder === void 0 ? Buffer.from(chunk.value).toString("hex") : decoder.decode(chunk.value, { stream: true }));
 			}
-			chunks.push(decoder.decode());
+			if (decoder !== void 0) chunks.push(decoder.decode());
 		} catch (error) {
 			await reader.cancel().catch(() => void 0);
 			throw error;
 		} finally {
 			reader.releaseLock();
 		}
-		return {
+		return binary ? {
+			lookup: "found",
+			hex: chunks.join(""),
+			note: ""
+		} : {
 			lookup: "found",
 			content: chunks.join(""),
 			note: ""
@@ -3480,6 +4105,6 @@ var Upstream = class Upstream {
 	}
 };
 //#endregion
-export { BRANCH_PATTERN, 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, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHostManifest, isInventory, isManifestEntry, isMaterializerHooks, isMaterializerOptions, isMirrors, isPhysicalDirectory, isPhysicalFile, isRepository, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, readAnchor, readExpectation, readFileHex, readFileText, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageHost };
+export { BRANCH_PATTERN, 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, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
 
 //# sourceMappingURL=index.js.map