@orkestrel/scaffold 0.0.25 → 0.0.26

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

@@ -289,12 +289,23 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * the byte ceiling. The character ceiling is read first so an oversized string is
    * refused before it is split.
    *
+   * The two spellings of an empty segment are answered differently. A trailing
+   * separator terminates a directory rather than opening a segment, and every
+   * supported filesystem and every Node path API reads `project/` and `project` as
+   * one location, so it is admitted. A doubled separator is a genuine empty
+   * segment, so `project//src` is refused. Nothing normalizes the argument first —
+   * every server entry point guards the caller's text and resolves it afterwards —
+   * so a directory taken from a shell completion arrives carrying the separator the
+   * shell appended and names the directory it appears to name.
+   *
    * @example
    * ```ts
    * import { isFilesystemPath } from '@orkestrel/scaffold/server'
    *
    * isFilesystemPath('C:/Users/sample/project') // true
    * isFilesystemPath('../sibling') // true
+   * isFilesystemPath('project/') // true
+   * isFilesystemPath('project//src') // false
    * isFilesystemPath('project/nul') // false
    * ```
    */
@@ -560,7 +571,7 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * ```ts
    * import { listFiles } from '@orkestrel/scaffold/server'
    *
-   * listFiles('./dist/host') // ['AGENTS.md', 'claude/rules/names.md', …]
+   * listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
    * ```
    */
   export declare function listFiles(root: string): readonly string[];
@@ -591,9 +602,13 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * device and inode.
    *
    * @remarks
-   * The check a write repeats between steps. A directory replaced by another
-   * directory of the same name answers `false` here, which is the case a path
-   * comparison alone cannot see.
+   * This binds location rather than history. `true` means the path still resolves
+   * to the same physical directory on the same device, so the next write lands
+   * where the last one did. A path now holding nothing, a file, or a symlink
+   * answers `false`; a directory swapped in by `rename` also answers `false`
+   * because the replacement carries its own inode. A directory deleted and made
+   * again under the same name can receive the old inode back and answers `true`,
+   * which nothing here detects.
    *
    * @example
    * ```ts
@@ -605,6 +620,31 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    */
   export declare function matchesAnchor(anchor: WriteAnchor): boolean;
 
+  /**
+   * Test 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}.
+   *
+   * @remarks
+   * The declaration is the whole answer, and deliberately so. Reading the staging
+   * host's mode instead makes the manifest depend on where the package was built:
+   * Windows carries no executable bit, so a host staged there declares every entry
+   * non-executable and every target it later fills receives hooks at `0644`. One
+   * checkout stages one manifest on every host because this predicate never
+   * consults the filesystem.
+   *
+   * @example
+   * ```ts
+   * import { matchesExecutablePath } from '@orkestrel/scaffold/server'
+   *
+   * matchesExecutablePath('scripts/codex.sh') // true
+   * matchesExecutablePath('scripts\\deps.sh') // true
+   * matchesExecutablePath('AGENTS.md') // false
+   * ```
+   */
+  export declare function matchesExecutablePath(path: string): boolean;
+
   /**
    * Test whether a destination still holds what was captured of it.
    *
@@ -861,10 +901,13 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * The audit is a preview, not an instruction. The plan is hydrated and
               * compared against the target again here, and the verdicts that produces must
               * match the ones the audit carried for every path the plan owns; anything else
-              * means the target moved, and the whole call is refused. A missing destination
-              * is restored whatever its ownership; a stale one is replaced only where the
-              * artifact claims its bytes, which is what leaves a presence-owned file a
-              * consumer has edited exactly as it is.
+              * means the target moved, and the whole call is refused. The audit is checked
+              * for agreement rather than for plausibility, so a verdict the comparison could
+              * not have produced — a birth-owned path reported stale, which the `Finding`
+              * shape admits — disagrees with the derived one and is refused. A missing
+              * destination is restored whatever its ownership; a stale one is replaced only
+              * where the artifact claims its bytes, which is what leaves a presence-owned
+              * file a consumer has edited exactly as it is.
               */
           repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
           /**
@@ -1018,6 +1061,20 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                   * @param audit - The preview returned by this materializer's `audit` method.
                   * @param target - The directory to write into.
                   * @returns The paths written and skipped, each decided by its artifact's ownership.
+                  *
+                  * @remarks
+                  * The audit is checked for agreement rather than for plausibility, so a verdict
+                  * the comparison could not have produced — a birth-owned path reported stale,
+                  * which the `Finding` shape admits — disagrees with the derived one and is
+                  * refused.
+                  *
+                  * The whole audit is guarded before any of it is read, so an audit produced by
+                  * an earlier version of this package is refused at runtime rather than only at
+                  * compile time. A planned finding carries `ownership`, which findings made
+                  * before that field existed do not, and the guard refuses the call with
+                  * `INVALID`. Take a fresh audit from this materializer; a stored one is a record
+                  * of what a target looked like then, not an argument to a write now. The
+                  * refusal is deliberate at `0.0.x` and there is no migration.
                   */
                  repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
                  /**
@@ -1062,6 +1119,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                   * unlinked, so a failure part way through restores what it already took.
                   * The package's own source and application trees are never candidates,
                   * whatever the audit reports.
+                  *
+                  * The whole audit is guarded before any of it is read, so an audit produced by
+                  * an earlier version of this package is refused at runtime rather than only at
+                  * compile time. Only foreign findings are candidates and those never carried
+                  * `ownership`, but the guard reads every finding, so one planned finding made
+                  * before that field existed refuses the whole call with `INVALID`. Take a fresh
+                  * audit from this materializer. The refusal is deliberate at `0.0.x` and there
+                  * is no migration.
                   */
                  remove(audit: Audit, repository: Repository, target: string): MaterializeResult;
                  /**
@@ -1175,8 +1240,8 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * @remarks
               * Device and inode rather than the path, because the path is the thing that can
               * be swapped underneath a write. An anchor captured before a mutation and
-              * checked again after it is what proves the directory written into is the
-              * directory that was inspected.
+              * checked again after it proves the directory written into sits where the
+              * inspected one sat, not that it is the one that was inspected.
               *
               * @example
               * ```ts
