@orkestrel/scaffold 0.0.48 → 0.0.50

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

@@ -5,19 +5,21 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { Guard } from '@orkestrel/contract';
+import { HostFile } from '@orkestrel/scaffold';
+import { ManifestRegionSet } from '@orkestrel/scaffold';
 import { Mirror } from '@orkestrel/scaffold';
 import { Plan } from '@orkestrel/scaffold';
 import { Release } from '@orkestrel/scaffold';
 import { Snapshot } from '@orkestrel/scaffold';
 
 /**
- * The Git branch syntax the guide endpoint accepts.
+ * The Git branch syntax the repository endpoint accepts.
  *
  * @remarks
  * A branch is caller-supplied and reaches a URL path, so it is closed to
  * alphanumerics, dot, underscore, hyphen, and the separator, must open with an
  * alphanumeric, and may carry no `..` anywhere. That last refusal is what stops
- * a branch from walking out of the guide directory it addresses.
+ * a branch from walking out of the repository path it addresses.
  */
 export declare const BRANCH_PATTERN: RegExp;
 
@@ -111,6 +113,80 @@ export declare const DIGEST_PATTERN: RegExp;
  */
 export declare const DRIVE_PATTERN: RegExp;
 
+/**
+ * Assemble a whole vendored host from live files and the installed floor.
+ *
+ * @param files - The host-owned vendored files read from the repository, one
+ * row per path.
+ * @param floor - The installed host floor, which fixes the membership a fill
+ * may draw from and supplies the bytes owned by another surface.
+ * @returns The assembled host, or `undefined` when any row produced no answer or
+ * names a path the floor does not declare, or when a host-owned path is absent.
+ *
+ * @remarks
+ * The one place the host-owned all-or-nothing rule is decided, so no verb
+ * restates it. The host surface contributes one baseline: a fill carries live
+ * bytes for every path that surface writes, or it is nothing. A row that failed,
+ * went missing, names an undeclared path, or leaves a host-owned path absent
+ * answers `undefined`. Deferred paths are presence-only and retain the installed
+ * floor bytes that their catalog or mirror surface owns; repair never writes
+ * those floor bytes. One `Host` can therefore carry live host bytes beside floor
+ * bytes without mixing baselines within a surface.
+ *
+ * The emitted entries keep the release's own order and its storage and
+ * executable declarations, and carry digests recomputed over the bytes the fill
+ * actually holds. That is what lets a reader verify the value against itself,
+ * and it is why an undeclared path is refused rather than added: membership
+ * moves with a release, never with a fetch.
+ *
+ * @example
+ * ```ts
+ * import { filesToHost } from '@orkestrel/scaffold/server'
+ *
+ * filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
+ * // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+ * ```
+ */
+export declare function filesToHost(files: readonly HostFile[], floor: Host): Host | undefined;
+
+/**
+ * Projects exact bytes stated in hexadecimal to their SHA-256 digest.
+ *
+ * @param hex - The exact lowercase hexadecimal bytes to digest.
+ * @returns Sixty-four lowercase hexadecimal digits.
+ * @throws `ScaffoldError('INVALID', …)` when `hex` is not exact bounded
+ * lowercase hexadecimal text.
+ *
+ * @example
+ * ```ts
+ * import { hexToDigest } from '@orkestrel/scaffold/server'
+ *
+ * hexToDigest('68690a') // '98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4'
+ * ```
+ */
+export declare function hexToDigest(hex: string): string;
+
+/**
+ * A whole vendored host supplied as a value: the membership beside the bytes filling it.
+ *
+ * @remarks
+ * `manifest` carries the membership, the roots, and the executable declarations
+ * the installed release fixed, and each entry's `digest` is the digest of the
+ * bytes this value actually holds. `bytes` is keyed by each entry's
+ * `destination` and covers exactly the entries the fill holds, so an entry with
+ * no bytes and a byte string under no entry are each a refusal rather than a
+ * gap a reader has to work around.
+ *
+ * Membership never moves without a release. A fill therefore states which of
+ * the release's paths it carries and never introduces one the release did not
+ * declare, which is what keeps a value host's reach identical to the installed
+ * root's however the bytes were obtained.
+ */
+export declare interface Host {
+    readonly manifest: HostManifest;
+    readonly bytes: Snapshot;
+}
+
 /**
  * The complete vendored-host inventory.
  *
@@ -139,10 +215,10 @@ export declare interface HostManifest {
 export declare const INVALID_SEGMENT_CHARACTER_PATTERN: RegExp;
 
 /**
- * Narrow a value to a Git branch the guide endpoint accepts.
+ * Narrow a value to a Git branch the repository endpoint accepts.
  *
  * @remarks
- * A branch reaches the guide URL's path, so the syntax is closed rather than
+ * A branch reaches the repository URL's path, so the syntax is closed rather than
  * merely bounded and no `..` is admitted anywhere in it.
  *
  * @example
@@ -272,6 +348,30 @@ export declare function isExactCaseFile(path: string): boolean;
  */
 export declare function isFilesystemPath(value: unknown): value is string;
 
