@orkestrel/scaffold 0.0.60 → 0.0.62

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

@@ -7,6 +7,7 @@ import { EmitterInterface } from '@orkestrel/emitter';
 import { Group } from '@orkestrel/scaffold';
 import { Guard } from '@orkestrel/contract';
 import { HostFile } from '@orkestrel/scaffold';
+import { Lookup } from '@orkestrel/scaffold';
 import { ManifestRegionSet } from '@orkestrel/scaffold';
 import { Mirror } from '@orkestrel/scaffold';
 import { Plan } from '@orkestrel/scaffold';
@@ -14,7 +15,7 @@ import { Release } from '@orkestrel/scaffold';
 import { Snapshot } from '@orkestrel/scaffold';
 
 /**
- * The Git branch syntax the repository endpoint accepts.
+ * Matches the Git branch syntax the repository endpoint accepts.
  *
  * @remarks
  * A branch is caller-supplied and reaches a URL path, so it is closed to
@@ -25,7 +26,22 @@ import { Snapshot } from '@orkestrel/scaffold';
 export declare const BRANCH_PATTERN: RegExp;
 
 /**
- * Compute the SHA-256 digest of text.
+ * Reports the outcome of one bounded read whose body is taken as exact bytes.
+ *
+ * @remarks
+ * `hex` carries the body as lowercase hexadecimal, and only when `lookup` is
+ * `found`; otherwise it is empty and `note` states what happened. Bytes rather
+ * than text, because a vendored file is compared by digest and a decode would
+ * change what is hashed.
+ */
+export declare interface BytesReadResult {
+    readonly lookup: Lookup;
+    readonly hex: string;
+    readonly note: string;
+}
+
+/**
+ * Computes the SHA-256 digest of text.
  *
  * @param content - The text to digest.
  * @returns Sixty-four lowercase hexadecimal digits.
@@ -48,7 +64,7 @@ export declare const BRANCH_PATTERN: RegExp;
 export declare function computeDigest(content: string): string;
 
 /**
- * Compute the SHA-256 digest of one file's exact bytes.
+ * Computes the SHA-256 digest of one file's exact bytes.
  *
  * @param path - The resolved host path to digest.
  * @returns The digest, or `undefined` when the path is not a physical file, is
@@ -71,7 +87,7 @@ export declare function computeDigest(content: string): string;
 export declare function computeFileDigest(path: string): string | undefined;
 
 /**
- * Compute the digest of a vendored host's declared membership.
+ * Computes the digest of a vendored host's declared membership.
  *
  * @param entries - The ordered file membership declarations.
  * @param roots - The ordered directory membership declarations.
@@ -94,8 +110,41 @@ export declare function computeFileDigest(path: string): string | undefined;
  */
 export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[]): string;
 
+/** Holds the repository branch a raw content read addresses when a caller names none. */
+export declare const DEFAULT_BRANCH = "main";
+
+/** Holds the registry a version read addresses when a caller names none. */
+export declare const DEFAULT_REGISTRY_BASE = "https://registry.npmjs.org";
+
+/** Holds the raw content host a repository read addresses when a caller names none. */
+export declare const DEFAULT_REPOSITORY_BASE = "https://raw.githubusercontent.com";
+
+/**
+ * Sets the simultaneous upstream requests a reader opens with, under
+ * {@link MAX_UPSTREAM_CONCURRENCY}.
+ */
+export declare const DEFAULT_UPSTREAM_CONCURRENCY = 6;
+
+/**
+ * Sets the retries one upstream request is given when a caller names none.
+ *
+ * @remarks
+ * A read is attempted once by default. Retrying is the caller's decision because
+ * a repeated request costs the upstream host, not this package.
+ */
+export declare const DEFAULT_UPSTREAM_RETRIES = 0;
+
+/**
+ * Sets the timeout one upstream request is given when a caller names none, in milliseconds.
+ *
+ * @remarks
+ * Both endpoints open at this value; a caller raises either one on its own up to
+ * {@link MAX_UPSTREAM_TIMEOUT}.
+ */
+export declare const DEFAULT_UPSTREAM_TIMEOUT = 10000;
+
 /**
- * The exact SHA-256 syntax a digest is stated in: sixty-four lowercase hexadecimal digits.
+ * Matches the exact SHA-256 syntax a digest is stated in: sixty-four lowercase hexadecimal digits.
  *
  * @remarks
  * Fixed length, unlike the core byte encoding, because a digest is one value of
@@ -105,7 +154,7 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
 export declare const DIGEST_PATTERN: RegExp;
 
 /**
- * The drive prefix a Windows host path may open with.
+ * Matches the drive prefix a Windows host path may open with.
  *
  * @remarks
  * The one segment allowed to carry a colon. Every other segment is measured by
@@ -115,7 +164,7 @@ export declare const DIGEST_PATTERN: RegExp;
 export declare const DRIVE_PATTERN: RegExp;
 
 /**
- * Assemble a whole vendored host from live files and the installed floor.
+ * Assembles 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.
@@ -129,13 +178,10 @@ export declare const DRIVE_PATTERN: RegExp;
  * 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. A canon path is read the same way for a different reason:
- * the canon is staged for reading rather than for a target, so every canon
- * destination keeps its floor bytes here, claimed or not, and a fill that carries
- * no row for one is complete rather than spoiled. One `Host` can therefore carry
- * live host bytes beside floor bytes without mixing baselines within a surface.
+ * answers `undefined`. Every {@link isFloorPath} destination keeps the installed
+ * floor's bytes instead, claimed or not, so a fill carrying no row for one is
+ * complete rather than spoiled. 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
@@ -175,7 +221,7 @@ export declare function filesToHost(files: readonly HostFile[], floor: Host): Ho
 export declare function hexToDigest(hex: string): string;
 
 /**
- * A whole vendored host supplied as a value: the membership beside the bytes filling it.
+ * Represents 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
@@ -196,7 +242,24 @@ export declare interface Host {
 }
 
 /**
- * The complete vendored-host inventory.
+ * Represents the committed vendored-file inventory as one call's reads are decided against.
+ *
+ * @remarks
+ * `lookup` is the verdict of the inventory read itself, and every row of the
+ * call inherits it when it is not `found`. `digests` maps a target-relative
+ * destination to the exact bytes the inventory declares for it, `duplicates`
+ * names every destination the inventory claims more than once, and `note` states
+ * why a lookup that is not `found` produced no inventory.
+ */
+export declare interface HostInventory {
+    readonly lookup: Lookup;
+    readonly digests: ReadonlyMap<string, string>;
+    readonly duplicates: ReadonlySet<string>;
+    readonly note: string;
+}
+
+/**
+ * Represents the complete vendored-host inventory.
  *
  * @remarks
  * `roots` is the sorted directory inventory, which is what distinguishes a
@@ -213,7 +276,7 @@ export declare interface HostManifest {
 }
 
 /**
- * Visible characters no host path segment may carry.
+ * Matches the visible characters no host path segment may carry.
  *
  * @remarks
  * Narrower than the core path law by exactly one character: a backslash is a
@@ -223,7 +286,7 @@ export declare interface HostManifest {
 export declare const INVALID_SEGMENT_CHARACTER_PATTERN: RegExp;
 
 /**
- * Narrow a value to a Git branch the repository endpoint accepts.
+ * Narrows a value to a Git branch the repository endpoint accepts.
  *
  * @remarks
  * A branch reaches the repository URL's path, so the syntax is closed rather than
@@ -239,14 +302,14 @@ export declare const INVALID_SEGMENT_CHARACTER_PATTERN: RegExp;
  */
 export declare const isBranch: Guard<string>;
 