@@ -1307,14 +1372,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               *
               * @remarks
               * The one place the three declared fields are decided together, because they are
-              * three readings of one file: {@link pathToStorage} decides where it is stored,
-              * the destination is the path it answers for, and the executable bit is read
-              * from the source's own mode.
+              * three readings of one path: {@link pathToStorage} decides where it is stored,
+              * the destination is the path it answers for, and {@link matchesExecutablePath}
+              * decides whether a target receives it executable.
               *
-              * That mode is the honest limit of this reading. A Windows host reports no
-              * executable bit at all, so a host staged there declares every entry
-              * non-executable and a consumer receives scripts without it. Staging on a POSIX
-              * host is what carries the bit through.
+              * The bit is read from that declaration rather than from the source's mode, so
+              * the entry does not depend on where the package was staged. A Windows host
+              * reports no executable bit at all, and reading the mode there declared every
+              * entry non-executable and shipped consumers hooks they could not run.
               *
               * @example
               * ```ts
@@ -1396,20 +1461,31 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               *
               * @remarks
               * The containment law, and the one door every read in this module goes through.
-              * Both sides are resolved through the real filesystem before they are compared,
-              * so a link planted inside the root cannot smuggle a destination out of it; the
-              * answer is then the lexical join, so the caller operates on the path it named
-              * rather than on a resolved form the target may not recognize.
+              * Both sides are resolved through the real filesystem before they are compared.
+              * A dangling link is followed only when its raw target contains no parent
+              * traversal. The answer is then the lexical join of `root` and `path` — an
+              * absolute path under `root`, not a root-relative one — so the caller operates
+              * on the path it named rather than on a resolved form the target may not
+              * recognize. A `root` written with a parent segment is collapsed by that
+              * resolution before anything is read, so containment is measured against the
+              * directory the caller's text names.
               *
               * Comparison is exact text, which fails closed on a case-insensitive
               * filesystem: a root and a path spelled with different case resolve to
               * different strings there and are refused, never wrongly admitted.
               *
+              * The answer describes the namespace this call read. The contract excludes a
+              * concurrent rename or link swap during the call or before the caller finishes
+              * using the returned path. This helper returns a string, not a filesystem
+              * handle, so it cannot bind its containment check to a later operation. A caller
+              * that admits hostile concurrent namespace mutation needs a handle-bound
+              * operation instead.
+              *
               * @example
               * ```ts
               * import { resolveContainedPath } from '@orkestrel/scaffold/server'
               *