+/**
+ * Narrow a value to one {@link Host}.
+ *
+ * @remarks
+ * A whole vendored host handed in as a value is as untrusted as one read from a
+ * directory a caller named, so both halves are guarded: the manifest by the same
+ * membership law a read root is held to, and the bytes by the core snapshot law,
+ * which bounds the fill and reads every key as a path and every value as exact
+ * lowercase hexadecimal. Whether those halves agree with each other is the
+ * reader's question rather than this one's, because a guard has only `false` to
+ * say and a mismatch has a path to name.
+ *
+ * @example
+ * ```ts
+ * import { isHost } from '@orkestrel/scaffold/server'
+ *
+ * const digest = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ *
+ * isHost({ manifest: { entries: [], roots: [], digest }, bytes: {} }) // true
+ * isHost({ manifest: { entries: [], roots: [], digest } }) // false
+ * ```
+ */
+export declare const isHost: Guard<Host>;
+
 /**
  * Narrow a value to one {@link HostManifest}.
  *
@@ -319,11 +419,34 @@ export declare function isInventory(value: unknown): value is readonly unknown[]
  * ```ts
  * import { isManifestEntry } from '@orkestrel/scaffold/server'
  *
- * isManifestEntry({ storage: 'AGENTS.md', destination: 'AGENTS.md', executable: false }) // true
+ * isManifestEntry({
+ *   storage: 'AGENTS.md',
+ *   destination: 'AGENTS.md',
+ *   executable: false,
+ *   digest: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+ * }) // true
  * ```
  */
 export declare const isManifestEntry: Guard<ManifestEntry>;
 
+/**
+ * Narrow a value to one {@link ManifestRegionSet}.
+ *
+ * @remarks
+ * The whole closed record a manifest-writing method accepts, so a caller
+ * naming a region the writer does not carry is refused before any byte moves.
+ * Each region is bounded by the same collection law its own list guard applies.
+ *
+ * @example
+ * ```ts
+ * import { isManifestRegionSet } from '@orkestrel/scaffold/server'
+ *
+ * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
+ * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+ * ```
+ */
+export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
+
 /**
  * Narrow a value to the materializer's initial listener record.
  *
@@ -337,6 +460,12 @@ export declare const isMaterializerHooks: Guard<EmitterHooks<MaterializerEventMa
 /**
  * Narrow a value to {@link MaterializerOptions}.
  *
+ * @remarks
+ * `host` admits both representations of one vendored root: a directory path and
+ * a whole {@link Host} value. They share a key because they are one setting
+ * stated two ways rather than two settings, so nothing downstream has to
+ * reconcile a pair that could disagree.
+ *
  * @example
  * ```ts
  * import { isMaterializerOptions } from '@orkestrel/scaffold/server'
@@ -350,6 +479,25 @@ export declare const isMaterializerOptions: Guard<MaterializerOptions>;
 /** Narrow a value to a bounded list of fetched guide mirrors. */
 export declare const isMirrors: Guard<readonly Mirror[]>;
 
