@orkestrel/scaffold 0.0.101 → 0.0.102

package/dist/src/server/index.d.ts

@@ -40,6 +40,57 @@ export declare interface BytesReadResult {
     readonly note: string;
 }
 
+/**
+ * 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
+ * ```
+ */
+export declare function climbRealPath(current: string, pending: readonly string[], depth: number): string | undefined;
+
+/**
+ * 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
+ * ```
+ */
+export declare function collectIndexed<TResult>(entries: ReadonlyArray<readonly [number, TResult]>): readonly TResult[];
+
 /**
  * Computes the SHA-256 digest of text.
  *
@@ -745,6 +796,29 @@ export declare function isVacant(target: string): boolean;
  */
 export declare const isWorktree: Guard<Worktree>;
 
+/**
+ * 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']
+ * ```
+ */
+export declare function listAncestors(path: string, limit?: number): readonly string[];
+
 /**
  * Lists the canon paths a target holds, filtered to a plan's groups.
  *
@@ -1627,809 +1701,727 @@ export declare class Materializer implements MaterializerInterface {
            export declare function pruneEmptiedDirectories(target: string, removed: readonly string[]): readonly string[];
 
            /**
-            * Represents the byte allowance one whole upstream call spends across every read it makes.
-            *
-            * @remarks
-            * `remaining` is deliberately mutable, and it is the one member of this module's
-            * contracts that is. The carrier is what makes `budget` a bound on a call rather
-            * than on a request: each read subtracts what it consumed from the same object,
-            * so many small answers exhaust the call exactly as one oversized answer does.
-            * Each call constructs its own carrier from `budget`, because concurrent calls
-            * own separate budgets and must not spend each other's.
-            */
-           export declare interface ReadAllowance {
-               remaining: number;
-           }
-
-           /**
-            * Captures one directory's physical identity.
-            *
-            * @param path - The resolved directory path to capture.
-            * @returns The anchor, or `undefined` when the path is not a physical directory.
+            * Represents the byte allowance one upstream call spends across every read it makes.
             *
             * @remarks
-            * Native bigint device and inode values preserve the filesystem identity without
-            * numeric rounding. Device and inode rather than the path, because the path can
-            * be swapped underneath a write. An anchor captured before a mutation and
-            * checked again after it proves the directory written into sits where the
-            * inspected one sat, not that it is the one that was inspected.
+            * 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 { readAnchor } from '@orkestrel/scaffold/server'
+            * import { ReadAllowance } from '@orkestrel/scaffold/server'
             *
-            * const anchor = readAnchor(process.cwd())
-            * anchor !== undefined && typeof anchor.device === 'bigint' && typeof anchor.inode === 'bigint' // true for a physical directory
+            * const allowance = new ReadAllowance(1_024)
+            * allowance.spend(1_000)
+            * allowance.remaining // 24
             * ```
             */