-              * resolveContainedPath('/tmp/project', 'guides/router.md') // '/tmp/project/guides/router.md'
+              * resolveContainedPath('/tmp/project', 'guides/router.md')?.endsWith('router.md') // true
               * resolveContainedPath('/tmp/project', '../secrets') // undefined
               * ```
               */
@@ -1419,9 +1495,10 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * Resolve 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 path with its existing prefix resolved through every link, or
-              * `undefined` when the text is not a host path, no bounded existing ancestor
-              * resolves, or an ancestor cannot be read.
+              * @returns The lexical resolution of `path`, with its existing prefix then
+              * resolved through every link, or `undefined` when the text is not a host path,
+              * no bounded existing ancestor resolves, a link target cannot be read, a link
+              * target carries a `..` segment, or an ancestor cannot be read.
               *
               * @remarks
               * A containment decision has to be made about a destination that does not exist
@@ -1431,6 +1508,30 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * it. The climb is bounded by the path-depth ceiling, so an adversarial path
               * cannot make it walk indefinitely.
               *
+              * The caller's own text is collapsed first, which is what `resolve` does with a
+              * `..` the caller wrote: it cancels the segment before it as text, before any
+              * link in that segment is read. So `<root>/hop/..` answers `<root>` even where
+              * `hop` links elsewhere, rather than the directory holding what `hop` points at.
+              * The collapse only ever shortens the caller's path, so nothing reaches outside
+              * it by this; the answer is that lexical location resolved through links, not
+              * the physical location the links lead to. {@link resolveContainedPath} passes
+              * its `root` through here, so a root written with a parent segment is contained
+              * against its collapsed spelling.
+              *
+              * `realpath` answers `ENOENT` both for a name that is not there and for a link
+              * whose target is not there. The name is therefore inspected without following
+              * it: a dangling link redirects the walk to its target, while a genuinely absent
+              * name is retained as one segment of the unresolved suffix. A dangling link
+              * target containing a `..` segment is refused. Resolving that target as one
+              * lexical string could discard a preceding link before the filesystem gives
+              * `..` its physical meaning.
+              *
+              * That target is split on both separators on every host, which is the reading
+              * `isPath` already gives a planned path. A POSIX filename legally containing a
+              * backslash is therefore refused with it: `weird\..\name` is one name to the
+              * host and three segments here. The package keeps one separator law rather than
+              * a host-dependent second one, and this is the conservative side of it.
+              *
               * @example
               * ```ts
               * import { resolveRealPath } from '@orkestrel/scaffold/server'
@@ -1745,7 +1846,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                         readonly error?: EmitterErrorHandler;
                     }
 
-                    /** One physical directory identity captured across a write transaction. */
+                    /**
+                     * 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;
@@ -1810,6 +1918,12 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                      * - **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 two
                      *   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

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

@@ -289,12 +289,23 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * the byte ceiling. The character ceiling is read first so an oversized string is
    * refused before it is split.
    *
+   * The two spellings of an empty segment are answered differently. A trailing
+   * separator terminates a directory rather than opening a segment, and every
+   * supported filesystem and every Node path API reads `project/` and `project` as
+   * one location, so it is admitted. A doubled separator is a genuine empty
+   * segment, so `project//src` is refused. Nothing normalizes the argument first —
+   * every server entry point guards the caller's text and resolves it afterwards —
+   * so a directory taken from a shell completion arrives carrying the separator the
+   * shell appended and names the directory it appears to name.
+   *
    * @example
    * ```ts
    * import { isFilesystemPath } from '@orkestrel/scaffold/server'
    *
    * isFilesystemPath('C:/Users/sample/project') // true
    * isFilesystemPath('../sibling') // true
+   * isFilesystemPath('project/') // true
+   * isFilesystemPath('project//src') // false
    * isFilesystemPath('project/nul') // false
    * ```
    */
@@ -560,7 +571,7 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * ```ts
    * import { listFiles } from '@orkestrel/scaffold/server'
    *
-   * listFiles('./dist/host') // ['AGENTS.md', 'claude/rules/names.md', …]
+   * listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
    * ```
    */
   export declare function listFiles(root: string): readonly string[];
@@ -591,9 +602,13 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    * device and inode.
    *
    * @remarks