+/**
+ * Narrow a value to a bounded list of target-relative paths.
+ *
+ * @remarks
+ * Composed from the core collection and path guards rather than restated, so
+ * the containment law that keeps a caller-supplied path inside its target has
+ * exactly one home. It bounds what a caller may hand a public method, which is
+ * why it is not {@link isInventory}: that one bounds what a checkout may hold.
+ *
+ * @example
+ * ```ts
+ * import { isPaths } from '@orkestrel/scaffold/server'
+ *
+ * isPaths(['AGENTS.md']) // true
+ * isPaths(['../secrets']) // false
+ * ```
+ */
+export declare const isPaths: Guard<readonly string[]>;
+
 /**
  * Test whether a path is a physical directory this package will read or write into.
  *
@@ -393,25 +541,6 @@ export declare function isPhysicalDirectory(path: string): boolean;
  */
 export declare function isPhysicalFile(path: string): boolean;
 
-/**
- * Narrow a value to a {@link Repository}.
- *
- * @remarks
- * Both path lists are target-relative, so both are measured by the core path
- * law: a reported path that is not one this package could have planned is not a
- * path it will delete. The inventory guard bounds the lists, because a checkout
- * is legitimately far larger than any collection a caller hands a method.
- *
- * @example
- * ```ts
- * import { isRepository } from '@orkestrel/scaffold/server'
- *
- * isRepository({ tracked: ['AGENTS.md'], dirty: [] }) // true
- * isRepository({ tracked: ['../secrets'], dirty: [] }) // false
- * ```
- */
-export declare const isRepository: Guard<Repository>;
-
 /**
  * Narrow a value to a per-request timeout in milliseconds.
  *
@@ -447,7 +576,7 @@ export declare const isUpstreamHooks: Guard<EmitterHooks<UpstreamEventMap>>;
  * ```ts
  * import { isUpstreamOptions } from '@orkestrel/scaffold/server'
  *
- * isUpstreamOptions({ guides: { branch: 'main' }, concurrency: 4 }) // true
+ * isUpstreamOptions({ repository: { branch: 'main' }, concurrency: 4 }) // true
  * isUpstreamOptions({ concurrency: 0 }) // false
  * ```
  */
@@ -476,6 +605,25 @@ export declare const isUpstreamOptions: Guard<UpstreamOptions>;
  */
 export declare function isVacant(target: string): boolean;
 
+/**
+ * Narrow a value to a {@link Worktree}.
+ *
+ * @remarks
+ * Both path lists are target-relative, so both are measured by the core path
+ * law: a reported path that is not one this package could have planned is not a
+ * path it will delete. The inventory guard bounds the lists, because a checkout
+ * is legitimately far larger than any collection a caller hands a method.
+ *
+ * @example
+ * ```ts
+ * import { isWorktree } from '@orkestrel/scaffold/server'
+ *
+ * isWorktree({ tracked: ['AGENTS.md'], dirty: [] }) // true
+ * isWorktree({ tracked: ['../secrets'], dirty: [] }) // false
+ * ```
+ */
+export declare const isWorktree: Guard<Worktree>;
+
 /**
  * List a directory's descendant directories as sorted root-relative paths.
  *
@@ -548,11 +696,19 @@ export declare function listFiles(root: string): readonly string[];
  */
 export declare const MANIFEST_NAME = "manifest.json";
 