-/** Narrow a value to a bounded list of fleet catalog rows. */
+/** Narrows a value to a bounded list of fleet catalog rows. */
 export declare const isCatalogEntries: Guard<readonly CatalogEntry[]>;
 
-/** Narrow a value to a bounded list of declared runtime dependencies. */
+/** Narrows a value to a bounded list of declared runtime dependencies. */
 export declare const isDependencies: Guard<readonly Dependency[]>;
 
 /**
- * Narrow a value to a bounded list of `@orkestrel` package names.
+ * Narrows a value to a bounded list of `@orkestrel` package names.
  *
  * @remarks
  * Composed from the core collection and dependency-name guards rather than
@@ -264,7 +327,7 @@ export declare const isDependencies: Guard<readonly Dependency[]>;
 export declare const isDependencyNames: Guard<readonly string[]>;
 
 /**
- * Narrow a value to one exact SHA-256 digest.
+ * Narrows a value to one exact SHA-256 digest.
  *
  * @remarks
  * The identity a vendored host manifest and a write precondition are both stated
@@ -282,7 +345,7 @@ export declare const isDependencyNames: Guard<readonly string[]>;
 export declare const isDigest: Guard<string>;
 
 /**
- * Narrow a value to a bounded upstream endpoint.
+ * Narrows a value to a bounded upstream endpoint.
  *
  * @remarks
  * Length only. Which schemes and hosts an endpoint may name is the reader's law,
@@ -292,11 +355,11 @@ export declare const isDigest: Guard<string>;
 export declare const isEndpoint: Guard<string>;
 
 /**
- * Test whether a path is a physical file with exact on-disk casing.
+ * Tests whether a path is a physical file with exact on-disk casing.
  *
  * @param path - The host path to inspect segment by segment.
- * @returns `true` only for a physical file whose requested segments exactly
- * match the names each parent directory stores.
+ * @returns True if the path is a physical file whose requested segments exactly match
+ * the names each parent directory stores; false otherwise.
  *
  * @remarks
  * A direct file lookup follows the host's case-folding rules on Windows and
@@ -314,11 +377,11 @@ export declare const isEndpoint: Guard<string>;
 export declare function isExactCaseFile(path: string): boolean;
 
 /**
- * Narrow a value to a path naming a location on this host.
+ * Narrows a value to a path naming a location on this host.
  *
  * @param value - The candidate host path.
- * @returns `true` for a bounded absolute or relative path whose every segment is
- * portable across the supported filesystems.
+ * @returns True if the value is a bounded absolute or relative path whose every segment
+ * is portable across the supported filesystems; false otherwise.
  *
  * @remarks
  * The counterpart to the core path law, not a copy of it. A target directory and
@@ -357,7 +420,7 @@ export declare function isExactCaseFile(path: string): boolean;
 export declare function isFilesystemPath(value: unknown): value is string;
 
 /**
- * Narrow a value to one {@link Host}.
+ * Narrows a value to one {@link Host}.
  *
  * @remarks
  * A whole vendored host handed in as a value is as untrusted as one read from a
@@ -381,7 +444,7 @@ export declare function isFilesystemPath(value: unknown): value is string;
 export declare const isHost: Guard<Host>;
 
 /**
- * Narrow a value to one {@link HostManifest}.
+ * Narrows a value to one {@link HostManifest}.
  *
  * @remarks
  * The manifest is read from a directory a caller named, so it is the least
@@ -391,10 +454,11 @@ export declare const isHost: Guard<Host>;
 export declare const isHostManifest: Guard<HostManifest>;
 
 /**
- * Narrow a value to a working-tree inventory within the limit one target may report.
+ * Narrows a value to a working-tree inventory within the limit one target may report.
  *
  * @param value - The candidate inventory.
- * @returns `true` for an array of no more than `MAX_INVENTORY_PATHS` items.
+ * @returns True if the value is an array of no more than
+ * `MAX_INVENTORY_PATHS` items; false otherwise.
  *
  * @remarks
  * Compose this ahead of an element guard exactly as the core collection guard is
@@ -415,7 +479,7 @@ export declare const isHostManifest: Guard<HostManifest>;
 export declare function isInventory(value: unknown): value is readonly unknown[];
 
 /**
- * Narrow a value to one {@link ManifestEntry}.
+ * Narrows a value to one {@link ManifestEntry}.
  *
  * @remarks
  * Both paths are measured by the core path law, because a vendored host's
@@ -438,7 +502,7 @@ export declare function isInventory(value: unknown): value is readonly unknown[]
 export declare const isManifestEntry: Guard<ManifestEntry>;
 
 /**
- * Narrow a value to one {@link ManifestRegionSet}.
+ * Narrows a value to one {@link ManifestRegionSet}.
  *
  * @remarks
  * The whole closed record a manifest-writing method accepts, so a caller
@@ -456,7 +520,7 @@ export declare const isManifestEntry: Guard<ManifestEntry>;
 export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
 
 /**
- * Narrow a value to the materializer's initial listener record.
+ * Narrows a value to the materializer's initial listener record.
  *
  * @remarks
  * Every event is optional and every declared value is a function. A key outside
@@ -466,7 +530,7 @@ export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
 export declare const isMaterializerHooks: Guard<EmitterHooks<MaterializerEventMap>>;
 
 /**
- * Narrow a value to {@link MaterializerOptions}.
+ * Narrows a value to {@link MaterializerOptions}.
  *
  * @remarks
  * `host` admits both representations of one vendored root: a directory path and
@@ -484,11 +548,11 @@ export declare const isMaterializerHooks: Guard<EmitterHooks<MaterializerEventMa
  */
 export declare const isMaterializerOptions: Guard<MaterializerOptions>;
 