-   * The check a write repeats between steps. A directory replaced by another
-   * directory of the same name answers `false` here, which is the case a path
-   * comparison alone cannot see.
+   * This binds location rather than history. `true` means the path still resolves
+   * to the same physical directory on the same device, so the next write lands
+   * where the last one did. A path now holding nothing, a file, or a symlink
+   * answers `false`; a directory swapped in by `rename` also answers `false`
+   * because the replacement carries its own inode. A directory deleted and made
+   * again under the same name can receive the old inode back and answers `true`,
+   * which nothing here detects.
    *
    * @example
    * ```ts
@@ -605,6 +620,31 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
    */
   export declare function matchesAnchor(anchor: WriteAnchor): boolean;
 
+  /**
+   * Test 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}.
+   *
+   * @remarks
+   * The declaration is the whole answer, and deliberately so. Reading the staging
+   * host's mode instead makes the manifest depend on where the package was built:
+   * Windows carries no executable bit, so a host staged there declares every entry
+   * non-executable and every target it later fills receives hooks at `0644`. One
+   * checkout stages one manifest on every host because this predicate never
+   * consults the filesystem.
+   *
+   * @example
+   * ```ts
+   * import { matchesExecutablePath } from '@orkestrel/scaffold/server'
+   *
+   * matchesExecutablePath('scripts/codex.sh') // true
+   * matchesExecutablePath('scripts\\deps.sh') // true
+   * matchesExecutablePath('AGENTS.md') // false
+   * ```
+   */
+  export declare function matchesExecutablePath(path: string): boolean;
+
   /**
    * Test whether a destination still holds what was captured of it.
    *
@@ -861,10 +901,13 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * The audit is a preview, not an instruction. The plan is hydrated and
               * compared against the target again here, and the verdicts that produces must
               * match the ones the audit carried for every path the plan owns; anything else
-              * means the target moved, and the whole call is refused. A missing destination
-              * is restored whatever its ownership; a stale one is replaced only where the
-              * artifact claims its bytes, which is what leaves a presence-owned file a
-              * consumer has edited exactly as it is.
+              * means the target moved, and the whole call is refused. The audit is checked
+              * for agreement rather than for plausibility, so a verdict the comparison could
+              * not have produced — a birth-owned path reported stale, which the `Finding`
+              * shape admits — disagrees with the derived one and is refused. A missing
+              * destination is restored whatever its ownership; a stale one is replaced only
+              * where the artifact claims its bytes, which is what leaves a presence-owned
+              * file a consumer has edited exactly as it is.
               */
           repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
           /**
@@ -1018,6 +1061,20 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                   * @param audit - The preview returned by this materializer's `audit` method.
                   * @param target - The directory to write into.
                   * @returns The paths written and skipped, each decided by its artifact's ownership.
+                  *
+                  * @remarks
+                  * The audit is checked for agreement rather than for plausibility, so a verdict
+                  * the comparison could not have produced — a birth-owned path reported stale,
+                  * which the `Finding` shape admits — disagrees with the derived one and is
+                  * refused.
+                  *
+                  * The whole audit is guarded before any of it is read, so an audit produced by
+                  * an earlier version of this package is refused at runtime rather than only at
+                  * compile time. A planned finding carries `ownership`, which findings made
+                  * before that field existed do not, and the guard refuses the call with
+                  * `INVALID`. Take a fresh audit from this materializer; a stored one is a record
+                  * of what a target looked like then, not an argument to a write now. The
+                  * refusal is deliberate at `0.0.x` and there is no migration.
                   */
                  repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
                  /**
@@ -1062,6 +1119,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                   * unlinked, so a failure part way through restores what it already took.
                   * The package's own source and application trees are never candidates,
                   * whatever the audit reports.
+                  *
+                  * The whole audit is guarded before any of it is read, so an audit produced by
+                  * an earlier version of this package is refused at runtime rather than only at
+                  * compile time. Only foreign findings are candidates and those never carried
+                  * `ownership`, but the guard reads every finding, so one planned finding made
+                  * before that field existed refuses the whole call with `INVALID`. Take a fresh
+                  * audit from this materializer. The refusal is deliberate at `0.0.x` and there
+                  * is no migration.
                   */
                  remove(audit: Audit, repository: Repository, target: string): MaterializeResult;
                  /**
@@ -1175,8 +1240,8 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * @remarks
               * Device and inode rather than the path, because the path is the thing that can
               * be swapped underneath a write. An anchor captured before a mutation and
-              * checked again after it is what proves the directory written into is the
-              * directory that was inspected.
+              * checked again after it proves the directory written into sits where the
+              * inspected one sat, not that it is the one that was inspected.
               *
               * @example
               * ```ts
@@ -1307,14 +1372,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               *
               * @remarks
               * The one place the three declared fields are decided together, because they are
-              * three readings of one file: {@link pathToStorage} decides where it is stored,
-              * the destination is the path it answers for, and the executable bit is read
-              * from the source's own mode.
+              * three readings of one path: {@link pathToStorage} decides where it is stored,
+              * the destination is the path it answers for, and {@link matchesExecutablePath}
+              * decides whether a target receives it executable.
               *