-/** One file record of the vendored host's manifest. */
+/**
+ * One file record of the vendored host's manifest.
+ *
+ * @remarks
+ * `digest` is the SHA-256 of the file's exact bytes. A live read compares it
+ * against the target's copy, and verifies host-supplied bytes against it before
+ * treating them as that entry.
+ */
 export declare interface ManifestEntry {
     readonly storage: string;
     readonly destination: string;
     readonly executable: boolean;
+    readonly digest: string;
 }
 
 /**
@@ -708,7 +864,7 @@ export declare function matchesPrecondition(precondition: WritePrecondition): bo
  * directories. It is the inversion the contract asks for: the candidate set
  * is re-derived from the plan and narrowed by what git tracks, and the audit
  * must agree with that derivation rather than supply the set itself.
- * Repository metadata is protected because losing history is not a repair,
+ * Git metadata is protected because losing history is not a repair,
  * and a target's own `src` and `app` trees are protected because a
  * workspace's source is the one thing scaffold never plans and never owns. A
  * plan the compiler emits never maps a protected root, so this guard exists
@@ -735,7 +891,7 @@ export declare function matchesProtectedPath(path: string): boolean;
  * The vendoring deny-list. A host root is staged from a real checkout, so the
  * refusal is stated over the path rather than over the file's content: a
  * credential is recognizable by where it sits and what it is called long before
- * anything reads it. Repository metadata is included through
+ * anything reads it. Git metadata is included through
  * {@link matchesGitPath}, so one call answers the whole question and no caller
  * has to remember to ask twice.
  *
@@ -768,6 +924,12 @@ export declare function matchesSensitivePath(path: string): boolean;
  * case, so a manifest naming `agents.md` for a stored `AGENTS.md` is refused on
  * a case-insensitive filesystem rather than silently resolved.
  *
+ * That host arrives as a directory path or as a whole {@link Host} value, and
+ * every verb reads one immutable host either way. A value is owned, verified
+ * against its own membership and digests, and read in memory; a write fills it
+ * into a private root and copies from there, so the executable declarations the
+ * release fixed reach the target from either representation.
+ *
  * What a mutation guarantees is exactly what {@link WriteTransaction}
  * guarantees, and no more: a caught failure part way through a commit rolls the
  * whole commit back, no destination ever receives half-written bytes, and a
@@ -794,18 +956,26 @@ export declare class Materializer implements MaterializerInterface {
     /**
      * Construct a materializer over one vendored host root.
      *
-     * @param options - The vendored host root, the initial listeners, and the
-     * listener-error handler.
+     * @param options - The vendored host, in either representation, the initial
+     * listeners, and the listener-error handler.
      * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
          * is not an option bag this materializer accepts, and `TARGET` when the host
-         * carries a manifest that cannot be read or does not match what it stores.
+         * carries a manifest that cannot be read, does not match what it stores, or
+         * is a value that does not agree with the bytes beside it.
          *
          * @remarks
-         * `host` defaults to this package's own vendored root, resolved from this
-         * module's own location so it never depends on the caller's working
-         * directory. A host carrying no manifest is read as a raw checkout and every
+         * A `host` path defaults to this package's own vendored root, resolved from
+         * this module's own location so it never depends on the caller's working
+         * directory. A root carrying no manifest is read as a raw checkout and every
          * artifact maps onto it one to one.
          *
+         * A `host` value is owned before it is read and then held immutable, so the
+         * bytes this check measured are the bytes every later read returns. It is
+         * verified the way a root is, against the same membership law: the manifest
+         * digest must cover the membership beside it, no two entries may claim one
+         * destination, and the fill must carry exactly one hashing byte string per
+         * declared entry.
+         *
          * The host is read here rather than on first use, so a broken vendored root
          * fails at construction where the caller can still act on it, and so nothing
          * has to carry a second flag recording whether the read has happened yet.
@@ -908,30 +1078,36 @@ export declare class Materializer implements MaterializerInterface {
               */
           catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
           /**
-           * Rewrite the declared dependency ranges the caller names in the target's manifest.
+           * Rewrite the manifest regions the caller names in the target's manifest.
            *
-           * @param dependencies - The names and ranges the manifest must declare.
+           * @param regions - The dependency ranges and script values the manifest must declare.
            * @param target - The directory to write into.
-           * @returns The manifest path, written when a declared range moved and skipped otherwise.
+           * @returns The manifest path, written when a named region moved and skipped otherwise.
            * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
                * exact shape or names a package the manifest does not declare, `TARGET` when
                * the manifest is unreadable, `WRITE` when the write cannot be staged or
                * committed, and `DESTROYED` after teardown.
                *
                * @remarks
-               * No other part of the manifest is read back out or rewritten, so a consumer's
-               * own description, keywords, scripts, and formatting survive the call. Only a
-               * range already declared is rewritten: inserting a package would mean
-               * re-serializing the whole manifest, which is exactly the edit this verb
-               * promises not to make, so an undeclared name is refused by name instead.
+               * No other part of the manifest is read back out or rewritten. The method
+               * never reads or writes `peerDependencies` or `peerDependenciesMeta`. Only a
+               * range already declared in its named writable section is rewritten, so an
+               * undeclared name is refused instead of inserted.
+               *
+               * The regions refuse differently because their targets differ. A range
+               * the manifest does not declare is the caller's mistake and throws. A script
+               * holding a value the region does not accept is the workspace author's own
+               * chain, so the script region is skipped without a byte moving and the range
+               * region is still written. The advisory channel reports what the maintainer
+               * must paste.
                */