-           export declare function readAnchor(path: string): WriteAnchor | undefined;
+           export declare class ReadAllowance implements ReadAllowanceInterface {
+               #private;
+               /**
+                * 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: number);
+                /** The bytes the call has left; negative once a read overshoots the budget. */
+                get remaining(): number;
+                /**
+                 * 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: number): void;
+                }
 
-           /**
-            * Captures what one destination holds before a write.
-            *
-            * @param path - The resolved destination path to capture.
-            * @returns The expectation, or `undefined` when the destination is a link or a
-            * shape this package will not write over.
-            *
-            * @remarks
-            * Absence is a captured state rather than a failure, because most writes expect
-            * exactly that. Each shape carries only the facts it supplies: a directory
-            * carries its identity, a file carries its identity, size, and bytes, and an
-            * absent destination carries nothing at all. A file past the artifact ceiling
-            * carries no digest and is bound by its identity, size, and modification time
-            * alone, which is the strongest honest claim about bytes nobody read.
-            *
-            * @example
-            * ```ts
-            * import { readExpectation } from '@orkestrel/scaffold/server'
-            *
-            * readExpectation('/tmp/project/absent.md') // { path: …, shape: 'absent' }
-            * ```
-            */
-           export declare function readExpectation(path: string): WriteExpectation | undefined;
+                /**
+                 * Describes the byte allowance one upstream call spends across every read it makes.
+                 *
+                 * @remarks
+                 * `remaining` is the budget less every byte spent, and it goes negative once a
+                 * read overshoots, so a caller tells a call that has nothing left (`remaining`
+                 * at or below zero) from one that spent past its budget (`remaining` below zero).
+                 */
+                export declare interface ReadAllowanceInterface {
+                    /** The bytes the call has left; negative once a read overshoots the budget. */
+                    readonly remaining: number;
+                    /**
+                     * Spends bytes a read consumed from the allowance.
+                     *
+                     * @param bytes - The decoded bytes the read consumed.
+                     * @returns Nothing.
+                     */
+                    spend(bytes: number): void;
+                }
 
-           /**
-            * Reads one contained file as its exact bytes in lowercase hexadecimal.
-            *
-            * @param root - The containing host directory.
-            * @param path - The portable root-relative file path.
-            * @param limit - The most bytes this read accepts; the artifact ceiling by default.
-            * @returns The exact bytes as hexadecimal, or `undefined` when the file is
-            * absent, is not a physical readable file, is past `limit`, or moved while it
-            * was being read.
-            * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
-            * `path` leaves `root`.
-            *
-            * @remarks
-            * Hexadecimal rather than text, because this is what a byte comparison is stated
-            * in everywhere in this package: a plan's artifact, an audit finding, and a
-            * snapshot all compare as the same digits. The file's identity and size are
-            * measured before and after the read, and one extra byte is requested past the
-            * declared size, so a file that grew or was replaced mid-read answers
-            * `undefined` rather than half of one file and half of another.
-            *
-            * @example
-            * ```ts
-            * import { readFileHex } from '@orkestrel/scaffold/server'
-            *
-            * readFileHex('/tmp/project', 'AGENTS.md') // '2320416765…'
-            * ```
-            */
-           export declare function readFileHex(root: string, path: string, limit?: number): string | undefined;
+                /**
+                 * Captures one directory's physical identity.
+                 *
+                 * @param path - The resolved directory path to capture.
+                 * @returns The anchor, or `undefined` when the path is not a physical directory.
+                 *
+                 * @remarks
+                 * Native bigint device and inode values preserve the filesystem identity without
+                 * numeric rounding. Device and inode rather than the path, because the path can
+                 * be swapped underneath a write. An anchor captured before a mutation and
+                 * checked again after it proves the directory written into sits where the
+                 * inspected one sat, not that it is the one that was inspected.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readAnchor } from '@orkestrel/scaffold/server'
+                 *
+                 * const anchor = readAnchor(process.cwd())
+                 * anchor !== undefined && typeof anchor.device === 'bigint' && typeof anchor.inode === 'bigint' // true for a physical directory
+                 * ```
+                 */
+                export declare function readAnchor(path: string): WriteAnchor | undefined;
 
-           /**
-            * Reads one contained file as bounded UTF-8 text.
-            *
-            * @param root - The containing host directory.
-            * @param path - The portable root-relative file path.
-            * @param limit - The most bytes this read accepts; the artifact ceiling by default.
-            * @returns The decoded text, or `undefined` when {@link readFileHex} answers
-            * nothing or the bytes are not valid UTF-8.
-            * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
-            * `path` leaves `root`.
-            *
-            * @remarks
-            * Decoding is strict, so a file carrying an invalid sequence answers `undefined`
-            * rather than text carrying replacement characters. That matters because the
-            * text is parsed next: a manifest silently repaired into valid JSON by lossy
-            * decoding would be trusted.
-            *
-            * @example
-            * ```ts
-            * import { readFileText } from '@orkestrel/scaffold/server'
-            *
-            * readFileText('/tmp/project', 'package.json') // '{ "name": "@orkestrel/router", … }'
-            * ```
-            */
-           export declare function readFileText(root: string, path: string, limit?: number): string | undefined;
+                /**
+                 * Captures what one destination holds before a write.
+                 *
+                 * @param path - The resolved destination path to capture.
+                 * @returns The expectation, or `undefined` when the destination is a link or a
+                 * shape this package will not write over.
+                 *
+                 * @remarks
+                 * Absence is a captured state rather than a failure, because most writes expect
+                 * exactly that. Each shape carries only the facts it supplies: a directory
+                 * carries its identity, a file carries its identity, size, and bytes, and an
+                 * absent destination carries nothing at all. A file past the artifact ceiling
+                 * carries no digest and is bound by its identity, size, and modification time
+                 * alone, which is the strongest honest claim about bytes nobody read.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readExpectation } from '@orkestrel/scaffold/server'
+                 *
+                 * readExpectation('/tmp/project/absent.md') // { path: …, shape: 'absent' }
+                 * ```
+                 */
+                export declare function readExpectation(path: string): WriteExpectation | undefined;
 
-           /**
-            * 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
-            * ```
-            */
-           export declare function readHostFloor(root?: string): Host;
+                /**
+                 * Reads one contained file as its exact bytes in lowercase hexadecimal.
+                 *
+                 * @param root - The containing host directory.
+                 * @param path - The portable root-relative file path.
+                 * @param limit - The most bytes this read accepts; the artifact ceiling by default.
+                 * @returns The exact bytes as hexadecimal, or `undefined` when the file is
+                 * absent, is not a physical readable file, is past `limit`, or moved while it
+                 * was being read.
+                 * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
+                 * `path` leaves `root`.
+                 *
+                 * @remarks
+                 * Hexadecimal rather than text, because this is what a byte comparison is stated
+                 * in everywhere in this package: a plan's artifact, an audit finding, and a
+                 * snapshot all compare as the same digits. The file's identity and size are
+                 * measured before and after the read, and one extra byte is requested past the
+                 * declared size, so a file that grew or was replaced mid-read answers
+                 * `undefined` rather than half of one file and half of another.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readFileHex } from '@orkestrel/scaffold/server'
+                 *
+                 * readFileHex('/tmp/project', 'AGENTS.md') // '2320416765…'
+                 * ```
+                 */
+                export declare function readFileHex(root: string, path: string, limit?: number): string | undefined;
 
-           /**
-            * Reads 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
-            * read, is not the declared shape, or does not match its own membership.
-            *
-            * @remarks
-            * The failures are held apart deliberately. A host with no manifest is a
-            * raw checkout, and a caller reads it by mapping each path one to one. A host
-            * with a manifest that does not verify is a staged host that has been edited,
-            * and answering `undefined` there would degrade it to that same one-to-one
-            * mapping — which is how an edited manifest would get a caller to read files it
-            * never declared. So absence answers and corruption throws.
-            *
-            * Verification here is the manifest's own self-consistency: the digest against
-            * the exact membership beside it. Whether that membership matches the files
-            * actually stored is a separate question, and it belongs to the reader that
-            * walks the host.
-            *
-            * @example
-            * ```ts
-            * import { readHostManifest } from '@orkestrel/scaffold/server'
-            *
-            * readHostManifest('./dist/host') // the manifest, or undefined for a raw root
-            * ```
-            */
-           export declare function readHostManifest(host: string, name?: string): HostManifest | undefined;
+                /**
+                 * Reads one contained file as bounded UTF-8 text.
+                 *
+                 * @param root - The containing host directory.
+                 * @param path - The portable root-relative file path.
+                 * @param limit - The most bytes this read accepts; the artifact ceiling by default.
+                 * @returns The decoded text, or `undefined` when {@link readFileHex} answers
+                 * nothing or the bytes are not valid UTF-8.
+                 * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
+                 * `path` leaves `root`.
+                 *
+                 * @remarks
+                 * Decoding is strict, so a file carrying an invalid sequence answers `undefined`
+                 * rather than text carrying replacement characters. That matters because the
+                 * text is parsed next: a manifest silently repaired into valid JSON by lossy
+                 * decoding would be trusted.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readFileText } from '@orkestrel/scaffold/server'
+                 *
+                 * readFileText('/tmp/project', 'package.json') // '{ "name": "@orkestrel/router", … }'
+                 * ```
+                 */
+                export declare function readFileText(root: string, path: string, limit?: number): string | undefined;
 
-           /**
-            * Derives one vendored-host manifest entry from a file in a checkout.
-            *
-            * @param destination - The target-relative path the file is written to.
-            * @param source - The resolved host path the bytes are read from.
-            * @returns The entry, or `undefined` when `source` is not a physical file this
-            * package will vendor or carries more bytes than one artifact may.
-            *
-            * @remarks
-            * The one place the declared fields are decided together, because they are
-            * readings of one path: {@link pathToStorage} decides where it is stored,
-            * the destination is the path it answers for, and {@link matchesExecutablePath}
-            * decides whether a target receives it executable.
-            *
-            * The bit is read from that declaration rather than from the source's mode, so
-            * the entry does not depend on where the package was staged. A Windows host
-            * reports no executable bit at all, and reading the mode there declared every
-            * entry non-executable and shipped consumers hooks they could not run.
-            *
-            * @example
-            * ```ts
-            * import { readManifestEntry } from '@orkestrel/scaffold/server'
-            *
-            * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
-            * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
-            * ```
-            */
-           export declare function readManifestEntry(destination: string, source: string): ManifestEntry | undefined;
+                /**
+                 * 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
+                 * ```
+                 */
+                export declare function readHostFloor(root?: string): Host;
 
-           /**
-            * Reads a target's current bytes at the paths a plan claims.
-            *
-            * @param target - The target directory to read.
-            * @param paths - The plan-relative paths to probe.
-            * @returns One entry per path that is there: a file maps to its exact bytes as
-            * hexadecimal and a directory maps to `''`, which records presence with no bytes
-            * to compare. An absent path is omitted.
-            * @throws `ScaffoldError('INVALID', …)` when `target` is not a host path or
-            * `paths` is not a bounded list of plannable paths.
-            * @throws `ScaffoldError('TARGET', …)` when a path that is there cannot be read,
-            * or when the whole read would retain more bytes than one plan may.
-            *
-            * @remarks
-            * The one door from a real directory into the vocabulary an audit compares in.
-            * Absence is omission rather than an empty value, because core reads a missing
-            * key as a missing destination and an empty string as a present directory;
-            * they are different verdicts. A path that is there but unreadable throws instead
-            * of being omitted, because omission would report it as missing and a repair
-            * would then overwrite whatever is actually sitting there.
-            *
-            * @example
-            * ```ts
-            * import { readSnapshot } from '@orkestrel/scaffold/server'
-            *
-            * readSnapshot('./packages/router', ['package.json', 'guides'])
-            * // { 'package.json': '7b226e…', guides: '' }
-            * ```
-            */
-           export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
+                /**
+                 * Reads 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
+                 * read, is not the declared shape, or does not match its own membership.
+                 *
+                 * @remarks
+                 * The failures are held apart deliberately. A host with no manifest is a
+                 * raw checkout, and a caller reads it by mapping each path one to one. A host
+                 * with a manifest that does not verify is a staged host that has been edited,
+                 * and answering `undefined` there would degrade it to that same one-to-one
+                 * mapping — which is how an edited manifest would get a caller to read files it
+                 * never declared. So absence answers and corruption throws.
+                 *
+                 * Verification here is the manifest's own self-consistency: the digest against
+                 * the exact membership beside it. Whether that membership matches the files
+                 * actually stored is a separate question, and it belongs to the reader that
+                 * walks the host.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readHostManifest } from '@orkestrel/scaffold/server'
+                 *
+                 * readHostManifest('./dist/host') // the manifest, or undefined for a raw root
+                 * ```
+                 */
+                export declare function readHostManifest(host: string, name?: string): HostManifest | undefined;
 
-           /**
-            * Reads the Surface collision baseline from a committed inventory.
-            *
-            * @param root - The checkout's host path.
-            * @param name - The checkout-relative inventory path. Default: `host.json`.
-            * @returns The recorded collisions, or `undefined` when the inventory is absent.
-            * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or `name` leaves it.
-            * @throws `ScaffoldError('TARGET', …)` when an existing inventory is unreadable,
-            * malformed, or inconsistent with its digest.
-            *
-            * @example
-            * ```ts
-            * import { readSurfaceBaseline } from '@orkestrel/scaffold/server'
-            *
-            * readSurfaceBaseline('.') // the recorded collisions, if the inventory exists
-            * ```
-            */
-           export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
+                /**
+                 * Derives one vendored-host manifest entry from a file in a checkout.
+                 *
+                 * @param destination - The target-relative path the file is written to.
+                 * @param source - The resolved host path the bytes are read from.
+                 * @returns The entry, or `undefined` when `source` is not a physical file this
+                 * package will vendor or carries more bytes than one artifact may.
+                 *
+                 * @remarks
+                 * The one place the declared fields are decided together, because they are
+                 * readings of one path: {@link pathToStorage} decides where it is stored,
+                 * the destination is the path it answers for, and {@link matchesExecutablePath}
+                 * decides whether a target receives it executable.
+                 *
+                 * The bit is read from that declaration rather than from the source's mode, so
+                 * the entry does not depend on where the package was staged. A Windows host
+                 * reports no executable bit at all, and reading the mode there declared every
+                 * entry non-executable and shipped consumers hooks they could not run.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readManifestEntry } from '@orkestrel/scaffold/server'
+                 *
+                 * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
+                 * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
+                 * ```
+                 */
+                export declare function readManifestEntry(destination: string, source: string): ManifestEntry | undefined;
 
-           /**
-            * Reads bare Surface names claimed by distinct package guides.
-            *
-            * @param root - The physical directory containing the package guides.
-            * @returns Colliding names and their distinct owners, sorted by name and owner.
-            * @throws `ScaffoldError('TARGET', …)` when the directory or a guide cannot be read.
-            * @throws `ScaffoldError('TARGET', …)` when `@orkestrel/guide` cannot be loaded.
-            *
-            * @remarks
-            * Reads immediate `.md` files except `README.md` through `createGuide().surface()`.
-            * Requires `@orkestrel/guide` in this module's resolution path; Scaffold declares it
-            * only for development. Loads it only when called, so importing the server entry
-            * requires no guide tooling in a production install.
-            *
-            * @example
-            * ```ts
-            * import { readSurfaceCollisions } from '@orkestrel/scaffold/server'
-            *
-            * readSurfaceCollisions('./guides').get('Shared') // the guides claiming Shared, if it collides
-            * ```
-            */
-           export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
+                /**
+                 * Reads a target's current bytes at the paths a plan claims.
+                 *
+                 * @param target - The target directory to read.
+                 * @param paths - The plan-relative paths to probe.
+                 * @returns One entry per path that is there: a file maps to its exact bytes as
+                 * hexadecimal and a directory maps to `''`, which records presence with no bytes
+                 * to compare. An absent path is omitted.
+                 * @throws `ScaffoldError('INVALID', …)` when `target` is not a host path or
+                 * `paths` is not a bounded list of plannable paths.
+                 * @throws `ScaffoldError('TARGET', …)` when a path that is there cannot be read,
+                 * or when the whole read would retain more bytes than one plan may.
+                 *
+                 * @remarks
+                 * The one door from a real directory into the vocabulary an audit compares in.
+                 * Absence is omission rather than an empty value, because core reads a missing
+                 * key as a missing destination and an empty string as a present directory;
+                 * they are different verdicts. A path that is there but unreadable throws instead
+                 * of being omitted, because omission would report it as missing and a repair
+                 * would then overwrite whatever is actually sitting there.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readSnapshot } from '@orkestrel/scaffold/server'
+                 *
+                 * readSnapshot('./packages/router', ['package.json', 'guides'])
+                 * // { 'package.json': '7b226e…', guides: '' }
+                 * ```
+                 */
+                export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
 
-           /**
-            * Matches the Windows device names that stay reserved even when an extension follows.
-            *
-            * @remarks
-            * Refused on every host rather than only on Windows. A generated workspace is
-            * checked out on all of them, so a directory this package writes on Linux must
-            * still be a name Windows can hold.
-            */
-           export declare const RESERVED_SEGMENT_PATTERN: RegExp;
+                /**
+                 * Reads the Surface collision baseline from a committed inventory.
+                 *
+                 * @param root - The checkout's host path.
+                 * @param name - The checkout-relative inventory path. Default: `host.json`.
+                 * @returns The recorded collisions, or `undefined` when the inventory is absent.
+                 * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or `name` leaves it.
+                 * @throws `ScaffoldError('TARGET', …)` when an existing inventory is unreadable,
+                 * malformed, or inconsistent with its digest.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readSurfaceBaseline } from '@orkestrel/scaffold/server'
+                 *
+                 * readSurfaceBaseline('.') // the recorded collisions, if the inventory exists
+                 * ```
+                 */
+                export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
 
-           /**
-            * Resolves a root-relative path and refuses one that leaves its root.
-            *
-            * @param root - The containing host directory.
-            * @param path - The portable root-relative path.
-            * @returns The destination as this package will address it, or `undefined` when
-            * either argument is off contract or the destination lies outside `root`.
-            *
-            * @remarks
-            * The containment law, and the one door every read in this module goes through.
-            * Both sides are resolved through the real filesystem before they are compared.
-            * A dangling link is followed only when its raw target contains no parent
-            * traversal. The answer is then the lexical join of `root` and `path` — an
-            * absolute path under `root`, not a root-relative one — so the caller operates
-            * on the path it named rather than on a resolved form the target may not
-            * recognize. A `root` written with a parent segment is collapsed by that
-            * resolution before anything is read, so containment is measured against the
-            * directory the caller's text names.
-            *
-            * Comparison is exact text, which fails closed on a case-insensitive
-            * filesystem: a root and a path spelled with different case resolve to
-            * different strings there and are refused, never wrongly admitted.
-            *
-            * The answer describes the namespace this call read. The contract excludes a
-            * concurrent rename or link swap during the call or before the caller finishes
-            * using the returned path. This helper returns a string, not a filesystem
-            * handle, so it cannot bind its containment check to a later operation. A caller
-            * that admits hostile concurrent namespace mutation needs a handle-bound
-            * operation instead.
-            *
-            * @example
-            * ```ts
-            * import { resolveContainedPath } from '@orkestrel/scaffold/server'
-            *
-            * resolveContainedPath('/tmp/project', 'guides/router.md')?.endsWith('router.md') // true
-            * resolveContainedPath('/tmp/project', '../secrets') // undefined
-            * ```
-            */
-           export declare function resolveContainedPath(root: string, path: string): string | undefined;
+                /**
+                 * Reads bare Surface names claimed by distinct package guides.
+                 *
+                 * @param root - The physical directory containing the package guides.
+                 * @returns Colliding names and their distinct owners, sorted by name and owner.
+                 * @throws `ScaffoldError('TARGET', …)` when the directory or a guide cannot be read.
+                 * @throws `ScaffoldError('TARGET', …)` when `@orkestrel/guide` cannot be loaded.
+                 *
+                 * @remarks
+                 * Reads immediate `.md` files except `README.md` through `createGuide().surface()`.
+                 * Requires `@orkestrel/guide` in this module's resolution path; Scaffold declares it
+                 * only for development. Loads it only when called, so importing the server entry
+                 * requires no guide tooling in a production install.
+                 *
+                 * @example
+                 * ```ts
+                 * import { readSurfaceCollisions } from '@orkestrel/scaffold/server'
+                 *
+                 * readSurfaceCollisions('./guides').get('Shared') // the guides claiming Shared, if it collides
+                 * ```
+                 */
+                export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
 
-           /**
-            * Resolves a path through the real filesystem, keeping the part that does not exist yet.
-            *
-            * @param path - The absolute or relative host path to resolve.
-            * @returns The lexical resolution of `path`, with its existing prefix then
-            * resolved through every link, or `undefined` when the text is not a host path,
-            * no bounded existing ancestor resolves, a link target cannot be read, a link
-            * target carries a `..` segment, or an ancestor cannot be read.
-            *
-            * @remarks
-            * A containment decision has to be made about a destination that does not exist
-            * 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.
-            *
-            * 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
-            * link in that segment is read. So `<root>/hop/..` answers `<root>` even where
-            * `hop` links elsewhere, rather than the directory holding what `hop` points at.
-            * The collapse only ever shortens the caller's path, so nothing reaches outside
-            * it by this; the answer is that lexical location resolved through links, not
-            * the physical location the links lead to. {@link resolveContainedPath} passes
-            * its `root` through here, so a root written with a parent segment is contained
-            * against its collapsed spelling.
-            *
-            * `realpath` answers `ENOENT` both for a name that is not there and for a link
-            * whose target is not there. The name is therefore inspected without following
-            * it: a dangling link redirects the walk to its target, while a genuinely absent
-            * name is retained as one segment of the unresolved suffix. A dangling link
-            * target containing a `..` segment is refused. Resolving that target as one
-            * lexical string could discard a preceding link before the filesystem gives
-            * `..` its physical meaning.
-            *
-            * That target is split on both separators on every host, which is the reading
-            * `isPath` already gives a planned path. A POSIX filename legally containing a
-            * backslash is therefore refused with it: `weird\..\name` is one name to the
-            * host and three segments here. The package keeps one separator law rather than
-            * a host-dependent second one, and this is the conservative side of it.
-            *
-            * @example
-            * ```ts
-            * import { resolveRealPath } from '@orkestrel/scaffold/server'
-            *
-            * resolveRealPath('./packages/new/src') // the real path of `packages`, plus `new/src`
-            * ```
-            */
-           export declare function resolveRealPath(path: string): string | undefined;
+                /**
+                 * Matches the Windows device names that stay reserved even when an extension follows.
+                 *
+                 * @remarks
+                 * Refused on every host rather than only on Windows. A generated workspace is
+                 * checked out on all of them, so a directory this package writes on Linux must
+                 * still be a name Windows can hold.
+                 */
+                export declare const RESERVED_SEGMENT_PATTERN: RegExp;
 
-           /**
-            * Names the repository this package's own vendored files are served from.
-            *
-            * @remarks
-            * This package's bare name, stated rather than derived, because the reader has no
-            * manifest to read it out of and one raw content host serves both the fleet's
-            * guides and these files.
-            */
-           export declare const SCAFFOLD_REPOSITORY = "scaffold";
+                /**
+                 * Resolves a root-relative path and refuses one that leaves its root.
+                 *
+                 * @param root - The containing host directory.
+                 * @param path - The portable root-relative path.
+                 * @returns The destination as this package will address it, or `undefined` when
+                 * either argument is off contract or the destination lies outside `root`.
+                 *
+                 * @remarks
+                 * The containment law, and the one door every read in this module goes through.
+                 * Both sides are resolved through the real filesystem before they are compared.
+                 * A dangling link is followed only when its raw target contains no parent
+                 * traversal. The answer is then the lexical join of `root` and `path` — an
+                 * absolute path under `root`, not a root-relative one — so the caller operates
+                 * on the path it named rather than on a resolved form the target may not
+                 * recognize. A `root` written with a parent segment is collapsed by that
+                 * resolution before anything is read, so containment is measured against the
+                 * directory the caller's text names.
+                 *
+                 * Comparison is exact text, which fails closed on a case-insensitive
+                 * filesystem: a root and a path spelled with different case resolve to
+                 * different strings there and are refused, never wrongly admitted.
+                 *
+                 * The answer describes the namespace this call read. The contract excludes a
+                 * concurrent rename or link swap during the call or before the caller finishes
+                 * using the returned path. This helper returns a string, not a filesystem
+                 * handle, so it cannot bind its containment check to a later operation. A caller
+                 * that admits hostile concurrent namespace mutation needs a handle-bound
+                 * operation instead.
+                 *
+                 * @example
+                 * ```ts
+                 * import { resolveContainedPath } from '@orkestrel/scaffold/server'
+                 *
+                 * resolveContainedPath('/tmp/project', 'guides/router.md')?.endsWith('router.md') // true
+                 * resolveContainedPath('/tmp/project', '../secrets') // undefined
+                 * ```
+                 */
+                export declare function resolveContainedPath(root: string, path: string): string | undefined;
 
-           /**
-            * Stages 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: '…' }]
-            * ```
-            */
-           export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly ManifestEntry[];
+                /**
+                 * Resolves a path through the real filesystem, keeping the part that does not exist yet.
+                 *
+                 * @param path - The absolute or relative host path to resolve.
+                 * @returns The lexical resolution of `path`, with its existing prefix then
+                 * resolved through every link, or `undefined` when the text is not a host path,
+                 * no bounded existing ancestor resolves, a link target cannot be read, a link
+                 * target carries a `..` segment, or an ancestor cannot be read.
+                 *
+                 * @remarks
+                 * A containment decision has to be made about a destination that does not exist
+                 * 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. {@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
+                 * link in that segment is read. So `<root>/hop/..` answers `<root>` even where
+                 * `hop` links elsewhere, rather than the directory holding what `hop` points at.
+                 * The collapse only ever shortens the caller's path, so nothing reaches outside
+                 * it by this; the answer is that lexical location resolved through links, not
+                 * the physical location the links lead to. {@link resolveContainedPath} passes
+                 * its `root` through here, so a root written with a parent segment is contained
+                 * against its collapsed spelling.
+                 *
+                 * `realpath` answers `ENOENT` both for a name that is not there and for a link
+                 * whose target is not there. The name is therefore inspected without following
+                 * it: a dangling link redirects the walk to its target, while a genuinely absent
+                 * name is retained as one segment of the unresolved suffix. A dangling link
+                 * target containing a `..` segment is refused. Resolving that target as one
+                 * lexical string could discard a preceding link before the filesystem gives
+                 * `..` its physical meaning.
+                 *
+                 * That target is split on both separators on every host, which is the reading
+                 * `isPath` already gives a planned path. A POSIX filename legally containing a
+                 * backslash is therefore refused with it: `weird\..\name` is one name to the
+                 * host and three segments here. The package keeps one separator law rather than
+                 * a host-dependent second one, and this is the conservative side of it.
+                 *
+                 * @example
+                 * ```ts
+                 * import { resolveRealPath } from '@orkestrel/scaffold/server'
+                 *
+                 * resolveRealPath('./packages/new/src') // the real path of `packages`, plus `new/src`
+                 * ```
+                 */
+                export declare function resolveRealPath(path: string): string | undefined;
 
-           /**
-            * Stages a vendored host root from a real checkout.
-            *
-            * @param checkout - The checkout the vendored paths are read from.
-            * @param host - The vendored host root to fill; it must be absent or empty.
-            * @param options - The inventory selection, establishment switch, and reporting callback.
-            * Default: no reporting.
-            * @returns One entry per staged file, sorted by storage name.
-            * @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
-            * or a vendored path leaves the checkout or the host root.
-            * @throws `ScaffoldError('TARGET', …)` when the checkout is not a directory, the
-            * host root is not vacant, the checkout does not carry every vendored path, two
-            * vendored files claim one storage name, a vendored file is not a plain file
-            * within the artifact ceiling, published guides are unreadable, a staged
-            * collision's owner set is not a subset of its published owner set, the inventory is absent without
-            * `establish: true`, or the staged manifest does not read back.
-            * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
-            * be written.
-            *
-            * @remarks
-            * This is the producer half of the vendored host, and it is not the mutation
-            * contract `MaterializerInterface` states. That contract owns **target**
-            * writes: it materializes a compiled plan into a consumer's workspace, binds
-            * every destination to what the caller observed, and rolls a failed commit back.
-            * This reads this package's own checkout at build time and fills its own build
-            * output. Different direction, different lifetime, no consumer target involved,
-            * so they do not overlap and neither one belongs inside the other.
-            *
-            * Staging is plain rather than transactional for the same reason. A
-            * `WriteTransaction` exists to hold a directory that already holds work
-            * still; a build output holds nothing, is deleted whole before every build, and
-            * has no concurrent reader. What replaces it is refusing early and ordering the
-            * writes: the whole membership is derived before anything is created, so a
-            * membership refusal leaves no host root at all, and `manifest.json` is
-            * written last, so a copy or Surface refusal leaves a root every
-            * reader treats as a raw checkout and fails loudly on.
-            *
-            * A missing vendored path is refused rather than staged around. A partial root
-            * is not detectably partial: it fails later, in a consumer's terminal, on
-            * whichever path the plan reached first. Refusing here fails the build that
-            * produced it, where the maintainer can act, and it names every missing path at
-            * once. A directory is the same case — declaring an absent directory as an empty
-            * root would create an empty directory in every generated workspace. A canon file
-            * member the checkout no longer holds is the one exception: scaffold keeps owning
-            * the path so a target's copy reports foreign, and the stage ships nothing for it.
-            *
-            * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
-            * A plan selects the paths a target receives; the installed package also carries
-            * the canon and reference files for reading. Every catalog package must have a
-            * guide in the discovered membership before the host is written.
-            * Copied guides must carry no collision whose name and exact owner set the
-            * committed inventory lacks. An absent inventory requires `establish: true`;
-            * an inventory without a valid recorded Surface is refused.
-            * Everything downstream — the missing-path refusal, the
-            * storage collision guard, the sort, the digests, and the root inventory — reads
-            * the union, so every staged path follows the same law.
-            *
-            * The vendoring deny-list applies to what the walk discovers beneath a staged
-            * directory, where a maintainer's local credential can legitimately sit, and
-            * such a path is skipped. A path a staging list names itself is curated data
-            * rather than discovery, so it is staged or the stage is refused.
-            *
-            * @example Vendored data root
-            * ```ts
-            * import { stageHost } from '@orkestrel/scaffold/server'
-            *
-            * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
-            * ```
-            */
-           export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly ManifestEntry[];
+                /**
+                 * Names the repository this package's own vendored files are served from.
+                 *
+                 * @remarks
+                 * This package's bare name, stated rather than derived, because the reader has no
+                 * manifest to read it out of and one raw content host serves both the fleet's
+                 * guides and these files.
+                 */
+                export declare const SCAFFOLD_REPOSITORY = "scaffold";
 
-           /**
-            * 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
-            * ```
-            */
-           export declare function stageInventory(checkout: string, path?: string): HostManifest;
+                /**
+                 * Stages 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: '…' }]
+                 * ```
+                 */
+                export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly ManifestEntry[];
 
-           /** Represents a Surface name claimed by distinct package guides. */
-           export declare interface SurfaceCollision {
-               readonly name: string;
-               readonly owners: readonly string[];
-           }
+                /**
+                 * Stages a vendored host root from a real checkout.
+                 *
+                 * @param checkout - The checkout the vendored paths are read from.
+                 * @param host - The vendored host root to fill; it must be absent or empty.
+                 * @param options - The inventory selection, establishment switch, and reporting callback.
+                 * Default: no reporting.
+                 * @returns One entry per staged file, sorted by storage name.
+                 * @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
+                 * or a vendored path leaves the checkout or the host root.
+                 * @throws `ScaffoldError('TARGET', …)` when the checkout is not a directory, the
+                 * host root is not vacant, the checkout does not carry every vendored path, two
+                 * vendored files claim one storage name, a vendored file is not a plain file
+                 * within the artifact ceiling, published guides are unreadable, a staged
+                 * collision's owner set is not a subset of its published owner set, the inventory is absent without
+                 * `establish: true`, or the staged manifest does not read back.
+                 * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
+                 * be written.
+                 *
+                 * @remarks
+                 * This is the producer half of the vendored host, and it is not the mutation
+                 * contract `MaterializerInterface` states. That contract owns **target**
+                 * writes: it materializes a compiled plan into a consumer's workspace, binds
+                 * every destination to what the caller observed, and rolls a failed commit back.
+                 * This reads this package's own checkout at build time and fills its own build
+                 * output. Different direction, different lifetime, no consumer target involved,
+                 * so they do not overlap and neither one belongs inside the other.
+                 *
+                 * Staging is plain rather than transactional for the same reason. A
+                 * `WriteTransaction` exists to hold a directory that already holds work
+                 * still; a build output holds nothing, is deleted whole before every build, and
+                 * has no concurrent reader. What replaces it is refusing early and ordering the
+                 * writes: the whole membership is derived before anything is created, so a
+                 * membership refusal leaves no host root at all, and `manifest.json` is
+                 * written last, so a copy or Surface refusal leaves a root every
+                 * reader treats as a raw checkout and fails loudly on.
+                 *
+                 * A missing vendored path is refused rather than staged around. A partial root
+                 * is not detectably partial: it fails later, in a consumer's terminal, on
+                 * whichever path the plan reached first. Refusing here fails the build that
+                 * produced it, where the maintainer can act, and it names every missing path at
+                 * once. A directory is the same case — declaring an absent directory as an empty
+                 * root would create an empty directory in every generated workspace. A canon file
+                 * member the checkout no longer holds is the one exception: scaffold keeps owning
+                 * the path so a target's copy reports foreign, and the stage ships nothing for it.
+                 *
+                 * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
+                 * A plan selects the paths a target receives; the installed package also carries
+                 * the canon and reference files for reading. Every catalog package must have a
+                 * guide in the discovered membership before the host is written.
+                 * Copied guides must carry no collision whose name and exact owner set the
+                 * committed inventory lacks. An absent inventory requires `establish: true`;
+                 * an inventory without a valid recorded Surface is refused.
+                 * Everything downstream — the missing-path refusal, the
+                 * storage collision guard, the sort, the digests, and the root inventory — reads
+                 * the union, so every staged path follows the same law.
+                 *
+                 * The vendoring deny-list applies to what the walk discovers beneath a staged
+                 * directory, where a maintainer's local credential can legitimately sit, and
+                 * such a path is skipped. A path a staging list names itself is curated data
+                 * rather than discovery, so it is staged or the stage is refused.
+                 *
+                 * @example Vendored data root
+                 * ```ts
+                 * import { stageHost } from '@orkestrel/scaffold/server'
+                 *
+                 * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
+                 * ```
+                 */
+                export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly ManifestEntry[];
 
-           /**
-            * Reports the outcome of one bounded read whose body is taken as text.
-            *
-            * @remarks
-            * `content` carries the body only when `lookup` is `found`; otherwise it is
-            * empty and `note` states what happened. A read that is not `found` is an answer
-            * rather than a throw, which is what lets one dead row sit beside live ones.
-            */
-           export declare interface TextReadResult {
-               readonly lookup: Lookup;
-               readonly content: string;
-               readonly note: string;
-           }
+                /**
+                 * 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
+                 * ```
+                 */
+                export declare function stageInventory(checkout: string, path?: string): HostManifest;
 
-           /** Holds the note a release carries when its packument names no readable latest version. */
-           export declare const UNREADABLE_VERSION_NOTE = "the answer carries no readable latest version";
+                /** Represents a Surface name claimed by distinct package guides. */
+                export declare interface SurfaceCollision {
+                    readonly name: string;
+                    readonly owners: readonly string[];
+                }
 
-           /**
-            * Represents the reading spine: one bounded, unauthenticated, redirect-free request per answer.
-            *
-            * @remarks
-            * This is the package's only network reader, and it never writes. Every call
-            * opens one byte allowance and spends it across every read the call makes, so a
-            * caller is bounded twice over: `limit` refuses one oversized answer and
-            * `budget` refuses many small ones. They are separate exhaustion routes and
-            * neither bound covers the other.
-            *
-            * A per-package failure never escapes as a throw. It is projected into the
-            * verdict that package's row already carries — `missing` for an upstream `404`,
-            * which is a definite answer, and `failed` for a transport fault, which is no
-            * answer at all — so one unreachable package never costs the caller the rest of
-            * the answer. The organization package list is the one exception: without it
-            * 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
-            * 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.
-            *
-            * @example
-            * ```ts
-            * import { Upstream } from '@orkestrel/scaffold/server'
-            *
-            * const upstream = new Upstream({ registry: { timeout: 5_000 } })
-            * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
-            *
-            * releases.filter((release) => release.lookup === 'found')
-            * upstream.destroy()
-            * ```
-            */
-           export declare class Upstream implements UpstreamInterface {
-               #private;
-               /**
-                * Constructs 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.
-                * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
-                    * is not an option bag this reader accepts, or when either endpoint names a
-                    * scheme, host, or form this reader will not request.
-                    *
-                    * @remarks
-                    * `isEndpoint` bounds an endpoint's length and nothing else, so the scheme and
-                    * host law is settled here, where a refusal can say which endpoint was refused
-                    * and why. An endpoint must be HTTPS, or HTTP to a loopback host — the one
-                    * place an unencrypted request has no network between its ends. That
-                    * refuses `file:`, `data:`, and plain HTTP to a real host, and it is what
-                    * keeps a fixture reachable without weakening transport security anywhere a
-                    * real request goes. An endpoint carrying credentials, a query, or a fragment
-                    * is refused too: this reader authenticates nothing and appends its own path.
-                    */
-                constructor(options?: UpstreamOptions);
-                /** Exposes the upstream reader's observation channel. */
-                get emitter(): EmitterInterface<UpstreamEventMap>;
                 /**
-                 * Looks up the newest release each declared range admits.
+                 * Reports the outcome of one bounded read whose body is taken as text.
                  *
-                 * @param dependencies - The declared dependencies to look up.
-                 * @returns One release verdict per dependency, in input order.
-                 * @throws {@link ScaffoldError} coded `INVALID` when `dependencies` is not a
-                     * bounded list of declared dependencies, and `DESTROYED` when the reader is
-                     * torn down before or during the call.
-                     *
-                     * @remarks
-                     * The reader selects across the packument's stable version map before any
-                     * collection bound can truncate it. It falls back to `dist-tags.latest` only
-                     * when that version satisfies the declared range. `*` requests the newest
-                     * stable version outright. The verdict's `major` field carries the stable
-                     * major from the latest tag when that tag can be read.
-                     *
-                     * @example
-                     * ```ts
-                     * import { Upstream } from '@orkestrel/scaffold/server'
+                 * @remarks
+                 * `content` carries the body only when `lookup` is `found`; otherwise it is
+                 * empty and `note` states what happened. A read that is not `found` is an answer
+                 * rather than a throw, which is what lets one dead row sit beside live ones.
+                 */
+                export declare interface TextReadResult {
+                    readonly lookup: Lookup;
+                    readonly content: string;
+                    readonly note: string;
+                }
+
+                /** Holds the note a release carries when its packument names no readable latest version. */
+                export declare const UNREADABLE_VERSION_NOTE = "the answer carries no readable latest version";
+
+                /**
+                 * Represents the reading spine: one bounded, unauthenticated, redirect-free request per answer.
+                 *
+                 * @remarks
+                 * This is the package's only network reader, and it never writes. Every call
+                 * opens one byte allowance and spends it across every read the call makes, so a
+                 * caller is bounded twice over: `limit` refuses one oversized answer and
+                 * `budget` refuses many small ones. They are separate exhaustion routes and
+                 * neither bound covers the other.
+                 *
+                 * A per-package failure never escapes as a throw. It is projected into the
+                 * verdict that package's row already carries — `missing` for an upstream `404`,
+                 * which is a definite answer, and `failed` for a transport fault, which is no
+                 * answer at all — so one unreachable package never costs the caller the rest of
+                 * the answer. The organization package list is the one exception: without it
+                 * 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
+                 * reader's own abort signal, so {@link Upstream.destroy} cancels what is in
+                 * flight instead of waiting for it.
+                 *
+                 * 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
+                 * import { Upstream } from '@orkestrel/scaffold/server'
+                 *
+                 * const upstream = new Upstream({ registry: { timeout: 5_000 } })
+                 * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
+                 *
+                 * releases.filter((release) => release.lookup === 'found')
+                 * upstream.destroy()
+                 * ```
+                 */
+                export declare class Upstream implements UpstreamInterface {
+                    #private;
+                    /**
+                     * Constructs a reader over one raw content host and one registry.
                      *
-                     * const upstream = new Upstream()
-                     * await upstream.lookup([{ name: '@orkestrel/router', range: '^0.0.8' }])
-                     * upstream.destroy()
-                     * ```
-                     */
-                 lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
-                 /**
-                  * Fetches each named package's guide, beside the local mirror it answers for.
-                  *
-                  * @param names - The packages to fetch: the target's declared set, or the whole organization.
-                  * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
-                  * @returns One mirror verdict per name, in input order.
-                  * @throws {@link ScaffoldError} coded `INVALID` when `names` is not a bounded
-                      * list of fleet package names or `current` is not a snapshot, and `DESTROYED`
-                      * when the reader is torn down before or during the call.
-                      *
-                      * @remarks
-                      * The mirror path is derived from the package name by the same helper the plan
-                      * derives it with, and the fetched URL ends in that exact path, so a verdict
-                      * always answers for the file it names. `observed` is carried through from
-                      * `current` whatever the lookup produced, because it is the precondition the
-                      * later write is held to and a failed fetch does not change what the target
-                      * holds.
-                      *
-                      * @example
-                      * ```ts
-                      * import { Upstream } from '@orkestrel/scaffold/server'
+                     * @param options - The endpoints, the request bounds, the initial
+                     * listeners, and the listener-error handler.
+                     * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
+                         * is not an option bag this reader accepts, or when either endpoint names a
+                         * scheme, host, or form this reader will not request.
+                         *
+                         * @remarks
+                         * `isEndpoint` bounds an endpoint's length and nothing else, so the scheme and
+                         * host law is settled here, where a refusal can say which endpoint was refused
+                         * and why. An endpoint must be HTTPS, or HTTP to a loopback host — the one
+                         * place an unencrypted request has no network between its ends. That
+                         * refuses `file:`, `data:`, and plain HTTP to a real host, and it is what
+                         * keeps a fixture reachable without weakening transport security anywhere a
+                         * real request goes. An endpoint carrying credentials, a query, or a fragment
+                         * is refused too: this reader authenticates nothing and appends its own path.
+                         */
+                     constructor(options?: UpstreamOptions);
+                     /** Exposes the upstream reader's observation channel. */
+                     get emitter(): EmitterInterface<UpstreamEventMap>;
+                     /**
+                      * Looks up the newest release each declared range admits.
                       *
-                      * const upstream = new Upstream()
-                      * await upstream.fetch(['@orkestrel/router'], { 'guides/router.md': '2320526f75746572' })
-                      * upstream.destroy()
-                      * ```
-                      */
-                  fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
-                  /**
-                   * Reads 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'
+                      * @param dependencies - The declared dependencies to look up.
+                      * @returns One release verdict per dependency, in input order.
+                      * @throws {@link ScaffoldError} coded `INVALID` when `dependencies` is not a
+                          * bounded list of declared dependencies, and `DESTROYED` when the reader is
+                          * torn down before or during the call.
+                          *
+                          * @remarks
+                          * The reader selects across the packument's stable version map before any
+                          * collection bound can truncate it. It falls back to `dist-tags.latest` only
+                          * when that version satisfies the declared range. `*` requests the newest
+                          * stable version outright. The verdict's `major` field carries the stable
+                          * major from the latest tag when that tag can be read.
+                          *
+                          * @example
+                          * ```ts
+                          * import { Upstream } from '@orkestrel/scaffold/server'
+                          *
+                          * const upstream = new Upstream()
+                          * await upstream.lookup([{ name: '@orkestrel/router', range: '^0.0.8' }])
+                          * upstream.destroy()
+                          * ```
+                          */
+                      lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
+                      /**
+                       * Fetches each named package's guide, beside the local mirror it answers for.
                        *
-                       * const upstream = new Upstream()
-                       * await upstream.read(['AGENTS.md'], { 'AGENTS.md': '2320416745' })
-                       * upstream.destroy()
-                       * ```
-                       */
-                   read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
-                   /**
-                    * Catalogs the published fleet from the registry's organization package list.
-                    *
-                    * @returns One row per published package, sorted by name.
-                    * @throws {@link ScaffoldError} coded `FETCH` when the organization package
-                        * list is unreachable, malformed, empty, or larger than one bounded
-                        * collection, and `DESTROYED` when the reader is torn down before or during
-                        * the call.
-                        *
-                        * @remarks
-                        * The organization list is the exact membership the registry publishes, not a
-                        * relevance search, and it is the whole reason this answer can claim to be the
-                        * fleet. So it fails hard where a per-package lookup fails soft: an empty or
-                        * unreadable list would otherwise be written into a target's catalog table as
-                        * a fleet with no packages in it. A package whose own version lookup then
-                        * fails still keeps its row, carrying the cause instead of a version, because
-                        * the list already proved the package is published.
-                        *
-                        * @example
-                        * ```ts
-                        * import { Upstream } from '@orkestrel/scaffold/server'
-                        *
-                        * const upstream = new Upstream()
-                        * const entries = await upstream.catalog()
-                        * upstream.destroy()
-                        * ```
-                        */
-                    catalog(): Promise<readonly CatalogEntry[]>;
-                    /**
-                     * Tears the reader down, aborting every request in flight. Teardown is idempotent.
-                     *
-                     * @returns Nothing.
-                     *
-                     * @remarks
-                     * A call still in flight rejects with a `DESTROYED` error rather than
-                     * resolving to a partial answer, because half a fleet reads exactly like a
-                     * whole one.
-                     *
-                     * @example
-                     * ```ts
-                     * import { Upstream } from '@orkestrel/scaffold/server'
-                     *
-                     * const upstream = new Upstream()
-                     * upstream.destroy()
-                     * upstream.emitter.destroyed // true
-                     * ```
-                     */
-                    destroy(): void;
-                   }
-
-                   /**
-                    * Represents the upstream reader's observation channel.
-                    *
-                    * @remarks
-                    * Each verdict is published whole rather than as a name beside a summary, so a
-                    * listener reads the same value the call returns and a failed lookup is told
-                    * apart from a successful one by the verdict's own discriminant rather than by
-                    * which event carried it.
-                    */
-                   export declare type UpstreamEventMap = {
-                       readonly release: readonly [release: Release];
-                       readonly mirror: readonly [mirror: Mirror];
-                       readonly file: readonly [file: HostFile];
-                       readonly error: readonly [error: unknown];
-                       readonly destroy: readonly [];
-                   };
-
-                   /**
-                    * Describes the upstream contract: the package's only network reader, and it never writes.
-                    *
-                    * @remarks
-                    * A per-package failure is collected as a verdict carrying its cause, not
-                    * thrown, so one unreachable package never costs the caller the rest of the
-                    * answer. The organization list is the exception: without it there is no fleet
-                    * to report, so an unreachable or malformed list is a coded failure.
-                    *
-                    * The vendored-file inventory is the other whole-answer read, and it fails
-                    * softly: an inventory that produces no answer fails every row of that call
-                    * rather than throwing, which is what leaves the caller one whole baseline to
-                    * fall back to instead of a mixture.
-                    */
-                   export declare interface UpstreamInterface {
-                       readonly emitter: EmitterInterface<UpstreamEventMap>;
-                       /**
-                        * Looks up the newest release each declared range admits.
-                        *
-                        * @param dependencies - The declared dependencies to look up.
-                        * @returns One release verdict per dependency, in input order.
-                        */
-                       lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
-                       /**
-                        * Fetches each named package's guide, beside the local mirror it answers for.
-                        *
-                        * @param names - The packages to fetch: the target's declared set, or the whole organization.
-                        * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
-                        * @returns One mirror verdict per name, in input order.
-                        */
+                       * @param names - The packages to fetch: the target's declared set, or the whole organization.
+                       * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
+                       * @returns One mirror verdict per name, in input order.
+                       * @throws {@link ScaffoldError} coded `INVALID` when `names` is not a bounded
+                           * list of fleet package names or `current` is not a snapshot, and `DESTROYED`
+                           * when the reader is torn down before or during the call.
+                           *
+                           * @remarks
+                           * The mirror path is derived from the package name by the same helper the plan
+                           * derives it with, and the fetched URL ends in that exact path, so a verdict
+                           * always answers for the file it names. `observed` is carried through from
+                           * `current` whatever the lookup produced, because it is the precondition the
+                           * later write is held to and a failed fetch does not change what the target
+                           * holds.
+                           *
+                           * @example
+                           * ```ts
+                           * import { Upstream } from '@orkestrel/scaffold/server'
+                           *
+                           * const upstream = new Upstream()
+                           * await upstream.fetch(['@orkestrel/router'], { 'guides/router.md': '2320526f75746572' })
+                           * upstream.destroy()
+                           * ```
+                           */
                        fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
                        /**
                         * Reads each named vendored file from the repository, beside the target bytes it answers for.
@@ -2437,307 +2429,445 @@ export declare class Materializer implements MaterializerInterface {
                         * @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.
-                        */
-                       read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
-                       /**
-                        * Catalogs the published fleet from the registry's organization package list.
-                        *
-                        * @returns One row per published package, sorted by name.
-                        */
-                       catalog(): Promise<readonly CatalogEntry[]>;
-                       /**
-                        * Tears the reader down, aborting every request in flight. Teardown is idempotent.
-                        *
-                        * @returns Nothing.
-                        */
-                       destroy(): void;
-                   }
-
-                   /**
-                    * Represents the options for the upstream reader.
-                    *
-                    * @remarks
-                    * The endpoints are grouped under the entity each configures: `repository`
-                    * takes the raw content host's `base`, its `branch`, and its `timeout`;
-                    * `registry` takes the registry's `base` and `timeout`. One raw content host
-                    * serves both the fleet's guides and this package's own vendored files, so one
-                    * group configures both. `concurrency` bounds requests in
-                    * flight and `retries` opts into per-request retry on a transport fault.
-                    * `limit` bounds the bytes read from one response body and `budget` bounds the
-                    * bytes read across a whole call, so neither one oversized answer nor many
-                    * small ones can exhaust the caller. Every request is unauthenticated and
-                    * follows no redirect.
-                    */
-                   export declare interface UpstreamOptions {
-                       readonly repository?: {
-                           readonly base?: string;
-                           readonly branch?: string;
-                           readonly timeout?: number;
-                       };
-                       readonly registry?: {
-                           readonly base?: string;
-                           readonly timeout?: number;
-                       };
-                       readonly concurrency?: number;
-                       readonly retries?: number;
-                       readonly limit?: number;
-                       readonly budget?: number;
-                       readonly on?: EmitterHooks<UpstreamEventMap>;
-                       readonly error?: EmitterErrorHandler;
-                   }
-
-                   /**
-                    * Describes what git reports about a target's working tree.
-                    *
-                    * @remarks
-                    * `tracked` is the only set a deletion may draw from: git does not report the
-                    * loss of an untracked path and `git diff` cannot restore it, so an ignored
-                    * path such as an installed dependency tree, a build output, or an editor
-                    * directory survives every verb. `dirty` is every path carrying an uncommitted
-                    * change, taken repo-wide rather than over a write set, because deletion makes
-                    * the write set the whole workspace. A clean tree is an empty `dirty`. A target
-                    * that is not a git repository yields no `Worktree` at all, so the caller
-                    * decides what to do about that rather than reading it out of an invented
-                    * empty value.
-                    */
-                   export declare interface Worktree {
-                       readonly tracked: readonly string[];
-                       readonly dirty: readonly string[];
-                   }
-
-                   /**
-                    * Represents one physical directory identity captured across a write transaction.
-                    *
-                    * @remarks
-                    * Native bigint device and inode values locate the directory and do not date it.
-                    * Two directories occupying one slot at different times share an anchor, so an anchor proves
-                    * where a write lands and never that the directory was left alone.
-                    */
-                   export declare interface WriteAnchor {
-                       readonly path: string;
-                       readonly device: bigint;
-                       readonly inode: bigint;
-                   }
-
-                   /** Reports the final directory anchor of a write transaction and the subset one call created. */
-                   export declare interface WriteDirectoryResult {
-                       readonly anchor: WriteAnchor;
-                       readonly created: readonly WriteAnchor[];
-                   }
-
-                   /**
-                    * Represents one destination snapshot captured before a write and required to survive it.
-                    *
-                    * @remarks
-                    * `device`, `inode`, `modified`, `size`, and `digest` are present only where
-                    * the observed shape supplies them.
-                    */
-                   export declare interface WriteExpectation {
-                       readonly path: string;
-                       readonly shape: 'absent' | 'file' | 'directory';
-                       readonly device?: number;
-                       readonly inode?: number;
-                       readonly modified?: number;
-                       readonly size?: number;
-                       readonly digest?: string;
-                   }
-
-                   /**
-                    * Describes the narrower caller-observed destination state a write transaction must
-                    * still match.
-                    */
-                   export declare interface WritePrecondition {
-                       readonly path: string;
-                       readonly shape: 'absent' | 'file';
-                       readonly digest?: string;
-                   }
-
-                   /**
-                    * Represents one staged, reversible mutation of one target directory.
-                    *
-                    * @remarks
-                    * The transaction owns a private root beside the target — a sibling directory on
-                    * the same volume, so every promotion is a rename rather than a copy. Staging
-                    * writes go into that root and nothing else, so a call that fails while staging
-                    * has not touched the target at all. Commit is the only step that mutates the
-                    * target, and it is the only step that can need rolling back.
-                    *
-                    * A precondition and an expectation hold a destination still. A **precondition** is what the caller
-                    * observed earlier and is checked once, at construction, so a target that moved
-                    * between the caller's read and this transaction fails before anything is
-                    * created. An **expectation** is captured here, at construction, and re-checked
-                    * at commit, so a target that moves while the write is being staged fails before
-                    * anything is promoted.
-                    *
-                    * What this provides, exactly:
-                    *
-                    * - **Across destinations, staged-then-swapped with rollback on a caught
-                    *   failure.** A failure part way through commit restores every destination it
-                    *   already promoted, restores every file it already took, and removes every
-                    *   directory it created, then reports what recovery could not undo. This is
-                    *   measured: a promotion is driven to fail after an earlier one landed, and the
-                    *   earlier destination is read back.
-                    * - **No partly written destination.** Every file is written whole into the
-                    *   private root and digested there before commit, so a destination never
-                    *   receives bytes that were still being produced.
-                    * - **Containment, not continuity, of the directories it creates.** Every
-                    *   ancestor is re-read between `mkdir` calls and again before the first
-                    *   promotion, so an ancestor that became a file, a symlink, a directory
-                    *   elsewhere, or nothing is refused. An ancestor deleted and recreated under
-                    *   the same name can receive its old inode back and is indistinguishable here
-                    *   from one that never moved.
-                    * - **No crash atomicity across destinations.** A process killed between
-                    *   promotions leaves the target holding some new files and some old ones, and
-                    *   leaves the private root behind. Nothing here is a journal, and the private
-                    *   root's name is the only record a later run could read.
-                    *
-                    * A destination is preserved by hard link and then replaced by a single
-                    * `rename`, rather than moved aside and replaced, so the path continues to name
-                    * the old file right up to the swap. That is a property of `rename` on the host,
-                    * not one this package's tests measure: telling it apart from move-then-replace
-                    * needs a reader observing the destination inside the swap, and no test here
-                    * does that. Read the claim as the mechanism it describes, not as a proven
-                    * guarantee about a concurrent reader.
-                    *
-                    * A path names a file this transaction writes, takes, or establishes as a
-                    * directory; every path is target-relative and is measured by the portable-path
-                    * law. An expectation and a precondition both name the resolved destination
-                    * instead, because that is the path each is re-read at.
-                    *
-                    * @example
-                    * ```ts
-                    * import { WriteTransaction } from '@orkestrel/scaffold/server'
-                    *
-                    * const transaction = new WriteTransaction('./packages/router', ['AGENTS.md'])
-                    * try {
-                    * 	transaction.write('AGENTS.md', '# Agents\n')
-                    * 	transaction.commit() // ['AGENTS.md']
-                    * } finally {
-                    * 	transaction.discard()
-                    * }
-                    * ```
-                    */
-                   export declare class WriteTransaction {
-                       #private;
-                       /**
-                        * Opens a transaction over one target directory.
-                        *
-                        * @param target - The directory every path is written beneath.
-                        * @param paths - Every target-relative path this transaction may touch.
-                        * @param preconditions - The caller-observed destination states the whole
-                        * transaction is held to, each naming a resolved destination of `paths`.
-                        * @throws {@link ScaffoldError} coded `INVALID` when an argument is off
-                            * contract, `TARGET` when a destination is a shape this package will not write
-                            * over or no longer matches its precondition, and `WRITE` when the private
-                            * root cannot be established.
+                        * @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
-                            * Nothing is created until every destination has been inspected and every
-                            * precondition has held, so a refused transaction leaves no residue at all.
-                            * The private root is created last and carries a random name, so two
-                            * transactions over one target never collide.
+                            * 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()
+                            * ```
                             */
-                        constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
-                        /** Names the resolved directory every path is written beneath. */
-                        get target(): string;
-                        /** Reports what each destination held when the transaction opened, in path order. */
-                        get expectations(): readonly WriteExpectation[];
-                        /** Reports whether the transaction can still be committed or discarded. */
-                        get open(): boolean;
+                        read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
                         /**
-                         * Stages one text file.
+                         * Catalogs the published fleet from the registry's organization package list.
                          *
-                         * @param path - The target-relative path to write.
-                         * @param content - The exact UTF-8 text the destination must hold.
-                         * @returns Nothing.
-                         * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
-                             * transaction opened or is already staged, `TARGET` when the destination holds
-                             * a directory, and `WRITE` when the staged file cannot be written or does not
-                             * carry the bytes it was given.
+                         * @returns One row per published package, sorted by name.
+                         * @throws {@link ScaffoldError} coded `FETCH` when the organization package
+                             * list is unreachable, malformed, empty, or larger than one bounded
+                             * collection, and `DESTROYED` when the reader is torn down before or during
+                             * the call.
                              *
                              * @remarks
-                             * The staged file is read back and digested against the text it was given, so
-                             * a partial or interrupted write is refused here rather than promoted later.
+                             * The organization list is the exact membership the registry publishes, not a
+                             * relevance search, and it is the whole reason this answer can claim to be the
+                             * fleet. So it fails hard where a per-package lookup fails soft: an empty or
+                             * unreadable list would otherwise be written into a target's catalog table as
+                             * a fleet with no packages in it. A package whose own version lookup then
+                             * fails still keeps its row, carrying the cause instead of a version, because
+                             * the list already proved the package is published.
+                             *
+                             * @example
+                             * ```ts
+                             * import { Upstream } from '@orkestrel/scaffold/server'
+                             *
+                             * const upstream = new Upstream()
+                             * const entries = await upstream.catalog()
+                             * upstream.destroy()
+                             * ```
                              */
-                         write(path: string, content: string): void;
+                         catalog(): Promise<readonly CatalogEntry[]>;
                          /**
-                          * Stages one byte-for-byte copy of a file that already exists on this host.
+                          * Tears the reader down, aborting every request in flight. Teardown is idempotent.
                           *
-                          * @param path - The target-relative path to write.
-                          * @param source - The resolved absolute path to copy the bytes from.
-                          * @param executable - If `true`, the destination carries the executable bit; if `false`, it does not.
                           * @returns Nothing.
-                          * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
-                              * transaction opened or is already staged, `TARGET` when the destination holds
-                              * a directory or the source is not a physical file, and `WRITE` when the copy
-                              * cannot be made or does not digest to the source's bytes.
-                              *
-                              * @remarks
-                              * The source is digested before the copy and the copy is digested after it, so
-                              * a source that changed mid-copy is refused instead of staged.
-                              */
-                          copy(path: string, source: string, executable: boolean): void;
-                          /**
-                           * Establishes one directory inside the target, one segment at a time.
-                           *
-                           * @param path - The target-relative directory to establish.
-                           * @returns The directory's identity and every segment this call created.
-                           * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
-                               * transaction opened, `TARGET` when the destination holds a file, and `WRITE`
-                               * when a segment cannot be created or changed while it was being created.
-                               *
-                               * @remarks
-                               * A directory is created immediately rather than staged, because creating one
-                               * destroys nothing: rollback removes exactly the segments this call created,
-                               * innermost first, and leaves every segment that was already there. Each
-                               * created segment is captured by device and inode, so a segment swapped
-                               * underneath the transaction is detected rather than written into.
-                               */
-                           establish(path: string): WriteDirectoryResult;
-                           /**
-                            * Marks one file for deletion at commit.
-                            *
-                            * @param path - The target-relative file to delete.
-                            * @returns Nothing.
-                            * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
-                                * transaction opened or is already claimed, and `TARGET` when the destination
-                                * does not hold a file.
-                                *
-                                * @remarks
-                                * Nothing moves here. Commit renames the file into the private backup rather
-                                * than unlinking it, so a later failure in the same commit puts it back.
-                                */
-                            remove(path: string): void;
+                          *
+                          * @remarks
+                          * A call still in flight rejects with a `DESTROYED` error rather than
+                          * resolving to a partial answer, because half a fleet reads exactly like a
+                          * whole one.
+                          *
+                          * @example
+                          * ```ts
+                          * import { Upstream } from '@orkestrel/scaffold/server'
+                          *
+                          * const upstream = new Upstream()
+                          * upstream.destroy()
+                          * upstream.emitter.destroyed // true
+                          * ```
+                          */
+                         destroy(): void;
+                        }
+
+                        /**
+                         * Represents the upstream reader's observation channel.
+                         *
+                         * @remarks
+                         * Each verdict is published whole rather than as a name beside a summary, so a
+                         * listener reads the same value the call returns and a failed lookup is told
+                         * apart from a successful one by the verdict's own discriminant rather than by
+                         * which event carried it.
+                         */
+                        export declare type UpstreamEventMap = {
+                            readonly release: readonly [release: Release];
+                            readonly mirror: readonly [mirror: Mirror];
+                            readonly file: readonly [file: HostFile];
+                            readonly error: readonly [error: unknown];
+                            readonly destroy: readonly [];
+                        };
+
+                        /**
+                         * Describes the upstream contract: the package's only network reader, and it never writes.
+                         *
+                         * @remarks
+                         * A per-package failure is collected as a verdict carrying its cause, not
+                         * thrown, so one unreachable package never costs the caller the rest of the
+                         * answer. The organization list is the exception: without it there is no fleet
+                         * to report, so an unreachable or malformed list is a coded failure.
+                         *
+                         * The vendored-file inventory is the other whole-answer read, and it fails
+                         * softly: an inventory that produces no answer fails every row of that call
+                         * rather than throwing, which is what leaves the caller one whole baseline to
+                         * fall back to instead of a mixture.
+                         */
+                        export declare interface UpstreamInterface {
+                            readonly emitter: EmitterInterface<UpstreamEventMap>;
+                            /**
+                             * Looks up the newest release each declared range admits.
+                             *
+                             * @param dependencies - The declared dependencies to look up.
+                             * @returns One release verdict per dependency, in input order.
+                             */
+                            lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
+                            /**
+                             * Fetches each named package's guide, beside the local mirror it answers for.
+                             *
+                             * @param names - The packages to fetch: the target's declared set, or the whole organization.
+                             * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
+                             * @returns One mirror verdict per name, in input order.
+                             */
+                            fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
+                            /**
+                             * Reads 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.
+                             */
+                            read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
+                            /**
+                             * Catalogs the published fleet from the registry's organization package list.
+                             *
+                             * @returns One row per published package, sorted by name.
+                             */
+                            catalog(): Promise<readonly CatalogEntry[]>;
+                            /**
+                             * Tears the reader down, aborting every request in flight. Teardown is idempotent.
+                             *
+                             * @returns Nothing.
+                             */
+                            destroy(): void;
+                        }
+
+                        /**
+                         * Represents the options for the upstream reader.
+                         *
+                         * @remarks
+                         * The endpoints are grouped under the entity each configures: `repository`
+                         * takes the raw content host's `base`, its `branch`, and its `timeout`;
+                         * `registry` takes the registry's `base` and `timeout`. One raw content host
+                         * serves both the fleet's guides and this package's own vendored files, so one
+                         * group configures both. `concurrency` bounds requests in
+                         * flight and `retries` opts into per-request retry on a transport fault.
+                         * `limit` bounds the bytes read from one response body and `budget` bounds the
+                         * bytes read across a whole call, so neither one oversized answer nor many
+                         * small ones can exhaust the caller. Every request is unauthenticated and
+                         * follows no redirect.
+                         */
+                        export declare interface UpstreamOptions {
+                            readonly repository?: {
+                                readonly base?: string;
+                                readonly branch?: string;
+                                readonly timeout?: number;
+                            };
+                            readonly registry?: {
+                                readonly base?: string;
+                                readonly timeout?: number;
+                            };
+                            readonly concurrency?: number;
+                            readonly retries?: number;
+                            readonly limit?: number;
+                            readonly budget?: number;
+                            readonly on?: EmitterHooks<UpstreamEventMap>;
+                            readonly error?: EmitterErrorHandler;
+                        }
+
+                        /**
+                         * Describes what git reports about a target's working tree.
+                         *
+                         * @remarks
+                         * `tracked` is the only set a deletion may draw from: git does not report the
+                         * loss of an untracked path and `git diff` cannot restore it, so an ignored
+                         * path such as an installed dependency tree, a build output, or an editor
+                         * directory survives every verb. `dirty` is every path carrying an uncommitted
+                         * change, taken repo-wide rather than over a write set, because deletion makes
+                         * the write set the whole workspace. A clean tree is an empty `dirty`. A target
+                         * that is not a git repository yields no `Worktree` at all, so the caller
+                         * decides what to do about that rather than reading it out of an invented
+                         * empty value.
+                         */
+                        export declare interface Worktree {
+                            readonly tracked: readonly string[];
+                            readonly dirty: readonly string[];
+                        }
+
+                        /**
+                         * Represents one physical directory identity captured across a write transaction.
+                         *
+                         * @remarks
+                         * Native bigint device and inode values locate the directory and do not date it.
+                         * Two directories occupying one slot at different times share an anchor, so an anchor proves
+                         * where a write lands and never that the directory was left alone.
+                         */
+                        export declare interface WriteAnchor {
+                            readonly path: string;
+                            readonly device: bigint;
+                            readonly inode: bigint;
+                        }
+
+                        /** Reports the final directory anchor of a write transaction and the subset one call created. */
+                        export declare interface WriteDirectoryResult {
+                            readonly anchor: WriteAnchor;
+                            readonly created: readonly WriteAnchor[];
+                        }
+
+                        /**
+                         * Represents one destination snapshot captured before a write and required to survive it.
+                         *
+                         * @remarks
+                         * `device`, `inode`, `modified`, `size`, and `digest` are present only where
+                         * the observed shape supplies them.
+                         */
+                        export declare interface WriteExpectation {
+                            readonly path: string;
+                            readonly shape: 'absent' | 'file' | 'directory';
+                            readonly device?: number;
+                            readonly inode?: number;
+                            readonly modified?: number;
+                            readonly size?: number;
+                            readonly digest?: string;
+                        }
+
+                        /**
+                         * Describes the narrower caller-observed destination state a write transaction must
+                         * still match.
+                         */
+                        export declare interface WritePrecondition {
+                            readonly path: string;
+                            readonly shape: 'absent' | 'file';
+                            readonly digest?: string;
+                        }
+
+                        /**
+                         * Represents one staged, reversible mutation of one target directory.
+                         *
+                         * @remarks
+                         * The transaction owns a private root beside the target — a sibling directory on
+                         * the same volume, so every promotion is a rename rather than a copy. Staging
+                         * writes go into that root and nothing else, so a call that fails while staging
+                         * has not touched the target at all. Commit is the only step that mutates the
+                         * target, and it is the only step that can need rolling back.
+                         *
+                         * A precondition and an expectation hold a destination still. A **precondition** is what the caller
+                         * observed earlier and is checked once, at construction, so a target that moved
+                         * between the caller's read and this transaction fails before anything is
+                         * created. An **expectation** is captured here, at construction, and re-checked
+                         * at commit, so a target that moves while the write is being staged fails before
+                         * anything is promoted.
+                         *
+                         * What this provides, exactly:
+                         *
+                         * - **Across destinations, staged-then-swapped with rollback on a caught
+                         *   failure.** A failure part way through commit restores every destination it
+                         *   already promoted, restores every file it already took, and removes every
+                         *   directory it created, then reports what recovery could not undo. This is
+                         *   measured: a promotion is driven to fail after an earlier one landed, and the
+                         *   earlier destination is read back.
+                         * - **No partly written destination.** Every file is written whole into the
+                         *   private root and digested there before commit, so a destination never
+                         *   receives bytes that were still being produced.
+                         * - **Containment, not continuity, of the directories it creates.** Every
+                         *   ancestor is re-read between `mkdir` calls and again before the first
+                         *   promotion, so an ancestor that became a file, a symlink, a directory
+                         *   elsewhere, or nothing is refused. An ancestor deleted and recreated under
+                         *   the same name can receive its old inode back and is indistinguishable here
+                         *   from one that never moved.
+                         * - **No crash atomicity across destinations.** A process killed between
+                         *   promotions leaves the target holding some new files and some old ones, and
+                         *   leaves the private root behind. Nothing here is a journal, and the private
+                         *   root's name is the only record a later run could read.
+                         *
+                         * A destination is preserved by hard link and then replaced by a single
+                         * `rename`, rather than moved aside and replaced, so the path continues to name
+                         * the old file right up to the swap. That is a property of `rename` on the host,
+                         * not one this package's tests measure: telling it apart from move-then-replace
+                         * needs a reader observing the destination inside the swap, and no test here
+                         * does that. Read the claim as the mechanism it describes, not as a proven
+                         * guarantee about a concurrent reader.
+                         *
+                         * A path names a file this transaction writes, takes, or establishes as a
+                         * directory; every path is target-relative and is measured by the portable-path
+                         * law. An expectation and a precondition both name the resolved destination
+                         * instead, because that is the path each is re-read at.
+                         *
+                         * @example
+                         * ```ts
+                         * import { WriteTransaction } from '@orkestrel/scaffold/server'
+                         *
+                         * const transaction = new WriteTransaction('./packages/router', ['AGENTS.md'])
+                         * try {
+                         * 	transaction.write('AGENTS.md', '# Agents\n')
+                         * 	transaction.commit() // ['AGENTS.md']
+                         * } finally {
+                         * 	transaction.discard()
+                         * }
+                         * ```
+                         */
+                        export declare class WriteTransaction {
+                            #private;
                             /**
-                             * Promotes every staged file and takes every marked file, or rolls the whole call back.
+                             * Opens a transaction over one target directory.
                              *
-                             * @returns Every target-relative path whose destination changed: the files
-                             * promoted, then the directories established, then the files taken.
-                             * @throws {@link ScaffoldError} coded `WRITE` when the transaction is closed,
-                                 * when a destination moved since the transaction opened, or when the commit
-                                 * failed; a failure reports what rollback could not undo in its context.
+                             * @param target - The directory every path is written beneath.
+                             * @param paths - Every target-relative path this transaction may touch.
+                             * @param preconditions - The caller-observed destination states the whole
+                             * transaction is held to, each naming a resolved destination of `paths`.
+                             * @throws {@link ScaffoldError} coded `INVALID` when an argument is off
+                                 * contract, `TARGET` when a destination is a shape this package will not write
+                                 * over or no longer matches its precondition, and `WRITE` when the private
+                                 * root cannot be established.
                                  *
                                  * @remarks
-                                 * Every destination and every directory this transaction created is re-checked
-                                 * before anything moves, so the common failure moves nothing at all. That
-                                 * check runs inside the same rollback as the promotions, because a transaction
-                                 * that refuses before it starts still has a private root and created
-                                 * directories to clear. The transaction is closed either way: a committed one
-                                 * has nothing left to undo and a failed one has already been rolled back.
+                                 * Nothing is created until every destination has been inspected and every
+                                 * precondition has held, so a refused transaction leaves no residue at all.
+                                 * The private root is created last and carries a random name, so two
+                                 * transactions over one target never collide.
                                  */
-                             commit(): readonly string[];
+                             constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
+                             /** Names the resolved directory every path is written beneath. */
+                             get target(): string;
+                             /** Reports what each destination held when the transaction opened, in path order. */
+                             get expectations(): readonly WriteExpectation[];
+                             /** Reports whether the transaction can still be committed or discarded. */
+                             get open(): boolean;
                              /**
-                              * Abandons the transaction and removes everything it created.
+                              * Stages one text file.
                               *
+                              * @param path - The target-relative path to write.
+                              * @param content - The exact UTF-8 text the destination must hold.
                               * @returns Nothing.
-                              * @throws {@link ScaffoldError} coded `WRITE` when residue could not be
-                                  * removed, naming the private root that still holds it.
+                              * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                  * transaction opened or is already staged, `TARGET` when the destination holds
+                                  * a directory, and `WRITE` when the staged file cannot be written or does not
+                                  * carry the bytes it was given.
                                   *
                                   * @remarks
-                                  * Idempotent, and a no-op on a transaction that already committed or already
-                                  * failed, so a caller can put it in a `finally` beside the work it guards.
+                                  * The staged file is read back and digested against the text it was given, so
+                                  * a partial or interrupted write is refused here rather than promoted later.
                                   */
-                              discard(): void;
-                             }
-
-                             export { }
+                              write(path: string, content: string): void;
+                              /**
+                               * Stages one byte-for-byte copy of a file that already exists on this host.
+                               *
+                               * @param path - The target-relative path to write.
+                               * @param source - The resolved absolute path to copy the bytes from.
+                               * @param executable - If `true`, the destination carries the executable bit; if `false`, it does not.
+                               * @returns Nothing.
+                               * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                   * transaction opened or is already staged, `TARGET` when the destination holds
+                                   * a directory or the source is not a physical file, and `WRITE` when the copy
+                                   * cannot be made or does not digest to the source's bytes.
+                                   *
+                                   * @remarks
+                                   * The source is digested before the copy and the copy is digested after it, so
+                                   * a source that changed mid-copy is refused instead of staged.
+                                   */
+                               copy(path: string, source: string, executable: boolean): void;
+                               /**
+                                * Establishes one directory inside the target, one segment at a time.
+                                *
+                                * @param path - The target-relative directory to establish.
+                                * @returns The directory's identity and every segment this call created.
+                                * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                    * transaction opened, `TARGET` when the destination holds a file, and `WRITE`
+                                    * when a segment cannot be created or changed while it was being created.
+                                    *
+                                    * @remarks
+                                    * A directory is created immediately rather than staged, because creating one
+                                    * destroys nothing: rollback removes exactly the segments this call created,
+                                    * innermost first, and leaves every segment that was already there. Each
+                                    * created segment is captured by device and inode, so a segment swapped
+                                    * underneath the transaction is detected rather than written into.
+                                    */
+                                establish(path: string): WriteDirectoryResult;
+                                /**
+                                 * Marks one file for deletion at commit.
+                                 *
+                                 * @param path - The target-relative file to delete.
+                                 * @returns Nothing.
+                                 * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                     * transaction opened or is already claimed, and `TARGET` when the destination
+                                     * does not hold a file.
+                                     *
+                                     * @remarks
+                                     * Nothing moves here. Commit renames the file into the private backup rather
+                                     * than unlinking it, so a later failure in the same commit puts it back.
+                                     */
+                                 remove(path: string): void;
+                                 /**
+                                  * Promotes every staged file and takes every marked file, or rolls the whole call back.
+                                  *
+                                  * @returns Every target-relative path whose destination changed: the files
+                                  * promoted, then the directories established, then the files taken.
+                                  * @throws {@link ScaffoldError} coded `WRITE` when the transaction is closed,
+                                      * when a destination moved since the transaction opened, or when the commit
+                                      * failed; a failure reports what rollback could not undo in its context.
+                                      *
+                                      * @remarks
+                                      * Every destination and every directory this transaction created is re-checked
+                                      * before anything moves, so the common failure moves nothing at all. That
+                                      * check runs inside the same rollback as the promotions, because a transaction
+                                      * that refuses before it starts still has a private root and created
+                                      * directories to clear. The transaction is closed either way: a committed one
+                                      * has nothing left to undo and a failed one has already been rolled back.
+                                      */
+                                  commit(): readonly string[];
+                                  /**
+                                   * Abandons the transaction and removes everything it created.
+                                   *
+                                   * @returns Nothing.
+                                   * @throws {@link ScaffoldError} coded `WRITE` when residue could not be
+                                       * removed, naming the private root that still holds it.
+                                       *
+                                       * @remarks
+                                       * Idempotent, and a no-op on a transaction that already committed or already
+                                       * failed, so a caller can put it in a `finally` beside the work it guards.
+                                       */
+                                   discard(): void;
+                                  }
+
+                                  export { }