-/** Narrow a value to a bounded list of fetched guide mirrors. */
+/** Narrows 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.
+ * Narrows a value to a bounded list of target-relative paths.
  *
  * @remarks
  * Composed from the core collection and path guards rather than restated, so
@@ -507,10 +571,10 @@ export declare const isMirrors: Guard<readonly Mirror[]>;
 export declare const isPaths: Guard<readonly string[]>;
 
 /**
- * Test whether a path is a physical directory this package will read or write into.
+ * Tests whether a path is a physical directory this package will read or write into.
  *
  * @param path - The resolved host path to inspect, without following links.
- * @returns `true` only for a directory that is not a link.
+ * @returns True if the path is a directory that is not a link; false otherwise.
  *
  * @remarks
  * A junction and a directory symbolic link both report as directories after
@@ -528,11 +592,11 @@ export declare const isPaths: Guard<readonly string[]>;
 export declare function isPhysicalDirectory(path: string): boolean;
 
 /**
- * Test whether a path is a physical file this package will read or replace.
+ * Tests whether a path is a physical file this package will read or replace.
  *
  * @param path - The resolved host path to inspect, without following links.
- * @returns `true` only for a regular file that is neither a link nor hard-linked
- * elsewhere.
+ * @returns True if the path is a regular file that is neither a link nor hard-linked
+ * elsewhere; false otherwise.
  *
  * @remarks
  * The link tests are the point. A symbolic link is a path pointing somewhere
@@ -550,7 +614,7 @@ export declare function isPhysicalDirectory(path: string): boolean;
 export declare function isPhysicalFile(path: string): boolean;
 
 /**
- * Narrow a value to a per-request timeout in milliseconds.
+ * Narrows a value to a per-request timeout in milliseconds.
  *
  * @remarks
  * A whole number of milliseconds, at least one and no more than
@@ -560,7 +624,7 @@ export declare function isPhysicalFile(path: string): boolean;
 export declare const isTimeout: Guard<number>;
 
 /**
- * Narrow a value to the upstream reader's initial listener record.
+ * Narrows a value to the upstream reader's initial listener record.
  *
  * @remarks
  * Closed to the reader's own events for the same reason the materializer's
@@ -569,7 +633,7 @@ export declare const isTimeout: Guard<number>;
 export declare const isUpstreamHooks: Guard<EmitterHooks<UpstreamEventMap>>;
 
 /**
- * Narrow a value to {@link UpstreamOptions}.
+ * Narrows a value to {@link UpstreamOptions}.
  *
  * @remarks
  * Each grouped endpoint is closed to its own leaves, so a setting written under
@@ -591,11 +655,11 @@ export declare const isUpstreamHooks: Guard<EmitterHooks<UpstreamEventMap>>;
 export declare const isUpstreamOptions: Guard<UpstreamOptions>;
 
 /**
- * Test whether a target is safe to write a fresh workspace into.
+ * Tests whether a target is safe to write a fresh workspace into.
  *
  * @param target - The candidate target directory.
- * @returns `true` when the target is absent, empty, or holds nothing but its own
- * `.git` directory.
+ * @returns True if the target is absent, empty, or holds nothing but its own `.git`
+ * directory; false otherwise.
  *
  * @remarks
  * The green-field law. A checkout of an empty repository is where a new
@@ -614,7 +678,7 @@ export declare const isUpstreamOptions: Guard<UpstreamOptions>;
 export declare function isVacant(target: string): boolean;
 
 /**
- * Narrow a value to a {@link Worktree}.
+ * Narrows a value to a {@link Worktree}.
  *
  * @remarks
  * Both path lists are target-relative, so both are measured by the core path
@@ -666,7 +730,7 @@ export declare const isWorktree: Guard<Worktree>;
 export declare function listCanonPaths(target: string, groups: readonly Group[]): readonly string[];
 
 /**
- * List a directory's descendant directories as sorted root-relative paths.
+ * Lists a directory's descendant directories as sorted root-relative paths.
  *
  * @param root - The directory to inventory.
  * @returns Every descendant directory as a `/`-separated root-relative path, in
@@ -697,7 +761,7 @@ export declare function listCanonPaths(target: string, groups: readonly Group[])
 export declare function listDirectories(root: string): readonly string[];
 
 /**
- * List a directory's files as sorted root-relative paths.
+ * Lists a directory's files as sorted root-relative paths.
  *
  * @param root - The directory to inventory.
  * @returns Every descendant file as a `/`-separated root-relative path, in
@@ -727,7 +791,7 @@ export declare function listDirectories(root: string): readonly string[];
 export declare function listFiles(root: string): readonly string[];
 
 /**
- * The reserved metadata name a staged vendored host writes at its own root.
+ * Reserves the metadata name a staged vendored host writes at its own root.
  *
  * @remarks
  * The one name a vendored file may never claim, because the staged root holds
@@ -738,7 +802,7 @@ export declare function listFiles(root: string): readonly string[];
 export declare const MANIFEST_NAME = "manifest.json";
 
 /**
- * One file record of the vendored host's manifest.
+ * Represents 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
@@ -753,11 +817,11 @@ export declare interface ManifestEntry {
 }
 
 /**
- * Test whether a captured directory is still the same directory.
+ * Tests whether a captured directory is still the same directory.
  *
  * @param anchor - The identity captured earlier.
- * @returns `true` when the path still holds a physical directory of that exact
- * device and inode.
+ * @returns True if the path still holds a physical directory of that exact device and
+ * inode; false otherwise.
  *
  * @remarks
  * This binds location rather than history. `true` means the path still resolves
@@ -779,10 +843,10 @@ export declare interface ManifestEntry {
 export declare function matchesAnchor(anchor: WriteAnchor): boolean;
 
 /**
- * Test whether a vendored path is one a target receives executable.
+ * Tests whether a vendored path is one a target receives executable.
  *
  * @param path - The target-relative path to classify; either separator is read.
- * @returns `true` when the path is declared in {@link EXECUTABLE_PATHS}.
+ * @returns True if the path is declared in {@link EXECUTABLE_PATHS}; false otherwise.
  *
  * @remarks
  * The declaration is the whole answer, and deliberately so. Reading the staging
@@ -804,10 +868,10 @@ export declare function matchesAnchor(anchor: WriteAnchor): boolean;
 export declare function matchesExecutablePath(path: string): boolean;
 
 /**
- * Test whether a destination still holds what was captured of it.
+ * Tests whether a destination still holds what was captured of it.
  *
  * @param expectation - The state captured earlier.
- * @returns `true` when re-reading the destination produces that same state.
+ * @returns True if re-reading the destination produces that same state; false otherwise.
  *
  * @remarks
  * Compared field for field against a fresh {@link readExpectation}, so an
@@ -826,10 +890,10 @@ export declare function matchesExecutablePath(path: string): boolean;
 export declare function matchesExpectation(expectation: WriteExpectation): boolean;
 
 /**
- * Test whether a path addresses a target's own repository metadata.
+ * Tests whether a path addresses a target's own repository metadata.
  *
  * @param path - The path to classify; either separator is read.
- * @returns `true` for `.git` and for anything beneath it.
+ * @returns True if the path is `.git` or sits beneath it; false otherwise.
  *
  * @remarks
  * The one home of the `.git` membership rule, read in either direction. A target
@@ -850,10 +914,10 @@ export declare function matchesExpectation(expectation: WriteExpectation): boole
 export declare function matchesGitPath(path: string): boolean;
 
 /**
- * Test whether a caught filesystem error reports an absent path.
+ * Tests whether a caught filesystem error reports an absent path.
  *
  * @param error - The caught value.
- * @returns `true` only for an `Error` whose `code` is exactly `ENOENT`.
+ * @returns True if `error` is an `Error` whose `code` is exactly `ENOENT`; false otherwise.
  *
  * @remarks
  * The one place absence is told apart from failure. Every read here answers
@@ -872,11 +936,11 @@ export declare function matchesGitPath(path: string): boolean;
 export declare function matchesMissingPath(error: unknown): boolean;
 
 /**
- * Test whether a destination still matches the narrower state a caller observed.
+ * Tests whether a destination still matches the narrower state a caller observed.
  *
  * @param precondition - The caller-observed state the write is held to.
- * @returns `true` when the destination is absent as stated, or holds a physical
- * file whose bytes digest to the stated value.
+ * @returns True if the destination is absent as stated, or holds a physical file whose
+ * bytes digest to the stated value; false otherwise.
  *
  * @remarks
  * Narrower than {@link matchesExpectation} on purpose. A caller observed bytes,
@@ -895,10 +959,10 @@ export declare function matchesMissingPath(error: unknown): boolean;
 export declare function matchesPrecondition(precondition: WritePrecondition): boolean;
 
 /**
- * Test whether a target-relative path is one no verb may delete.
+ * Tests whether a target-relative path is one no verb may delete.
  *
  * @param path - The target-relative path to classify.
- * @returns `true` when the path must survive every verb this package runs.
+ * @returns True if the path must survive every verb this package runs; false otherwise.
  *
  * @remarks
  * The deletion deny-list, stated as a rule over paths rather than as a list of
@@ -923,10 +987,10 @@ export declare function matchesPrecondition(precondition: WritePrecondition): bo
 export declare function matchesProtectedPath(path: string): boolean;
 
 /**
- * Test whether a path names local configuration or a credential.
+ * Tests whether a path names local configuration or a credential.
  *
  * @param path - The path to classify; either separator is read.
- * @returns `true` when the path must never be copied into a vendored host.
+ * @returns True if the path must never be copied into a vendored host; false otherwise.
  *
  * @remarks
  * The vendoring deny-list. A host root is staged from a real checkout, so the
@@ -948,7 +1012,7 @@ export declare function matchesProtectedPath(path: string): boolean;
 export declare function matchesSensitivePath(path: string): boolean;
 
 /**
- * The mutation spine: read the vendored host, re-derive the target, stage, swap.
+ * Represents the mutation spine: read the vendored host, re-derive the target, stage, swap.
  *
  * @remarks
  * Every verb runs the same steps. It snapshots each caller-supplied value
@@ -995,7 +1059,7 @@ export declare function matchesSensitivePath(path: string): boolean;
 export declare class Materializer implements MaterializerInterface {
     #private;
     /**
-     * Construct a materializer over one vendored host root.
+     * Constructs a materializer over one vendored host root.
      *
      * @param options - The vendored host, in either representation, the initial
      * listeners, and the listener-error handler.
@@ -1022,10 +1086,10 @@ export declare class Materializer implements MaterializerInterface {
          * has to carry a second flag recording whether the read has happened yet.
          */
      constructor(options?: MaterializerOptions);