-           declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+           declare(regions: ManifestRegionSet, target: string): MaterializeResult;
            /**
             * Re-derive and delete the tracked files the plan does not own.
             *
             * @param plan - The compiled plan that decides which paths are foreign.
             * @param audit - The preview returned by this materializer's `audit` method; it must agree with the candidate set this call re-derives.
-            * @param repository - The target's git state; only a tracked path is ever deleted.
+            * @param worktree - The target's git state; only a tracked path is ever deleted.
             * @param target - The directory to delete from.
             * @returns The paths removed.
             * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
@@ -952,7 +1128,7 @@ export declare class Materializer implements MaterializerInterface {
                 * any foreign finding, including one the deletion itself would skip, because a
                 * preview stale anywhere is stale evidence.
                 */
-            remove(plan: Plan, audit: Audit, repository: Repository, target: string): MaterializeResult;
+            remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
             /**
              * Tear the materializer down. Every later call throws, and teardown is idempotent.
              *
@@ -1062,23 +1238,25 @@ export declare class Materializer implements MaterializerInterface {
                 */
                catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
                /**
-                * Rewrite the declared dependency ranges the caller names in the target's manifest.
+                * Rewrite the manifest regions the caller names in the target's manifest.
                 *
-                * @param dependencies - The names and ranges the manifest must declare.
+                * @param regions - The dependency ranges and script values the manifest must declare.
                 * @param target - The directory to write into.
-                * @returns The manifest path, written when a declared range moved and skipped otherwise.
+                * @returns The manifest path, written when a named region moved and skipped otherwise.
                 *
                 * @remarks
-                * No other part of the manifest is read back out or rewritten, so a
-                * consumer's own description, keywords, and scripts survive the call.
+                * No other part of the manifest is read back out or rewritten. The method
+                * never reads or writes `peerDependencies` or `peerDependenciesMeta`. A
+                * script region naming a value the manifest does not accept is skipped
+                * without a byte moving, and the range region is written regardless.
                 */
-               declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+               declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**
                 * Re-derive and delete the tracked files the plan does not own.
                 *
                 * @param plan - The compiled plan that decides which paths are foreign.
                 * @param audit - The preview returned by this materializer's `audit` method; it must agree with the candidate set this call re-derives.
-                * @param repository - The target's git state; only a tracked path is ever deleted.
+                * @param worktree - The target's git state; only a tracked path is ever deleted.
                 * @param target - The directory to delete from.
                 * @returns The paths removed.
                 *