-              * That mode is the honest limit of this reading. A Windows host reports no
-              * executable bit at all, so a host staged there declares every entry
-              * non-executable and a consumer receives scripts without it. Staging on a POSIX
-              * host is what carries the bit through.
+              * The bit is read from that declaration rather than from the source's mode, so
+              * the entry does not depend on where the package was staged. A Windows host
+              * reports no executable bit at all, and reading the mode there declared every
+              * entry non-executable and shipped consumers hooks they could not run.
               *
               * @example
               * ```ts
@@ -1396,20 +1461,31 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               *
               * @remarks
               * The containment law, and the one door every read in this module goes through.
-              * Both sides are resolved through the real filesystem before they are compared,
-              * so a link planted inside the root cannot smuggle a destination out of it; the
-              * answer is then the lexical join, so the caller operates on the path it named
-              * rather than on a resolved form the target may not recognize.
+              * Both sides are resolved through the real filesystem before they are compared.
+              * A dangling link is followed only when its raw target contains no parent
+              * traversal. The answer is then the lexical join of `root` and `path` — an
+              * absolute path under `root`, not a root-relative one — so the caller operates
+              * on the path it named rather than on a resolved form the target may not
+              * recognize. A `root` written with a parent segment is collapsed by that
+              * resolution before anything is read, so containment is measured against the
+              * directory the caller's text names.
               *
               * Comparison is exact text, which fails closed on a case-insensitive
               * filesystem: a root and a path spelled with different case resolve to
               * different strings there and are refused, never wrongly admitted.
               *
+              * The answer describes the namespace this call read. The contract excludes a
+              * concurrent rename or link swap during the call or before the caller finishes
+              * using the returned path. This helper returns a string, not a filesystem
+              * handle, so it cannot bind its containment check to a later operation. A caller
+              * that admits hostile concurrent namespace mutation needs a handle-bound
+              * operation instead.
+              *
               * @example
               * ```ts
               * import { resolveContainedPath } from '@orkestrel/scaffold/server'
               *
-              * resolveContainedPath('/tmp/project', 'guides/router.md') // '/tmp/project/guides/router.md'
+              * resolveContainedPath('/tmp/project', 'guides/router.md')?.endsWith('router.md') // true
               * resolveContainedPath('/tmp/project', '../secrets') // undefined
               * ```
               */
@@ -1419,9 +1495,10 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * Resolve 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 path with its existing prefix resolved through every link, or
-              * `undefined` when the text is not a host path, no bounded existing ancestor
-              * resolves, or an ancestor cannot be read.
+              * @returns The lexical resolution of `path`, with its existing prefix then
+              * resolved through every link, or `undefined` when the text is not a host path,
+              * no bounded existing ancestor resolves, a link target cannot be read, a link
+              * target carries a `..` segment, or an ancestor cannot be read.
               *
               * @remarks
               * A containment decision has to be made about a destination that does not exist
@@ -1431,6 +1508,30 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
               * it. The climb is bounded by the path-depth ceiling, so an adversarial path
               * cannot make it walk indefinitely.
               *
+              * The caller's own text is collapsed first, which is what `resolve` does with a
+              * `..` the caller wrote: it cancels the segment before it as text, before any
+              * link in that segment is read. So `<root>/hop/..` answers `<root>` even where
+              * `hop` links elsewhere, rather than the directory holding what `hop` points at.
+              * The collapse only ever shortens the caller's path, so nothing reaches outside
+              * it by this; the answer is that lexical location resolved through links, not
+              * the physical location the links lead to. {@link resolveContainedPath} passes
+              * its `root` through here, so a root written with a parent segment is contained
+              * against its collapsed spelling.
+              *
+              * `realpath` answers `ENOENT` both for a name that is not there and for a link
+              * whose target is not there. The name is therefore inspected without following
+              * it: a dangling link redirects the walk to its target, while a genuinely absent
+              * name is retained as one segment of the unresolved suffix. A dangling link
+              * target containing a `..` segment is refused. Resolving that target as one
+              * lexical string could discard a preceding link before the filesystem gives
+              * `..` its physical meaning.
+              *
+              * That target is split on both separators on every host, which is the reading
+              * `isPath` already gives a planned path. A POSIX filename legally containing a
+              * backslash is therefore refused with it: `weird\..\name` is one name to the
+              * host and three segments here. The package keeps one separator law rather than
+              * a host-dependent second one, and this is the conservative side of it.
+              *
               * @example
               * ```ts
               * import { resolveRealPath } from '@orkestrel/scaffold/server'
@@ -1745,7 +1846,14 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                         readonly error?: EmitterErrorHandler;
                     }
 
-                    /** One physical directory identity captured across a write transaction. */
+                    /**
+                     * 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;
@@ -1810,6 +1918,12 @@ export declare function computeManifestDigest(entries: readonly ManifestEntry[],
                      * - **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 two
                      *   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