-     /** The materializer's observation channel. */
+     /** Exposes the materializer's observation channel. */
      get emitter(): EmitterInterface<MaterializerEventMap>;
      /**
-      * Compare a plan with a target through the vendored host that will repair it.
+      * Compares a plan with a target through the vendored host that will repair it.
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
@@ -1051,7 +1115,7 @@ export declare class Materializer implements MaterializerInterface {
           */
       audit(plan: Plan, target: string): Audit;
       /**
-       * Write a plan into a vacant target.
+       * Writes a plan into a vacant target.
        *
        * @param plan - The compiled plan to write.
        * @param target - The directory to write into; it must hold nothing the plan would collide with.
@@ -1070,7 +1134,7 @@ export declare class Materializer implements MaterializerInterface {
            */
        materialize(plan: Plan, target: string): MaterializeResult;
        /**
-        * Write a plan into an existing target, guided by an audit of it.
+        * Writes a plan into an existing target, guided by an audit of it.
         *
         * @param plan - The compiled plan to write.
         * @param audit - The preview returned by this materializer's `audit` method.
@@ -1094,7 +1158,7 @@ export declare class Materializer implements MaterializerInterface {
             */
         repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
         /**
-         * Write fetched dependency guides to their local mirrors.
+         * Writes fetched dependency guides to their local mirrors.
          *
          * @param mirrors - The fetched guides; each carries the local bytes its write is held to.
          * @param target - The directory to write into.
@@ -1110,7 +1174,7 @@ export declare class Materializer implements MaterializerInterface {
              */
          mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
          /**
-          * Rewrite the marker-bounded package table in the target's catalog agent file.
+          * Rewrites the marker-bounded package table in the target's catalog agent file.
           *
           * @param entries - The published packages the table must list.
           * @param target - The directory to write into.
@@ -1128,7 +1192,7 @@ export declare class Materializer implements MaterializerInterface {
               */
           catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
           /**
-           * Rewrite the manifest regions the caller names in the target's manifest.
+           * Rewrites the manifest regions the caller names in the target's manifest.
            *
            * @param regions - The dependency ranges and script values the manifest must declare.
            * @param target - The directory to write into.
@@ -1153,7 +1217,7 @@ export declare class Materializer implements MaterializerInterface {
                */
            declare(regions: ManifestRegionSet, target: string): MaterializeResult;
            /**
-            * Re-derive and delete the tracked files the plan does not own.
+            * Re-derives and deletes 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.
@@ -1191,7 +1255,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
             remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
             /**
-             * Tear the materializer down. Every later call throws, and teardown is idempotent.
+             * Tears the materializer down. Every later call throws, and teardown is idempotent.
              *
              * @returns Nothing.
              *
@@ -1208,7 +1272,7 @@ export declare class Materializer implements MaterializerInterface {
            }
 
            /**
-            * The outcome of one mutation of a target.
+            * Reports the outcome of one mutation of a target.
             *
             * @remarks
             * `written` names every path this call created or replaced. `skipped` names
@@ -1223,7 +1287,7 @@ export declare class Materializer implements MaterializerInterface {
                readonly removed: readonly string[];
            }
 
-           /** The materializer's observation channel. */
+           /** Represents the materializer's observation channel. */
            export declare type MaterializerEventMap = {
                readonly write: readonly [path: string];
                readonly remove: readonly [path: string];
@@ -1233,7 +1297,7 @@ export declare class Materializer implements MaterializerInterface {
            };
 
            /**
-            * The mutation contract: the package's only filesystem writer.
+            * Describes the mutation contract: the package's only filesystem writer.
             *
             * @remarks
             * Every method binds to the observation it was given. It re-derives what it is
@@ -1244,7 +1308,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare interface MaterializerInterface {
                readonly emitter: EmitterInterface<MaterializerEventMap>;
                /**
-                * Compare a plan with a target through the vendored host that will repair it.
+                * Compares a plan with a target through the vendored host that will repair it.
                 *
                 * @param plan - The compiled plan to compare.
                 * @param target - The directory to inspect.
@@ -1252,7 +1316,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                audit(plan: Plan, target: string): Audit;
                /**
-                * Write a plan into a vacant target.
+                * Writes a plan into a vacant target.
                 *
                 * @param plan - The compiled plan to write.
                 * @param target - The directory to write into; it must hold nothing the plan would collide with.
@@ -1260,7 +1324,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                materialize(plan: Plan, target: string): MaterializeResult;
                /**
-                * Write a plan into an existing target, guided by an audit of it.
+                * Writes a plan into an existing target, guided by an audit of it.
                 *
                 * @param plan - The compiled plan to write.
                 * @param audit - The preview returned by this materializer's `audit` method.
@@ -1283,7 +1347,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
                /**
-                * Write fetched dependency guides to their local mirrors.
+                * Writes fetched dependency guides to their local mirrors.
                 *
                 * @param mirrors - The fetched guides; each carries the local bytes its write is held to.
                 * @param target - The directory to write into.
@@ -1291,7 +1355,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
                /**
-                * Rewrite the marker-bounded package table in the target's catalog agent file.
+                * Rewrites the marker-bounded package table in the target's catalog agent file.
                 *
                 * @param entries - The published packages the table must list.
                 * @param target - The directory to write into.
@@ -1299,7 +1363,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
                /**
-                * Rewrite the manifest regions the caller names in the target's manifest.
+                * Rewrites the manifest regions the caller names in the target's manifest.
                 *
                 * @param regions - The dependency ranges and script values the manifest must declare.
                 * @param target - The directory to write into.
@@ -1313,7 +1377,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**
-                * Re-derive and delete the tracked files the plan does not own.
+                * Re-derives and deletes 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.
@@ -1342,7 +1406,7 @@ export declare class Materializer implements MaterializerInterface {
                 */
                remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
                /**
-                * Tear the materializer down. Every later call throws, and teardown is idempotent.
+                * Tears the materializer down. Every later call throws, and teardown is idempotent.
                 *
                 * @returns Nothing.
                 */
@@ -1350,7 +1414,7 @@ export declare class Materializer implements MaterializerInterface {
            }
 
            /**
-            * Options for the materializer.
+            * Represents the options for the materializer.
             *
             * @remarks
             * `host` is the vendored data root host-origin artifacts are copied from, in
@@ -1367,14 +1431,14 @@ export declare class Materializer implements MaterializerInterface {
                readonly error?: EmitterErrorHandler;
            }
 
-           /** Maximum characters one repository branch may carry. */
+           /** Caps the characters one repository branch may carry. */
            export declare const MAX_BRANCH_LENGTH = 255;
 
-           /** Maximum characters one caller-supplied upstream endpoint may carry. */
+           /** Caps the characters one caller-supplied upstream endpoint may carry. */
            export declare const MAX_ENDPOINT_LENGTH = 2048;
 
            /**
-            * Maximum paths one target's working-tree inventory may report.
+            * Caps the paths one target's working-tree inventory may report.
             *
             * @remarks
             * Far above the core collection ceiling, and deliberately so. A tracked or dirty
@@ -1386,7 +1450,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare const MAX_INVENTORY_PATHS = 100000;
 
            /**
-            * Maximum segments one host path may carry.
+            * Caps the segments one host path may carry.
             *
             * @remarks
             * Bounds the work a path decision costs before any filesystem call is made. With
@@ -1396,7 +1460,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare const MAX_PATH_DEPTH = 64;
 
            /**
-            * Maximum UTF-8 bytes one host path segment may encode to.
+            * Caps the UTF-8 bytes one host path segment may encode to.
             *
             * @remarks
             * The limit every supported filesystem shares for a single name. It is a byte
@@ -1406,7 +1470,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare const MAX_PATH_SEGMENT_BYTES = 255;
 
            /**
-            * Maximum simultaneous upstream requests.
+            * Caps the simultaneous upstream requests.
             *
             * @remarks
             * A ceiling rather than a default: the reader picks what it opens by, and this
@@ -1414,14 +1478,29 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare const MAX_UPSTREAM_CONCURRENCY = 64;
 
-           /** Maximum retries one upstream request may be given after a transport fault. */
+           /** Caps the retries one upstream request may be given after a transport fault. */
            export declare const MAX_UPSTREAM_RETRIES = 5;
 
-           /** Maximum timeout one upstream request may be given, in milliseconds. */
+           /** Caps the timeout one upstream request may be given, in milliseconds. */
            export declare const MAX_UPSTREAM_TIMEOUT = 300000;
 
            /**
-            * Project a target-relative path to the storage name a vendored host holds it under.
+            * Names the npm scope and repository owner the fleet's packages and sources are
+            * published under.
+            */
+           export declare const ORKESTREL_SCOPE = "orkestrel";
+
+           /**
+            * Names the media type that selects the registry's abbreviated packument.
+            *
+            * @remarks
+            * Sent on exactly the reads that want a version, so the registry answers with the
+            * smaller document instead of the whole packument.
+            */
+           export declare const PACKUMENT_MEDIA_TYPE = "application/vnd.npm.install-v1+json";
+
+           /**
+            * Projects a target-relative path to the storage name a vendored host holds it under.
             *
             * @param path - The target-relative path the file is written to.
             * @returns The storage name beneath the host root.
@@ -1478,7 +1557,22 @@ export declare class Materializer implements MaterializerInterface {
            export declare function pruneEmptiedDirectories(target: string, removed: readonly string[]): readonly string[];
 
            /**
-            * Capture one directory's physical identity.
+            * 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.
@@ -1499,7 +1593,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readAnchor(path: string): WriteAnchor | undefined;
 
            /**
-            * Capture what one destination holds before a write.
+            * 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
@@ -1523,7 +1617,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readExpectation(path: string): WriteExpectation | undefined;
 
            /**
-            * Read one contained file as its exact bytes in lowercase hexadecimal.
+            * 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.
@@ -1552,7 +1646,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readFileHex(root: string, path: string, limit?: number): string | undefined;
 
            /**
-            * Read one contained file as bounded UTF-8 text.
+            * Reads one contained file as bounded UTF-8 text.
             *
             * @param root - The containing host directory.
             * @param path - The portable root-relative file path.
@@ -1583,7 +1677,7 @@ export declare class Materializer implements MaterializerInterface {
             * @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
+            * @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.
             *
@@ -1605,7 +1699,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readHostFloor(root?: string): Host;
 
            /**
-            * Read a vendored host's manifest, when it carries one.
+            * 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`.
@@ -1637,7 +1731,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readHostManifest(host: string, name?: string): HostManifest | undefined;
 
            /**
-            * Derive one vendored-host manifest entry from a file in a checkout.
+            * 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.
@@ -1666,7 +1760,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readManifestEntry(destination: string, source: string): ManifestEntry | undefined;
 
            /**
-            * Read a target's current bytes at the paths a plan claims.
+            * 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.
@@ -1681,7 +1775,7 @@ export declare class Materializer implements MaterializerInterface {
             * @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; the
+            * 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.
@@ -1697,7 +1791,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
 
            /**
-            * The Windows device names that stay reserved even when an extension follows.
+            * 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
@@ -1707,7 +1801,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare const RESERVED_SEGMENT_PATTERN: RegExp;
 
            /**
-            * Resolve a root-relative path and refuse one that leaves its root.
+            * 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.
@@ -1747,7 +1841,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function resolveContainedPath(root: string, path: string): string | undefined;
 
            /**
-            * Resolve a path through the real filesystem, keeping the part that does not exist yet.
+            * 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
@@ -1797,7 +1891,17 @@ 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.
+            * 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 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
@@ -1833,7 +1937,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare function stageBytes(host: Host, root: string, destinations: readonly string[]): readonly ManifestEntry[];
 
            /**
-            * Stage a vendored host root from a real checkout.
+            * 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.
@@ -1920,7 +2024,24 @@ export declare class Materializer implements MaterializerInterface {
            export declare function stageInventory(checkout: string, path: string): HostManifest;
 
            /**
-            * The reading spine: one bounded, unauthenticated, redirect-free request per answer.
+            * 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;
+           }
+
+           /** 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
@@ -1949,7 +2070,7 @@ export declare class Materializer implements MaterializerInterface {
             * flight instead of waiting for it.
             *
             * The allowance is threaded through the private reads as a mutable
-            * `{ remaining: number }` carrier rather than held on the instance, because
+            * {@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
@@ -1964,7 +2085,7 @@ export declare class Materializer implements MaterializerInterface {
            export declare class Upstream implements UpstreamInterface {
                #private;
                /**
-                * Construct a reader over one raw content host and one registry.
+                * 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.
@@ -1983,10 +2104,10 @@ export declare class Materializer implements MaterializerInterface {
                     * is refused too: this reader authenticates nothing and appends its own path.
                     */
                 constructor(options?: UpstreamOptions);
-                /** The upstream reader's observation channel. */
+                /** Exposes the upstream reader's observation channel. */
                 get emitter(): EmitterInterface<UpstreamEventMap>;
                 /**
-                 * Look up the newest release each declared range admits.
+                 * 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.
@@ -2012,7 +2133,7 @@ export declare class Materializer implements MaterializerInterface {
                      */
                  lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
                  /**
-                  * Fetch each named package's guide, beside the local mirror it answers for.
+                  * 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.
@@ -2040,7 +2161,7 @@ export declare class Materializer implements MaterializerInterface {
                       */
                   fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
                   /**
-                   * Read each named vendored file from the repository, beside the target bytes it answers for.
+                   * 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.
@@ -2080,7 +2201,7 @@ export declare class Materializer implements MaterializerInterface {
                        */
                    read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
                    /**
-                    * Catalog the published fleet from the registry's organization package list.
+                    * 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
@@ -2108,7 +2229,7 @@ export declare class Materializer implements MaterializerInterface {
                         */
                     catalog(): Promise<readonly CatalogEntry[]>;
                     /**
-                     * Tear the reader down, aborting every request in flight. Teardown is idempotent.
+                     * Tears the reader down, aborting every request in flight. Teardown is idempotent.
                      *
                      * @returns Nothing.
                      *
@@ -2130,7 +2251,7 @@ export declare class Materializer implements MaterializerInterface {
                    }
 
                    /**
-                    * The upstream reader's observation channel.
+                    * Represents the upstream reader's observation channel.
                     *
                     * @remarks
                     * Each verdict is published whole rather than as a name beside a summary, so a
@@ -2147,7 +2268,7 @@ export declare class Materializer implements MaterializerInterface {
                    };
 
                    /**
-                    * The upstream contract: the package's only network reader, and it never writes.
+                    * 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
@@ -2163,14 +2284,14 @@ export declare class Materializer implements MaterializerInterface {
                    export declare interface UpstreamInterface {
                        readonly emitter: EmitterInterface<UpstreamEventMap>;
                        /**
-                        * Look up the newest release each declared range admits.
+                        * 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[]>;
                        /**
-                        * Fetch each named package's guide, beside the local mirror it answers for.
+                        * 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.
@@ -2178,7 +2299,7 @@ export declare class Materializer implements MaterializerInterface {
                         */
                        fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
                        /**
-                        * Read each named vendored file from the repository, beside the target bytes it answers for.
+                        * 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.
@@ -2186,13 +2307,13 @@ export declare class Materializer implements MaterializerInterface {
                         */
                        read(paths: readonly string[], current: Snapshot): Promise<readonly HostFile[]>;
                        /**
-                        * Catalog the published fleet from the registry's organization package list.
+                        * Catalogs 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.
+                        * Tears the reader down, aborting every request in flight. Teardown is idempotent.
                         *
                         * @returns Nothing.
                         */
@@ -2200,7 +2321,7 @@ export declare class Materializer implements MaterializerInterface {
                    }
 
                    /**
-                    * Options for the upstream reader.
+                    * Represents the options for the upstream reader.
                     *
                     * @remarks
                     * The endpoints are grouped under the entity each configures: `repository`
@@ -2233,7 +2354,7 @@ export declare class Materializer implements MaterializerInterface {
                    }
 
                    /**
-                    * What git reports about a target's working tree.
+                    * 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
@@ -2252,7 +2373,7 @@ export declare class Materializer implements MaterializerInterface {
                    }
 
                    /**
-                    * One physical directory identity captured across a write transaction.
+                    * Represents one physical directory identity captured across a write transaction.
                     *
                     * @remarks
                     * Device and inode locate the directory and do not date it. Two directories
@@ -2265,14 +2386,14 @@ export declare class Materializer implements MaterializerInterface {
                        readonly inode: number;
                    }
 
-                   /** The final directory anchor of a write transaction and the subset one call created. */
+                   /** 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[];
                    }
 
                    /**
-                    * One destination snapshot captured before a write and required to survive it.
+                    * Represents one destination snapshot captured before a write and required to survive it.
                     *
                     * @remarks
                     * `device`, `inode`, `modified`, `size`, and `digest` are present only where
@@ -2288,7 +2409,10 @@ export declare class Materializer implements MaterializerInterface {
                        readonly digest?: string;
                    }
 
-                   /** The narrower caller-observed destination state a write transaction must still match. */
+                   /**
+                    * Describes the narrower caller-observed destination state a write transaction must
+                    * still match.
+                    */
                    export declare interface WritePrecondition {
                        readonly path: string;
                        readonly shape: 'absent' | 'file';
@@ -2296,7 +2420,7 @@ export declare class Materializer implements MaterializerInterface {
                    }
 
                    /**
-                    * One staged, reversible mutation of one target directory.
+                    * Represents one staged, reversible mutation of one target directory.
                     *
                     * @remarks
                     * The transaction owns a private root beside the target — a sibling directory on
@@ -2363,7 +2487,7 @@ export declare class Materializer implements MaterializerInterface {
                    export declare class WriteTransaction {
                        #private;
                        /**
-                        * Open a transaction over one target directory.
+                        * 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.
@@ -2381,14 +2505,14 @@ export declare class Materializer implements MaterializerInterface {
                             * transactions over one target never collide.
                             */
                         constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
-                        /** The resolved directory every path is written beneath. */
+                        /** Names the resolved directory every path is written beneath. */
                         get target(): string;
-                        /** What each destination held when the transaction opened, in path order. */
+                        /** Reports what each destination held when the transaction opened, in path order. */
                         get expectations(): readonly WriteExpectation[];
-                        /** Whether the transaction can still be committed or discarded. */
+                        /** Reports whether the transaction can still be committed or discarded. */
                         get open(): boolean;
                         /**
-                         * Stage one text file.
+                         * Stages one text file.
                          *
                          * @param path - The target-relative path to write.
                          * @param content - The exact UTF-8 text the destination must hold.
@@ -2404,7 +2528,7 @@ export declare class Materializer implements MaterializerInterface {
                              */
                          write(path: string, content: string): void;
                          /**
-                          * Stage one byte-for-byte copy of a file that already exists on this host.
+                          * 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.
@@ -2421,7 +2545,7 @@ export declare class Materializer implements MaterializerInterface {
                               */
                           copy(path: string, source: string, executable: boolean): void;
                           /**
-                           * Establish one directory inside the target, one segment at a time.
+                           * 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.
@@ -2438,7 +2562,7 @@ export declare class Materializer implements MaterializerInterface {
                                */
                            establish(path: string): WriteDirectoryResult;
                            /**
-                            * Mark one file for deletion at commit.
+                            * Marks one file for deletion at commit.
                             *
                             * @param path - The target-relative file to delete.
                             * @returns Nothing.
@@ -2452,7 +2576,7 @@ export declare class Materializer implements MaterializerInterface {
                                 */
                             remove(path: string): void;
                             /**
-                             * Promote every staged file and take every marked file, or roll the whole call back.
+                             * 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.
@@ -2470,7 +2594,7 @@ export declare class Materializer implements MaterializerInterface {
                                  */
                              commit(): readonly string[];
                              /**
-                              * Abandon the transaction and remove everything it created.
+                              * Abandons the transaction and removes everything it created.
                               *
                               * @returns Nothing.
                               * @throws {@link ScaffoldError} coded `WRITE` when residue could not be