@@ -1101,7 +1279,7 @@ export declare class Materializer implements MaterializerInterface {
                 * any foreign finding, including one the deletion itself would skip, because a
                 * preview stale anywhere is stale evidence.
                 */
-               remove(plan: Plan, audit: Audit, repository: Repository, target: string): MaterializeResult;
+               remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
                /**
                 * Tear the materializer down. Every later call throws, and teardown is idempotent.
                 *
@@ -1114,19 +1292,21 @@ export declare class Materializer implements MaterializerInterface {
             * Options for the materializer.
             *
             * @remarks
-            * `host` is the vendored data root host-origin artifacts are copied from. It
-            * defaults to this package's own vendored root, resolved from the installed
-            * module's location rather than the caller's working directory. A host that
-            * carries no manifest beside it maps artifact paths one to one instead of
-            * through the manifest.
+            * `host` is the vendored data root host-origin artifacts are copied from, in
+            * either representation. A string is a directory: it defaults to this package's
+            * own vendored root, resolved from the installed module's location rather than
+            * the caller's working directory, and a directory that carries no manifest
+            * beside it maps artifact paths one to one instead of through the manifest. A
+            * {@link Host} is the same root supplied as a value, so a caller that already
+            * holds the bytes never stages them to a directory to be read back.
             */
            export declare interface MaterializerOptions {
-               readonly host?: string;
+               readonly host?: string | Host;
                readonly on?: EmitterHooks<MaterializerEventMap>;
                readonly error?: EmitterErrorHandler;
            }
 
-           /** Maximum characters one guide branch may carry. */
+           /** Maximum characters one repository branch may carry. */
            export declare const MAX_BRANCH_LENGTH = 255;
 
            /** Maximum characters one caller-supplied upstream endpoint may carry. */
@@ -1304,10 +1484,38 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function readFileText(root: string, path: string, limit?: number): string | 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;
+
            /**
             * Read a vendored host's manifest, when it carries one.
             *
             * @param host - The vendored host root to read.
+            * @param name - The root-relative manifest path. Default: `manifest.json`.
             * @returns The manifest, or `undefined` when the host carries none.
             * @throws `ScaffoldError('INVALID', …)` when `host` is not a host path.
             * @throws `ScaffoldError('TARGET', …)` when the manifest is there but cannot be
@@ -1333,7 +1541,7 @@ export declare class Materializer implements MaterializerInterface {
             * readHostManifest('./dist/host') // the manifest, or undefined for a raw root
             * ```
             */
-           export declare function readHostManifest(host: string): HostManifest | undefined;
+           export declare function readHostManifest(host: string, name?: string): HostManifest | undefined;
 
            /**
             * Derive one vendored-host manifest entry from a file in a checkout.
@@ -1359,7 +1567,7 @@ export declare class Materializer implements MaterializerInterface {
             * import { readManifestEntry } from '@orkestrel/scaffold/server'
             *
             * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
-            * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false }
+            * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
             * ```
             */
            export declare function readManifestEntry(destination: string, source: string): ManifestEntry | undefined;
@@ -1395,25 +1603,6 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
 
-           /**
-            * 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 `Repository` at all, so the caller
-            * decides what to do about that rather than reading it out of an invented
-            * empty value.
-            */
-           export declare interface Repository {
-               readonly tracked: readonly string[];
-               readonly dirty: readonly string[];
-           }
-
            /**
             * The Windows device names that stay reserved even when an extension follows.
             *
@@ -1514,6 +1703,42 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function resolveRealPath(path: string): string | undefined;
 
+           /**
+            * Stage the named destinations of a value host into a private root.
+            *
+            * @param host - The host whose bytes are written, keyed by destination.
+            * @param root - The private directory to fill; it must already be a directory
+            * this process may write into.
+            * @param destinations - The destinations to stage, each declared by `host`.
+            * @returns The entry staged for each destination, in the order requested.
+            * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or a
+            * storage name leaves it.
+            * @throws `ScaffoldError('TARGET', …)` when a destination is one the host does
+            * not declare, carries no bytes, or carries bytes that miss its declared digest.
+            * @throws `ScaffoldError('WRITE', …)` when a file cannot be written or does not
+            * read back as the bytes it was given.
+            *
+            * @remarks
+            * Each file lands under the storage name the manifest declares and takes the
+            * executable bit that manifest records, so a root filled from a value is the
+            * same shape as one staged from a checkout and a reader cannot tell them apart.
+            * That is what lets a mutation copy real files with real modes from bytes a
+            * caller supplied, instead of degrading them to plain text writes.
+            *
+            * The bytes are digested before the write and the staged file after it, so a
+            * value that disagrees with its own manifest is told apart from a write that
+            * did not land.
+            *
+            * @example
+            * ```ts
+            * import { stageBytes } from '@orkestrel/scaffold/server'
+            *
+            * stageBytes(host, '/tmp/orkestrel-host-a1b2', ['scripts/codex.sh'])
+            * // [{ storage: 'scripts/codex.sh', destination: 'scripts/codex.sh', executable: true, digest: '…' }]
+            * ```
+            */
+           export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly ManifestEntry[];
+
            /**
             * Stage a vendored host root from a real checkout.
             *
@@ -1568,6 +1793,33 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
 
+           /**
+            * 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;
+
            /**
             * The reading spine: one bounded, unauthenticated, redirect-free request per answer.
             *
@@ -1586,6 +1838,11 @@ export declare class Materializer implements MaterializerInterface {
             * 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
@@ -1608,7 +1865,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare class Upstream implements UpstreamInterface {
                #private;
                /**
-                * Construct a reader over one guide host and one registry.
+                * Construct a reader over one raw content host and one registry.
                 *
                 * @param options - The endpoints, the request bounds, the initial
                 * listeners, and the listener-error handler.
@@ -1684,372 +1941,447 @@ export declare class Materializer implements MaterializerInterface {
                       */
                   fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
                   /**
-                   * Catalog the published fleet from the registry's organization package list.
+                   * Read each named vendored file from the repository, beside the target bytes it answers for.
                    *
-                   * @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.
+                   * @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 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.
+                       * 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()
-                       * const entries = await upstream.catalog()
+                       * await upstream.read(['AGENTS.md'], { 'AGENTS.md': '2320416745' })
                        * upstream.destroy()
                        * ```
                        */
-                   catalog(): Promise<readonly CatalogEntry[]>;
+                   read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
                    /**
-                    * Tear the reader down, aborting every request in flight. Teardown is idempotent.
+                    * Catalog the published fleet from the registry's organization package list.
                     *
-                    * @returns Nothing.
+                    * @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[]>;
+                    /**
+                     * Tear 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;
+                   }
+
+                   /**
+                    * The upstream reader's observation channel.
                     *
                     * @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.
+                    * 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 [];
+                   };
+
+                   /**
+                    * The upstream contract: the package's only network reader, and it never writes.
                     *
-                    * @example
-                    * ```ts
-                    * import { Upstream } from '@orkestrel/scaffold/server'
+                    * @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.
                     *
-                    * const upstream = new Upstream()
-                    * upstream.destroy()
-                    * upstream.emitter.destroyed // true
-                    * ```
+                    * 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.
                     */
-                   destroy(): void;
-                  }
-
-                  /**
-                   * 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 error: readonly [error: unknown];
-                      readonly destroy: readonly [];
-                  };
+                   export declare interface UpstreamInterface {
+                       readonly emitter: EmitterInterface<UpstreamEventMap>;
+                       /**
+                        * Look 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[]>;
+                       /**
+                        * Fetch 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[]>;
+                       /**
+                        * Read each named vendored file from the repository, beside the target bytes it answers for.
+                        *
+                        * @param paths - The target-relative vendored paths to read.
+                        * @param current - The target files as exact bytes, keyed by the same paths.
+                        * @returns One file verdict per path, in input order.
+                        */
+                       read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
+                       /**
+                        * Catalog the published fleet from the registry's organization package list.
+                        *
+                        * @returns One row per published package, sorted by name.
+                        */
+                       catalog(): Promise<readonly CatalogEntry[]>;
+                       /**
+                        * Tear the reader down, aborting every request in flight. Teardown is idempotent.
+                        *
+                        * @returns Nothing.
+                        */
+                       destroy(): void;
+                   }
 
