@orkestrel/scaffold 0.0.67 → 0.0.68

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

@@ -91,6 +91,7 @@ export declare function computeFileDigest(path: string): string | undefined;
  *
  * @param entries - The ordered file membership declarations.
  * @param roots - The ordered directory membership declarations.
+ * @param surface - The ordered Surface collisions and their ordered guide owners.
  * @returns The SHA-256 of that exact membership, in that exact order.
  *
  * @remarks
@@ -105,10 +106,10 @@ export declare function computeFileDigest(path: string): string | undefined;
  * ```ts
  * import { computeManifestDigest } from '@orkestrel/scaffold/server'
  *
- * computeManifestDigest([], []) // the digest of the empty membership
+ * computeManifestDigest([], [], []) // the digest of the empty membership
  * ```
  */
-export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[]): string;
+export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
 
 /** Holds the repository branch a raw content read addresses when a caller names none. */
 export declare const DEFAULT_BRANCH = "main";
@@ -263,8 +264,9 @@ export declare interface HostInventory {
  *
  * @remarks
  * `roots` is the sorted directory inventory, which is what distinguishes a
- * declared empty directory. `digest` is the SHA-256 of that exact entry and
- * root membership, so a membership edit that did not update the digest is
+ * declared empty directory. `surface` records only names claimed by distinct
+ * guides, sorted by name with each owner list sorted. `digest` is the SHA-256
+ * of the exact entries, roots, and surface, so an edit without its digest is
  * detected. A self-consistent replacement manifest defines its own smaller
  * membership; authenticating omitted membership is outside a checksum's
  * contract.
@@ -272,9 +274,25 @@ export declare interface HostInventory {
 export declare interface HostManifest {
     readonly entries: readonly ManifestEntry[];
     readonly roots: readonly string[];
+    readonly surface: readonly SurfaceCollision[];
     readonly digest: string;
 }
 
+/**
+ * Configures the committed inventory baseline and staging reports.
+ *
+ * @remarks
+ * `report` receives the baseline location or its absence. Default: no reporting.
+ * `inventory` is relative to the checkout. Default: `host.json`.
+ * `establish`: if `true`, an absent inventory establishes the baseline; if `false`,
+ * an absent inventory refuses staging. Default: `false`.
+ */
+export declare interface HostStageOptions {
+    readonly inventory?: string;
+    readonly establish?: boolean;
+    readonly report?: (message: string) => void;
+}
+
 /**
  * Matches the visible characters no host path segment may carry.
  *
@@ -427,18 +445,19 @@ export declare function isFilesystemPath(value: unknown): value is string;
  * directory a caller named, so both halves are guarded: the manifest by the same
  * membership law a read root is held to, and the bytes by the core snapshot law,
  * which bounds the fill and reads every key as a path and every value as exact
- * lowercase hexadecimal. Whether those halves agree with each other is the
+ * lowercase hexadecimal. The manifest's digest must match its declared entries,
+ * roots, and Surface collisions. Whether the fill agrees with the manifest is the
  * reader's question rather than this one's, because a guard has only `false` to
  * say and a mismatch has a path to name.
  *
  * @example
  * ```ts
- * import { isHost } from '@orkestrel/scaffold/server'
+ * import { computeManifestDigest, isHost } from '@orkestrel/scaffold/server'
  *
- * const digest = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ * const digest = computeManifestDigest([], [], [])
  *
- * isHost({ manifest: { entries: [], roots: [], digest }, bytes: {} }) // true
- * isHost({ manifest: { entries: [], roots: [], digest } }) // false
+ * isHost({ manifest: { entries: [], roots: [], surface: [], digest }, bytes: {} }) // true
+ * isHost({ manifest: { entries: [], roots: [], surface: [], digest } }) // false
  * ```
  */
 export declare const isHost: Guard<Host>;
@@ -449,7 +468,8 @@ export declare const isHost: Guard<Host>;
  * @remarks
  * The manifest is read from a directory a caller named, so it is the least
  * trusted value the server face handles and is guarded whole: every entry, every
- * declared root, and the digest that authenticates their membership.
+ * declared root, sorted Surface collisions with distinct sorted owners, and
+ * the syntax of the digest that authenticates that membership.
  */
 export declare const isHostManifest: Guard<HostManifest>;
 
@@ -1095,7 +1115,8 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns Findings for hydrated planned paths and selected foreign candidates.
+      * @returns Findings for hydrated planned paths and selected foreign candidates,
+      * plus non-blocking questions for present foreign mirrors differing from hosted guides.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -1169,9 +1190,9 @@ export declare class Materializer implements MaterializerInterface {
              * the write cannot be staged or committed, and `DESTROYED` after teardown.
              *
              * @remarks
-             * A verdict carrying no bytes carries a cause instead, so it is skipped rather
-             * than written: one unreachable package never costs the caller the rest of the
-             * fetch, and it never empties a mirror it could not replace.
+             * A failed or absent upstream guide uses the verified hosted guide only when
+             * the observed target copy was absent. A present copy stays untouched. A guide
+             * unavailable from the host is skipped, retaining the upstream verdict.
              */
          mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
          /**
@@ -1356,6 +1377,10 @@ export declare class Materializer implements MaterializerInterface {
                 * @param mirrors - The fetched guides; each carries the local bytes its write is held to.
                 * @param target - The directory to write into.
                 * @returns The mirror paths written and skipped; a mirror already current is skipped.
+                * @remarks
+                * A missing target mirror can use the hosted guide after an upstream failure
+                * or absence. A present mirror stays untouched when upstream supplies no bytes.
+                * The observed target bytes remain the write precondition for either source.
                 */
                mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
                /**
@@ -1793,6 +1818,48 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
 
+           /**
+            * Reads the Surface collision baseline from a committed inventory.
+            *
+            * @param root - The checkout's host path.
+            * @param name - The checkout-relative inventory path. Default: `host.json`.
+            * @returns The recorded collisions, or `undefined` when the inventory is absent.
+            * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or `name` leaves it.
+            * @throws `ScaffoldError('TARGET', …)` when an existing inventory is unreadable,
+            * malformed, or inconsistent with its digest.
+            *
+            * @example
+            * ```ts
+            * import { readSurfaceBaseline } from '@orkestrel/scaffold/server'
+            *
+            * readSurfaceBaseline('.') // the recorded collisions, if the inventory exists
+            * ```
+            */
+           export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
+
+           /**
+            * Reads bare Surface names claimed by distinct package guides.
+            *
+            * @param root - The physical directory containing the package guides.
+            * @returns Colliding names and their distinct owners, sorted by name and owner.
+            * @throws `ScaffoldError('TARGET', …)` when the directory or a guide cannot be read.
+            * @throws `ScaffoldError('TARGET', …)` when `@orkestrel/guide` cannot be loaded.
+            *
+            * @remarks
+            * Reads immediate `.md` files except `README.md` through `createGuide().surface()`.
+            * Requires `@orkestrel/guide` in this module's resolution path; Scaffold declares it
+            * only for development. Loads it only when called, so importing the server entry
+            * requires no guide tooling in a production install.
+            *
+            * @example
+            * ```ts
+            * import { readSurfaceCollisions } from '@orkestrel/scaffold/server'
+            *
+            * readSurfaceCollisions('./guides').get('Shared') // the guides claiming Shared, if it collides
+            * ```
+            */
+           export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
+
            /**
             * Matches the Windows device names that stay reserved even when an extension follows.
             *
@@ -1944,13 +2011,17 @@ export declare class Materializer implements MaterializerInterface {
             *
             * @param checkout - The checkout the vendored paths are read from.
             * @param host - The vendored host root to fill; it must be absent or empty.
+            * @param options - The inventory selection, establishment switch, and reporting callback.
+            * Default: no reporting.
             * @returns One entry per staged file, sorted by storage name.
             * @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
             * or a vendored path leaves the checkout or the host root.
             * @throws `ScaffoldError('TARGET', …)` when the checkout is not a directory, the
             * host root is not vacant, the checkout does not carry every vendored path, two
             * vendored files claim one storage name, a vendored file is not a plain file
-            * within the artifact ceiling, or the staged manifest does not read back.
+            * within the artifact ceiling, published guides are unreadable, a staged
+            * collision's owner set is not a subset of its published owner set, the inventory is absent without
+            * `establish: true`, or the staged manifest does not read back.
             * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
             * be written.
             *
@@ -1968,8 +2039,8 @@ export declare class Materializer implements MaterializerInterface {
             * still; a build output holds nothing, is deleted whole before every build, and
             * has no concurrent reader. What replaces it is refusing early and ordering the
             * writes: the whole membership is derived before anything is created, so a
-            * checkout this refuses leaves no host root at all, and `manifest.json` is
-            * written last, so a stage that failed part way through leaves a root every
+            * membership refusal leaves no host root at all, and `manifest.json` is
+            * written last, so a copy or Surface refusal leaves a root every
             * reader treats as a raw checkout and fails loudly on.
             *
             * A missing vendored path is refused rather than staged around. A partial root
@@ -1979,15 +2050,20 @@ export declare class Materializer implements MaterializerInterface {
             * once. A directory is the same case — declaring an absent directory as an empty
             * root would create an empty directory in every generated workspace.
             *
-            * The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
-            * ships both: a target receives the first set, and reads the second one out of
-            * the installed package. Everything downstream — the missing-path refusal, the
+            * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
+            * A plan selects the paths a target receives; the installed package also carries
+            * the canon and reference files for reading. Every catalog package must have a
+            * guide in the discovered membership before the host is written.
+            * Copied guides must carry no collision whose name and exact owner set the
+            * committed inventory lacks. An absent inventory requires `establish: true`;
+            * an inventory without a valid recorded Surface is refused.
+            * Everything downstream — the missing-path refusal, the
             * storage collision guard, the sort, the digests, and the root inventory — reads
-            * the union, so a canon path is staged under exactly the law a vendored one is.
+            * the union, so every staged path follows the same law.
             *
             * The vendoring deny-list applies to what the walk discovers beneath a staged
             * directory, where a maintainer's local credential can legitimately sit, and
-            * such a path is skipped. A path either list names itself is curated data
+            * such a path is skipped. A path a staging list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
             * @example Vendored data root
@@ -1997,7 +2073,7 @@ export declare class Materializer implements MaterializerInterface {
             * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
             * ```
             */
-           export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
+           export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly ManifestEntry[];
 
            /**
             * Stages the committed inventory of the files a vendored host carries.
@@ -2024,7 +2100,13 @@ export declare class Materializer implements MaterializerInterface {
             * stageInventory(process.cwd(), 'host.json') // the committed host inventory
             * ```
             */
-           export declare function stageInventory(checkout: string, path: string): HostManifest;
+           export declare function stageInventory(checkout: string, path?: string): HostManifest;
+
+           /** Represents a Surface name claimed by distinct package guides. */
+           export declare interface SurfaceCollision {
+               readonly name: string;
+               readonly owners: readonly string[];
+           }
 
            /**
             * Reports the outcome of one bounded read whose body is taken as text.

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

@@ -91,6 +91,7 @@ export declare function computeFileDigest(path: string): string | undefined;
  *
  * @param entries - The ordered file membership declarations.
  * @param roots - The ordered directory membership declarations.
+ * @param surface - The ordered Surface collisions and their ordered guide owners.
  * @returns The SHA-256 of that exact membership, in that exact order.
  *
  * @remarks
@@ -105,10 +106,10 @@ export declare function computeFileDigest(path: string): string | undefined;
  * ```ts
  * import { computeManifestDigest } from '@orkestrel/scaffold/server'
  *
- * computeManifestDigest([], []) // the digest of the empty membership
+ * computeManifestDigest([], [], []) // the digest of the empty membership
  * ```
  */
-export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[]): string;
+export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
 
 /** Holds the repository branch a raw content read addresses when a caller names none. */
 export declare const DEFAULT_BRANCH = "main";
@@ -263,8 +264,9 @@ export declare interface HostInventory {
  *
  * @remarks
  * `roots` is the sorted directory inventory, which is what distinguishes a
- * declared empty directory. `digest` is the SHA-256 of that exact entry and
- * root membership, so a membership edit that did not update the digest is
+ * declared empty directory. `surface` records only names claimed by distinct
+ * guides, sorted by name with each owner list sorted. `digest` is the SHA-256
+ * of the exact entries, roots, and surface, so an edit without its digest is
  * detected. A self-consistent replacement manifest defines its own smaller
  * membership; authenticating omitted membership is outside a checksum's
  * contract.
@@ -272,9 +274,25 @@ export declare interface HostInventory {
 export declare interface HostManifest {
     readonly entries: readonly ManifestEntry[];
     readonly roots: readonly string[];
+    readonly surface: readonly SurfaceCollision[];
     readonly digest: string;
 }
 
+/**
+ * Configures the committed inventory baseline and staging reports.
+ *
+ * @remarks
+ * `report` receives the baseline location or its absence. Default: no reporting.
+ * `inventory` is relative to the checkout. Default: `host.json`.
+ * `establish`: if `true`, an absent inventory establishes the baseline; if `false`,
+ * an absent inventory refuses staging. Default: `false`.
+ */
+export declare interface HostStageOptions {
+    readonly inventory?: string;
+    readonly establish?: boolean;
+    readonly report?: (message: string) => void;
+}
+
 /**
  * Matches the visible characters no host path segment may carry.
  *
@@ -427,18 +445,19 @@ export declare function isFilesystemPath(value: unknown): value is string;
  * directory a caller named, so both halves are guarded: the manifest by the same
  * membership law a read root is held to, and the bytes by the core snapshot law,
  * which bounds the fill and reads every key as a path and every value as exact
- * lowercase hexadecimal. Whether those halves agree with each other is the
+ * lowercase hexadecimal. The manifest's digest must match its declared entries,
+ * roots, and Surface collisions. Whether the fill agrees with the manifest is the
  * reader's question rather than this one's, because a guard has only `false` to
  * say and a mismatch has a path to name.
  *
  * @example
  * ```ts
- * import { isHost } from '@orkestrel/scaffold/server'
+ * import { computeManifestDigest, isHost } from '@orkestrel/scaffold/server'
  *
- * const digest = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+ * const digest = computeManifestDigest([], [], [])
  *
- * isHost({ manifest: { entries: [], roots: [], digest }, bytes: {} }) // true
- * isHost({ manifest: { entries: [], roots: [], digest } }) // false
+ * isHost({ manifest: { entries: [], roots: [], surface: [], digest }, bytes: {} }) // true
+ * isHost({ manifest: { entries: [], roots: [], surface: [], digest } }) // false
  * ```
  */
 export declare const isHost: Guard<Host>;
@@ -449,7 +468,8 @@ export declare const isHost: Guard<Host>;
  * @remarks
  * The manifest is read from a directory a caller named, so it is the least
  * trusted value the server face handles and is guarded whole: every entry, every
- * declared root, and the digest that authenticates their membership.
+ * declared root, sorted Surface collisions with distinct sorted owners, and
+ * the syntax of the digest that authenticates that membership.
  */
 export declare const isHostManifest: Guard<HostManifest>;
 
@@ -1095,7 +1115,8 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns Findings for hydrated planned paths and selected foreign candidates.
+      * @returns Findings for hydrated planned paths and selected foreign candidates,
+      * plus non-blocking questions for present foreign mirrors differing from hosted guides.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -1169,9 +1190,9 @@ export declare class Materializer implements MaterializerInterface {
              * the write cannot be staged or committed, and `DESTROYED` after teardown.
              *
              * @remarks
-             * A verdict carrying no bytes carries a cause instead, so it is skipped rather
-             * than written: one unreachable package never costs the caller the rest of the
-             * fetch, and it never empties a mirror it could not replace.
+             * A failed or absent upstream guide uses the verified hosted guide only when
+             * the observed target copy was absent. A present copy stays untouched. A guide
+             * unavailable from the host is skipped, retaining the upstream verdict.
              */
          mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
          /**
@@ -1356,6 +1377,10 @@ export declare class Materializer implements MaterializerInterface {
                 * @param mirrors - The fetched guides; each carries the local bytes its write is held to.
                 * @param target - The directory to write into.
                 * @returns The mirror paths written and skipped; a mirror already current is skipped.
+                * @remarks
+                * A missing target mirror can use the hosted guide after an upstream failure
+                * or absence. A present mirror stays untouched when upstream supplies no bytes.
+                * The observed target bytes remain the write precondition for either source.
                 */
                mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
                /**
@@ -1793,6 +1818,48 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
 
+           /**
+            * Reads the Surface collision baseline from a committed inventory.
+            *
+            * @param root - The checkout's host path.
+            * @param name - The checkout-relative inventory path. Default: `host.json`.
+            * @returns The recorded collisions, or `undefined` when the inventory is absent.
+            * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path or `name` leaves it.
+            * @throws `ScaffoldError('TARGET', …)` when an existing inventory is unreadable,
+            * malformed, or inconsistent with its digest.
+            *
+            * @example
+            * ```ts
+            * import { readSurfaceBaseline } from '@orkestrel/scaffold/server'
+            *
+            * readSurfaceBaseline('.') // the recorded collisions, if the inventory exists
+            * ```
+            */
+           export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
+
+           /**
+            * Reads bare Surface names claimed by distinct package guides.
+            *
+            * @param root - The physical directory containing the package guides.
+            * @returns Colliding names and their distinct owners, sorted by name and owner.
+            * @throws `ScaffoldError('TARGET', …)` when the directory or a guide cannot be read.
+            * @throws `ScaffoldError('TARGET', …)` when `@orkestrel/guide` cannot be loaded.
+            *
+            * @remarks
+            * Reads immediate `.md` files except `README.md` through `createGuide().surface()`.
+            * Requires `@orkestrel/guide` in this module's resolution path; Scaffold declares it
+            * only for development. Loads it only when called, so importing the server entry
+            * requires no guide tooling in a production install.
+            *
+            * @example
+            * ```ts
+            * import { readSurfaceCollisions } from '@orkestrel/scaffold/server'
+            *
+            * readSurfaceCollisions('./guides').get('Shared') // the guides claiming Shared, if it collides
+            * ```
+            */
+           export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
+
            /**
             * Matches the Windows device names that stay reserved even when an extension follows.
             *
@@ -1944,13 +2011,17 @@ export declare class Materializer implements MaterializerInterface {
             *
             * @param checkout - The checkout the vendored paths are read from.
             * @param host - The vendored host root to fill; it must be absent or empty.
+            * @param options - The inventory selection, establishment switch, and reporting callback.
+            * Default: no reporting.
             * @returns One entry per staged file, sorted by storage name.
             * @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
             * or a vendored path leaves the checkout or the host root.
             * @throws `ScaffoldError('TARGET', …)` when the checkout is not a directory, the
             * host root is not vacant, the checkout does not carry every vendored path, two
             * vendored files claim one storage name, a vendored file is not a plain file
-            * within the artifact ceiling, or the staged manifest does not read back.
+            * within the artifact ceiling, published guides are unreadable, a staged
+            * collision's owner set is not a subset of its published owner set, the inventory is absent without
+            * `establish: true`, or the staged manifest does not read back.
             * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
             * be written.
             *
@@ -1968,8 +2039,8 @@ export declare class Materializer implements MaterializerInterface {
             * still; a build output holds nothing, is deleted whole before every build, and
             * has no concurrent reader. What replaces it is refusing early and ordering the
             * writes: the whole membership is derived before anything is created, so a
-            * checkout this refuses leaves no host root at all, and `manifest.json` is
-            * written last, so a stage that failed part way through leaves a root every
+            * membership refusal leaves no host root at all, and `manifest.json` is
+            * written last, so a copy or Surface refusal leaves a root every
             * reader treats as a raw checkout and fails loudly on.
             *
             * A missing vendored path is refused rather than staged around. A partial root
@@ -1979,15 +2050,20 @@ export declare class Materializer implements MaterializerInterface {
             * once. A directory is the same case — declaring an absent directory as an empty
             * root would create an empty directory in every generated workspace.
             *
-            * The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
-            * ships both: a target receives the first set, and reads the second one out of
-            * the installed package. Everything downstream — the missing-path refusal, the
+            * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
+            * A plan selects the paths a target receives; the installed package also carries
+            * the canon and reference files for reading. Every catalog package must have a
+            * guide in the discovered membership before the host is written.
+            * Copied guides must carry no collision whose name and exact owner set the
+            * committed inventory lacks. An absent inventory requires `establish: true`;
+            * an inventory without a valid recorded Surface is refused.
+            * Everything downstream — the missing-path refusal, the
             * storage collision guard, the sort, the digests, and the root inventory — reads
-            * the union, so a canon path is staged under exactly the law a vendored one is.
+            * the union, so every staged path follows the same law.
             *
             * The vendoring deny-list applies to what the walk discovers beneath a staged
             * directory, where a maintainer's local credential can legitimately sit, and
-            * such a path is skipped. A path either list names itself is curated data
+            * such a path is skipped. A path a staging list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
             * @example Vendored data root
@@ -1997,7 +2073,7 @@ export declare class Materializer implements MaterializerInterface {
             * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
             * ```
             */
-           export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
+           export declare function stageHost(checkout: string, host: string, options?: HostStageOptions): readonly ManifestEntry[];
 
            /**
             * Stages the committed inventory of the files a vendored host carries.
@@ -2024,7 +2100,13 @@ export declare class Materializer implements MaterializerInterface {
             * stageInventory(process.cwd(), 'host.json') // the committed host inventory
             * ```
             */
-           export declare function stageInventory(checkout: string, path: string): HostManifest;
+           export declare function stageInventory(checkout: string, path?: string): HostManifest;
+
+           /** Represents a Surface name claimed by distinct package guides. */
+           export declare interface SurfaceCollision {
+               readonly name: string;
+               readonly owners: readonly string[];
+           }
 
            /**
             * Reports the outcome of one bounded read whose body is taken as text.