-                  /**
-                   * 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.
-                   */
-                  export declare interface UpstreamInterface {
-                      readonly emitter: EmitterInterface<UpstreamEventMap>;
-                      /**
-                       * Look 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[]>;
-                      /**
-                       * Fetch 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[]>;
-                      /**
-                       * Catalog the published fleet from the registry's organization package list.
-                       *
-                       * @returns One row per published package, sorted by name.
-                       */
-                      catalog(): Promise<readonly CatalogEntry[]>;
-                      /**
-                       * Tear the reader down, aborting every request in flight. Teardown is idempotent.
-                       *
-                       * @returns Nothing.
-                       */
-                      destroy(): void;
-                  }
+                   /**
+                    * 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;
+                   }
 
-                  /**
-                   * Options for the upstream reader.
-                   *
-                   * @remarks
-                   * The endpoints are grouped under the entity each configures: `guides`
-                   * takes the guide host's `base`, its `branch`, and its `timeout`; `registry`
-                   * takes the registry's `base` and `timeout`. `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 guides?: {
-                          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;
-                  }
+                   /**
+                    * 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[];
+                   }
 
-                  /**
-                   * One physical directory identity captured across a write transaction.
-                   *
-                   * @remarks
-                   * Device and inode 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: number;
-                      readonly inode: number;
-                  }
-
-                  /** 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[];
-                  }
+                   /**
+                    * One physical directory identity captured across a write transaction.
+                    *
+                    * @remarks
+                    * Device and inode 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: number;
+                       readonly inode: number;
+                   }
+
+                   /** 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[];
+                   }
 
-                  /**
-                   * 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;
-                  }
-
-                  /** 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;
-                  }
+                   /**
+                    * 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;
+                   }
+
+                   /** 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;
+                   }
 
-                  /**
-                   * 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;
-                      /**
-                       * Open 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.
-                           *
-                           * @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.
-                           */
-                       constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
-                       /** The resolved directory every path is written beneath. */
-                       get target(): string;
-                       /** What each destination held when the transaction opened, in path order. */
-                       get expectations(): readonly WriteExpectation[];
-                       /** Whether the transaction can still be committed or discarded. */
-                       get open(): boolean;
+                   /**
+                    * 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;
                        /**
-                        * Stage one text file.
+                        * Open a transaction over one target directory.
                         *
-                        * @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.
+                        * @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
-                            * 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.
+                            * 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.
                             */
-                        write(path: string, content: string): void;
+                        constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
+                        /** The resolved directory every path is written beneath. */
+                        get target(): string;
+                        /** What each destination held when the transaction opened, in path order. */
+                        get expectations(): readonly WriteExpectation[];
+                        /** Whether the transaction can still be committed or discarded. */
+                        get open(): boolean;
                         /**
-                         * Stage one byte-for-byte copy of a file that already exists on this host.
+                         * Stage one text file.
                          *
                          * @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.
+                         * @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 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.
+                             * a directory, and `WRITE` when the staged file cannot be written or does not
+                             * carry the bytes it was given.
                              *
                              * @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.
+                             * 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.
                              */
-                         copy(path: string, source: string, executable: boolean): void;
+                         write(path: string, content: string): void;
                          /**
-                          * Establish one directory inside the target, one segment at a time.
+                          * Stage one byte-for-byte copy of a file that already exists on this host.
                           *
-                          * @param path - The target-relative directory to establish.
-                          * @returns The directory's identity and every segment this call created.
+                          * @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, `TARGET` when the destination holds a file, and `WRITE`
-                              * when a segment cannot be created or changed while it was being created.
+                              * 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
-                              * 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.
+                              * 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.
                               */
-                          establish(path: string): WriteDirectoryResult;
+                          copy(path: string, source: string, executable: boolean): void;
                           /**
-                           * Mark one file for deletion at commit.
+                           * Establish one directory inside the target, one segment at a time.
                            *
-                           * @param path - The target-relative file to delete.
-                           * @returns Nothing.
+                           * @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 or is already claimed, and `TARGET` when the destination
-                               * does not hold a file.
+                               * 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
-                               * 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.
+                               * 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.
                                */
-                           remove(path: string): void;
+                           establish(path: string): WriteDirectoryResult;
                            /**
-                            * Promote every staged file and take every marked file, or roll the whole call back.
+                            * Mark one file for deletion at commit.
                             *
-                            * @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 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
-                                * 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 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.
                                 */
-                            commit(): readonly string[];
+                            remove(path: string): void;
                             /**
-                             * Abandon the transaction and remove everything it created.
+                             * Promote every staged file and take every marked file, or roll the whole call back.
                              *
-                             * @returns Nothing.
-                             * @throws {@link ScaffoldError} coded `WRITE` when residue could not be
-                                 * removed, naming the private root that still holds it.
+                             * @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
-                                 * 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.
+                                 * 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.
                                  */
-                             discard(): void;
-                            }
-
-                            export { }
+                             commit(): readonly string[];
+                             /**
+                              * Abandon the transaction and remove 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 { }