@orkestrel/scaffold 0.0.23 → 0.0.25

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

@@ -1,1382 +1,1967 @@
 import { Audit } from '@orkestrel/scaffold';
-import { Blueprint } from '@orkestrel/scaffold';
-import { BooleanShape } from '@orkestrel/contract';
 import { CatalogEntry } from '@orkestrel/scaffold';
-import { ContractInterface } from '@orkestrel/contract';
 import { Dependency } from '@orkestrel/scaffold';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
-import { GuideSync } from '@orkestrel/scaffold';
-import { HostArtifact } from '@orkestrel/scaffold';
-import { NumberShape } from '@orkestrel/contract';
-import { ObjectShape } from '@orkestrel/contract';
-import { OptionalShape } from '@orkestrel/contract';
+import { Guard } from '@orkestrel/contract';
+import { Mirror } from '@orkestrel/scaffold';
 import { Plan } from '@orkestrel/scaffold';
-import { ScaffoldErrorCode } from '@orkestrel/scaffold';
+import { Release } from '@orkestrel/scaffold';
 import { Snapshot } from '@orkestrel/scaffold';
-import { StringShape } from '@orkestrel/contract';
-import { SyncReport } from '@orkestrel/scaffold';
-import { VersionSync } from '@orkestrel/scaffold';
-
-/** One mutable aggregate entry allowance shared by fleet catalog roots. */
-export declare type CatalogAllowance = Float64Array;
 
 /**
- * Build the fleet package catalog — one `CatalogEntry` per `@orkestrel/*`
- * package discovered under each root, its description drawn from its own
- * guide's FIRST blockquote.
+ * The Git branch syntax the guide endpoint accepts.
  *
- * @param roots - The fleet root directories to scan (each walked via `discoverPackages`).
  * @remarks
- * Per discovered package directory: `name` / `version` come from its own
- * `package.json`; `description` is the first paragraph of the guide's opening
- * blockquote — the flattened text of the FIRST `ParagraphNode` among the
- * FIRST `BlockquoteNode` found's (depth-first, pre-order, via `walkNodes`)
- * TOP-LEVEL children in its `guides/src/<short>.md` (`<short>` = `name` with
- * the `@orkestrel/` prefix stripped), parsed with `@orkestrel/markdown`'s
- * `parseDocument` — a multi-paragraph blockquote overview yields only its
- * FIRST paragraph, never the whole quote glued together; embedded newlines
- * collapse to single spaces, and surrounding whitespace trims. A
- * missing/unreadable guide, a guide carrying no blockquote, or a blockquote
- * with no top-level paragraph child, yields `description: ''`, never a
- * thrown error. Entries merge across `roots` (a later root's entry for a
- * repeated `name` wins), then code-unit sort by `name`. An unreadable ROOT
- * itself is NOT wrapped here — whatever `discoverPackages` throws for it
- * propagates as-is; the bin layer is responsible for coding that failure
- * `TARGET`.
- * @returns The merged, sorted `CatalogEntry[]`.
- *
- * @example
- * ```ts
- * import { catalogPackages } from '@orkestrel/scaffold/server'
- *
- * catalogPackages(['/repos']) // [{ name: '@orkestrel/contract', version: '0.0.5', description: '…' }, …]
- * ```
+ * A branch is caller-supplied and reaches a URL path, so it is closed to
+ * alphanumerics, dot, underscore, hyphen, and the separator, must open with an
+ * alphanumeric, and may carry no `..` anywhere. That last refusal is what stops
+ * a branch from walking out of the guide directory it addresses.
  */
-export declare function catalogPackages(roots: readonly string[], limit?: number): readonly CatalogEntry[];
+export declare const BRANCH_PATTERN: RegExp;
 
 /**
- * Promote a complete staged set and roll every earlier destination back when
- * any later promotion fails.
- *
- * @param transaction - Same-volume sibling staging state.
- * @param paths - Portable target-relative files to promote.
- * @throws `ScaffoldError('WRITE', ...)` with recovery details on failure.
- */
-export declare function commitWriteTransaction(transaction: WriteTransaction, paths: readonly string[]): void;
-
-/** Consume one aggregate fleet-catalog traversal slot. */
-export declare function consumeCatalogAllowance(allowance: CatalogAllowance, root: string): void;
-
-/**
- * Create a `MaterializerInterface` (server) — the materialization entity,
- * seeded from `MaterializerOptions`.
- *
- * @param options - Optional `host` root override, emitter hooks, and error handler
- * @returns A {@link MaterializerInterface}
+ * Compute the SHA-256 digest of text.
  *
- * @example
- * ```ts
- * import { createMaterializer } from '@orkestrel/scaffold/server'
- *
- * const materializer = createMaterializer()
- * materializer.destroy()
- * ```
- */
-export declare function createMaterializer(options?: MaterializerOptions): MaterializerInterface;
-
-/**
- * Create a `SyncInterface` (server) — the upstream-synchronization entity,
- * seeded from `SyncOptions`.
+ * @param content - The text to digest.
+ * @returns Sixty-four lowercase hexadecimal digits.
  *
- * @param options - Optional endpoint bases/branch, concurrency, retries, strict, emitter hooks, and error handler
- * @returns A {@link SyncInterface}
+ * @remarks
+ * The identity the server face states, and the reason it differs from core's:
+ * core settled on a folded 64-bit identity because compilation is synchronous by
+ * contract and the only cryptographic digest a host-independent scope reaches is
+ * asynchronous. A Node host reaches the real one synchronously, and
+ * `HostManifest.digest` is documented as SHA-256, so this is what the server
+ * uses everywhere a digest is claimed.
  *
  * @example
  * ```ts
- * import { createSync } from '@orkestrel/scaffold/server'
+ * import { computeDigest } from '@orkestrel/scaffold/server'
  *
- * const sync = createSync()
- * sync.destroy()
+ * computeDigest('hi\n') // '98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4'
  * ```
  */
-export declare function createSync(options?: SyncOptions): SyncInterface;
+export declare function computeDigest(content: string): string;
 
 /**
- * Create a physical directory path one segment at a time behind captured identities.
+ * Compute the SHA-256 digest of one file's exact bytes.
  *
- * @param path - The absolute directory path to establish.
- * @param boundary - The boundary name used in diagnostics.
- * @returns The final directory anchor and the subset created by this call.
- */
-export declare function createWriteDirectory(path: string, boundary: string): WriteDirectoryResult;
-
-/** Default cumulative response bytes retained by one Sync operation. */
-export declare const DEFAULT_SYNC_BUDGET = 16777216;
-
-/** Default simultaneous upstream requests used by `Sync`. */
-export declare const DEFAULT_SYNC_CONCURRENCY = 6;
-
-/** Default maximum dependencies or catalog entries retained by one Sync operation. */
-export declare const DEFAULT_SYNC_ITEMS = 256;
-
-/** Default per-response byte limit used by `Sync`. */
-export declare const DEFAULT_SYNC_LIMIT = 5242880;
-
-/** Default per-request timeout used by `Sync`, in milliseconds. */
-export declare const DEFAULT_SYNC_TIMEOUT = 10000;
-
-/**
- * Reconstruct a `Blueprint` from an EXISTING repo at `target` — the faithful
- * inverse `audit` / `repair` / `mirror` need to diff a live package against
- * its own would-be scaffold, rather than a fresh, dependency-less stand-in.
+ * @param path - The resolved host path to digest.
+ * @returns The digest, or `undefined` when the path is not a physical file, is
+ * past the artifact ceiling, or moved while it was being read.
  *
- * @param target - The existing package directory to derive a `Blueprint` from.
  * @remarks
- * A scoped package name is stripped to its bounded safe short name. An
- * unscoped name is accepted only when the target is app-only, `private: true`,
- * and the name satisfies `isWorkspaceName`; every other name is a coded
- * `TARGET` failure. `src` is derived from `src/<environment>/` and `app` from
- * `app/<environment>/`; a target with no environment on either axis is also a coded
- * `TARGET` failure. The `bin` and `integration` facts probe physical
- * directories at `src/bin` and `tests/integration`. `services` is the sorted
- * set of direct vendor directories under `tests/service` that contain a test
- * at any depth, while `global` probes the physical exact-case `tests/setupGlobal.ts` file and `showcase`
- * probes the physical exact-case `configs/app/vite.showcase.config.ts` regular file; none is
- * inferred from the workspace name. `dependencies` /
- * `peers` are the `@orkestrel/`-prefixed entries of `manifest.dependencies` /
- * `manifest.peerDependencies` (a peer flagged `peerDependenciesMeta[name]
- * .optional === true` carries `optional: true`). `extras` is EVERY entry of
- * `manifest.devDependencies` (not only `@orkestrel/`-prefixed ones — an
- * external extra like `zod` must round-trip too), EXCLUDING the complete
- * generated dependency set `devDependenciesFor` emits for the reconstructed
- * blueprint's actual environments and structural axes. A devDependency ALSO present in
- * `manifest.peerDependencies` or `manifest.dependencies` (e.g. a peer
- * dev-installed for local testing) is likewise excluded from `extras` — it
- * already appears as a `peer`/`dependency` above, and double-counting it as
- * an `extra` would land it in `peers ∩ extras`, a blocking `validateBlueprint`
- * gate. `overrides` is always `[]` — derivation cannot recover a caller's
- * artifact-override intent from repository state.
- * @returns The reconstructed `Blueprint`.
- * @throws `ScaffoldError('TARGET', …)` when `target`'s manifest is unreadable
- *   (via `readManifest`), is not valid JSON, its name is unsafe for its
- *   publication mode, or `target` carries no source or application environment.
- * @throws `ScaffoldError('INVALID', …)` when service tests use the retired flat
- *   layout, a vendor directory has no test, or a service companion is missing.
+ * Read in bounded chunks rather than loaded whole, so digesting a large file
+ * costs one buffer instead of its size. The file's identity and size are
+ * measured before and after the read and a mismatch answers `undefined`, so a
+ * digest is either of one settled file or is not produced at all.
  *
  * @example
  * ```ts
- * import { deriveBlueprint } from '@orkestrel/scaffold/server'
+ * import { computeFileDigest } from '@orkestrel/scaffold/server'
  *
- * deriveBlueprint('./packages/router') // { name: 'router', src: ['core', 'server'], … }
+ * computeFileDigest('/tmp/project/AGENTS.md') // the file's SHA-256
+ * computeFileDigest('/tmp/project/absent.md') // undefined
  * ```
  */
-export declare function deriveBlueprint(target: string): Blueprint;
-
-/**
- * Compute a bounded-memory SHA-256 digest for one file.
- *
- * @param path - The file to read.
- * @returns Its lowercase SHA-256 digest.
- */
-export declare function digestFile(path: string): string;
-
-/**
- * Compute SHA-256 from exact lowercase hexadecimal bytes without decoding the whole value at once.
- *
- * @param hex - Exact hexadecimal bytes.
- * @returns Their lowercase SHA-256 digest.
- */
-export declare function digestHex(hex: string): string;
+export declare function computeFileDigest(path: string): string | undefined;
 
 /**
- * Digest the exact declared membership of a vendored host manifest.
+ * Compute the digest of a vendored host's declared membership.
  *
  * @param entries - The ordered file membership declarations.
  * @param roots - The ordered directory membership declarations.
- * @returns A SHA-256 digest independent of the manifest's stored digest field.
- */
-export declare function digestHostManifest(entries: readonly ManifestEntry[], roots: readonly string[]): string;
-
-/**
- * Compute SHA-256 from UTF-8 text.
- *
- * @param value - The text to hash.
- * @returns Its lowercase SHA-256 digest.
- */
-export declare function digestText(value: string): string;
-
-/**
- * Remove an uncommitted or already-committed write transaction's private residue.
- *
- * @param transaction - The transaction to discard.
- * @throws `ScaffoldError('WRITE', ...)` when its private root cannot be removed.
- */
-export declare function discardWriteTransaction(transaction: WriteTransaction): void;
-
-/**
- * List a fleet root's `@orkestrel/*` package directories.
- *
- * @param root - The fleet root directory to scan.
- * @returns Absolute, code-unit-sorted paths of `root`'s immediate child
- *   directories whose `package.json` parses and whose `name` starts with
- *   `@orkestrel/`. A child with an unreadable or unparsable `package.json`,
- *   or a non-`@orkestrel` name, is skipped silently — it simply is not a
- *   fleet member.
- * @throws `ScaffoldError('TARGET', …)` when a child directory name contains
- *   terminal controls and therefore cannot be safely inspected or reported.
- *
- * @example
- * ```ts
- * import { discoverPackages } from '@orkestrel/scaffold/server'
- *
- * discoverPackages('./packages') // ['/abs/packages/router', '/abs/packages/budget']
- * ```
- */
-export declare function discoverPackages(root: string, allowance?: CatalogAllowance): readonly string[];
-
-/**
- * Render the local pointer written when an upstream dependency guide is not vendored yet.
- *
- * @param source - The canonical `guides/src/<name>.md` source path.
- * @returns The deterministic pointer content.
- */
-export declare function guideStub(source: string): string;
-
-/**
- * Extract the first paragraph from the first blockquote in a Markdown guide.
- *
- * @param text - The guide Markdown to traverse.
- * @returns A normalized one-line description, or `undefined` when parsing
- *   fails, no blockquote paragraph exists, or the paragraph is empty.
- *
- * @example
- * ```ts
- * import { guideToDescription } from '@orkestrel/scaffold/server'
- *
- * guideToDescription('> A concise package description.\n>\n> More detail.')
- * // 'A concise package description.'
- * ```
- */
-export declare function guideToDescription(text: string): string | undefined;
-
-/** One validated guide update and its contained destination. */
-export declare interface GuideWrite {
-    readonly guide: GuideSync;
-    readonly destination: string;
-}
-
-/** Reserved metadata file written at the root of every staged host. */
-export declare const HOST_MANIFEST_PATH = "manifest.json";
-
-/** A complete vendored-host inventory with file entries and declared directory roots. */
-export declare interface HostManifest {
-    readonly entries: readonly ManifestEntry[];
-    readonly roots: readonly string[];
-    /** SHA-256 of the exact declared entry/root membership. */
-    readonly digest: string;
-}
-
-/**
- * Locate this MODULE's own installed package root — the nearest ancestor of
- * `import.meta.url` holding a `package.json` — and return its vendored
- * `dist/host` data root. THE single source of truth for the default
- * `Materializer` / `scaffold` bin host: once installed, walking up from the
- * module's own file (not `process.cwd()`, which points at whichever project
- * happens to be running) resolves to `node_modules/@orkestrel/scaffold`, the
- * correct default host — the package ships its vendored data with itself.
- * `dist/host` may not exist yet when this resolves from SOURCE under a test
- * runner; that is fine — existence is checked at the point of use, not here.
- *
- * @returns The absolute vendored `dist/host` path.
- * @throws `ScaffoldError('TARGET', …)` when no ancestor of this module's own
- *   location holds a `package.json`.
- *
- * @example
- * ```ts
- * import { hostRoot } from '@orkestrel/scaffold/server'
- *
- * hostRoot() // '/…/node_modules/@orkestrel/scaffold/dist/host'
- * ```
- */
-export declare function hostRoot(): string;
-
-/**
- * Rehydrate a `Plan`'s `host`-origin artifacts with their exact byte hex read
- * from `host` — manifest-aware, via `locateHostSource`.
- *
- * @param plan - The plan to hydrate.
- * @param host - The resolved host root to read from.
- * @returns A new `Plan` whose file-shaped `host` artifacts carry exact `hex`.
- *   Directory-shaped host artifacts expand into one byte-aware artifact
- *   per file, preserving their group and mapping the artifact/source prefixes.
- *   `template` / `computed` artifacts pass through untouched.
- * @throws `ScaffoldError('TARGET', …)` when the host is not a readable
- *   directory, a present manifest is invalid/incomplete, or a required source
- *   is absent, escaping, not a file/directory as declared, or unreadable.
- *
- * @example
- * ```ts
- * import { hydratePlan } from '@orkestrel/scaffold/server'
- *
- * const hydrated = hydratePlan(plan, './dist/host')
- * ```
- */
-export declare function hydratePlan(plan: Plan, host: string): Plan;
-
-/** Narrow one exact aggregate fleet traversal allowance. */
-export declare function isCatalogAllowance(value: unknown): value is CatalogAllowance;
-
-/** Whether a normalized catalog description is bounded and contains no controls. */
-export declare function isCatalogDescription(value: unknown): value is string;
-
-/** Whether one dependency is an exact data-property record safe to snapshot. */
-export declare function isDependencyData(value: unknown): value is Dependency;
-
-/** Whether one host filesystem path is bounded, non-empty, and safe to render in a terminal. */
-export declare function isFilesystemPath(value: unknown): value is string;
-
-/**
- * Narrow a value to one exact complete vendored-host manifest.
- *
- * @param value - The candidate manifest value.
- * @returns `true` only for an exact `{ entries, roots, digest }` record with safe paths.
- */
-export declare function isHostManifest(value: unknown): value is HostManifest;
-
-/**
- * Narrow a value to one exact vendored-host manifest entry.
- *
- * @param value - The candidate raw manifest entry.
- * @returns `true` only for the exact safe entry shape.
- */
-export declare function isManifestEntry(value: unknown): value is ManifestEntry;
-
-/** Narrow an exact initial-listener record for `Materializer`. */
-export declare function isMaterializerEventHooks(value: unknown): value is EmitterHooks<MaterializerEventMap>;
-
-/**
- * Determine whether a caught filesystem error reports an absent path.
- *
- * @param value - The caught value.
- * @returns `true` only for an `Error` whose `code` is exactly `ENOENT`.
- */
-export declare function isMissingPathError(value: unknown): boolean;
-
-/**
- * Determine whether a value is a non-empty portable relative POSIX path.
- *
- * @param value - The candidate path.
- * @returns `true` when every path segment is safe and portable.
- */
-export declare function isPortablePath(value: unknown): value is string;
-
-/**
- * Whether a path is an existing physical directory rather than a file or link.
- *
- * @param path - The filesystem path to inspect without following links.
- * @returns `true` only for a successful `lstat` reporting a directory.
- */
-export declare function isRealDirectory(path: string): boolean;
-
-/**
- * Whether a path is an existing physical file rather than a directory or link.
- *
- * @param path - The filesystem path to inspect without following links.
- * @returns `true` only for a successful `lstat` reporting a single-link file.
- */
-export declare function isRealFile(path: string): boolean;
-
-/** Determine whether a target-relative path addresses preserved repository metadata. */
-export declare function isReservedTargetPath(value: string): boolean;
-
-/**
- * Determine whether a host-relative path resembles local configuration or credentials.
- *
- * @param value - The portable candidate path.
- * @returns `true` when the path must be excluded from vendored host output.
- */
-export declare function isSensitiveHostPath(value: string): boolean;
-
-/** Narrow an exact initial-listener record for `Sync`. */
-export declare function isSyncEventHooks(value: unknown): value is EmitterHooks<SyncEventMap>;
-
-/** Whether one externally supplied string is safe to render in terminal or JSON diagnostics. */
-export declare function isTerminalText(value: unknown): value is string;
-
-/**
- * Whether a target path is absent, empty, or contains nothing but a `.git`
- * directory — the green-field target law `Materializer.materialize` enforces.
- *
- * @param target - The candidate target directory path.
- * @returns `true` when `target` is safe to materialize a fresh package into.
- *
- * @example
- * ```ts
- * import { isVacant } from '@orkestrel/scaffold/server'
- *
- * isVacant('./packages/router-new') // true — absent, empty, or only a .git dir
- * ```
- */
-export declare function isVacant(target: string): boolean;
-
-/** Narrow one exact transaction destination precondition. */
-export declare function isWritePrecondition(value: unknown): value is WritePrecondition;
-
-/**
- * Recursively list a directory's descendant directories.
- *
- * @param root - The directory to list.
- * @returns Root-relative POSIX directory paths in code-unit order.
- */
-export declare function listDirectories(root: string): readonly string[];
-
-/**
- * Recursively list a directory's files as root-relative paths.
- *
- * @param root - The directory to list.
- * @returns Root-relative file paths (posix-style `/` separators), code-unit
- *   sorted, or `[]` when `root` is absent.
- *
- * @example
- * ```ts
- * import { listFiles } from '@orkestrel/scaffold/server'
- *
- * listFiles('./dist/host/.claude/agents') // ['scout.md', 'builder.md', …]
- * ```
- */
-export declare function listFiles(root: string): readonly string[];
-
-/**
- * Resolve the absolute host-storage path for a host-origin artifact's
- * `source`, manifest-aware.
- *
- * @param manifest - The parsed complete host manifest, or `undefined`
- *   when the host carries none (raw-repo-root fallback).
- * @param source - The artifact's `source` (or `path`) to resolve.
- * @param host - The resolved host root the path is joined against.
- * @returns `join(host, source)` when `manifest` is `undefined` (no vendored
- *   staging indirection); when `manifest` is present, `join(host,
- *   entries[0].storage)` for the SINGLE manifest entry whose `destination`
- *   equals `source`, or `undefined` when zero or more than one entry matches
- *   (`source` names a directory, or the manifest is ambiguous — no single
- *   storage file to point at).
- *
- * @example
- * ```ts
- * import { locateHostSource } from '@orkestrel/scaffold/server'
- *
- * locateHostSource(undefined, 'package.json', './dist/host') // './dist/host/package.json'
- * locateHostSource(
- *   {
- *     entries: [{ storage: 'pkg.tmpl', destination: 'package.json', executable: false }],
- *     roots: [],
- *     digest: '3b52f19450237ea4cfb39bc7a77b1e5094b52a8ff1fc9c02fd68b13ad088aa0f',
- *   },
- *   'package.json',
- *   './dist/host',
- * )
- * // './dist/host/pkg.tmpl'
- * ```
- */
-export declare function locateHostSource(manifest: HostManifest | undefined, source: string, host: string): string | undefined;
-
-/** One entry of the vendored host's `manifest.json` (server). */
-export declare interface ManifestEntry {
-    readonly storage: string;
-    readonly destination: string;
-    readonly executable: boolean;
-}
-
-/**
- * The materialization entity (server) — the only impure environment in the
- * package, writing a `Plan` to `node:fs` behind an explicit call.
- *
- * @remarks
- * `materialize` is green-field: it refuses any target `isVacant` rejects
- * (`ScaffoldError('TARGET', …)`), then byte-copies each `host` artifact from
- * the `host` root and writes each `template` / `computed` artifact's rendered
- * `content`, failing fast on any write error (`ScaffoldError('WRITE', …)`).
- * `repair` is into-existing: it skips the vacancy check and writes `missing`
- * artifacts an `Audit` names. `stale` artifacts are report-only unless its
- * `replace` switch is true, because byte replacement discards local changes.
- * Hydrated directory-shaped host entries are expanded into
- * file-shaped artifacts, so canonical skills and agent configuration are
- * audited and repaired file by file. `prune` deletes stale files under
- * `target/.claude/agents/`, `target/.codex/agents/`, and `target/scripts/`
- * that the vendored `host` does not name. After `destroy()`
- * every method throws `DESTROYED`; teardown is idempotent, emitter last.
- * Before the vacancy check or any write, `materialize` and `repair` require a
- * structural `isPlan` match and a valid `validatePlan` result. Contextual
- * overrides that are missing from the artifact set, host-owned, or target
- * `package.json` therefore fail closed instead of being silently ignored.
- *
- * @remarks
- * `host`-origin copies are MANIFEST-AWARE: when the resolved `host` root
- * carries a `manifest.json` (this package's own vendored `dist/host`), each
- * artifact's `source` (a destination-relative path) is looked up in the
- * manifest to find its un-dotted STORAGE path plus an `executable` bit
- * (applied via `chmodSync` after the copy) — the vendored-package shape,
- * where storage names avoid leading dots npm would otherwise mangle. When
- * `host` carries no `manifest.json` (a caller-supplied raw repo root, e.g. a
- * sibling checkout or a test fixture), `source` maps to `host` 1:1, exactly
- * as before.
- *
- * @remarks
- * A manifest-present `source` with ZERO matching entries degrades to a stub
- * ONLY when that `source` is a dependency-guide pointer — one that starts
- * with `guides/src/` and ends with `.md` (the `guides/src/<dep>.md` pointer
- * `Compiler` emits for any dependency outside this package's vendored set).
- * That is the ONLY zero-match case that is legitimate: every `HOST_PATHS`
- * source is always staged by `stageHost`, so a non-guide zero-match means a
- * corrupted or truncated `manifest.json`, not an intentionally-unvendored
- * artifact. For a guide pointer, a short stub file is written at the
- * destination and reported exactly like a successful copy. The READ path
- * leaves that intentional pointer without canonical bytes, so `diffPlan`
- * treats it as presence-owned rather than inventing a byte match.
- * For every OTHER zero-match, the
- * fail-closed `ScaffoldError('TARGET', …)` is thrown — degrading an
- * unscoped zero-match would otherwise let a corrupted manifest silently stub
- * an unrecoverable artifact (e.g. `AGENTS.md` — `pull` only ever fetches
- * dependency guides) or write a FILE named `.claude` over what should be a
- * directory artifact. The raw-root fallback (`manifest === undefined`, a
- * caller-supplied `--from`) keeps its own throw regardless: an EXPLICITLY
- * named source failing to resolve is a different, caller-error failure
- * class, not a "not vendored" degrade.
- *
- * @remarks
- * Defense in depth at the filesystem trust boundary: EVERY resolved
- * destination (`materialize` and `repair`, both origins) is asserted to stay
- * within `resolve(target)` before any write, and every `host`-origin copy
- * source is asserted to stay within `resolve(host)` before any read — a
- * traversal segment (`../`) in an artifact's `path` or `source` cannot escape
- * either root, even if a gate upstream (e.g. an ungated `Plan` built by hand)
- * let it through. A destination violation throws `ScaffoldError('WRITE', …)`;
- * a source violation throws `ScaffoldError('TARGET', …)`.
- *
- * @remarks
- * The containment check is REAL-PATH aware, not merely lexical: both the
- * root (`target` / `host`) and the candidate destination/source are resolved
- * through `realpathSync` on their DEEPEST EXISTING ancestor before the prefix
- * comparison, so a symlinked subdirectory planted inside an otherwise
- * legitimate root cannot smuggle a write (or read) outside it — `repair`,
- * which has no `isVacant` gate, is covered exactly like `materialize`. A path
- * segment that does not yet exist on disk (the still-to-be-created file/dir
- * a write is about to create) is rejoined onto the resolved existing
- * ancestor rather than realpath'd itself.
- *
- * @example
- * ```ts
- * import { blueprint, blueprintToPlan } from '@orkestrel/scaffold'
- * import { createMaterializer } from '@orkestrel/scaffold/server'
- *
- * const plan = blueprintToPlan(blueprint('budget', { src: ['core'] }))
- * const materializer = createMaterializer()
- * materializer.materialize(plan, './packages/budget-new')
- * materializer.destroy()
- * ```
- */
-export declare class Materializer implements MaterializerInterface {
-    #private;
-    constructor(options?: MaterializerOptions);
-    get emitter(): EmitterInterface<MaterializerEventMap>;
-    materialize(plan: Plan, target: string): MaterializeResult;
-    repair(plan: Plan, audit: Audit, target: string, replace?: boolean): MaterializeResult;
-    prune(target: string, expected: Readonly<Record<string, string>>): MaterializeResult;
-    destroy(): void;
-}
-
-/** The outcome of one materialization (server). */
-export declare interface MaterializeResult {
-    readonly target: string;
-    readonly written: readonly string[];
-    readonly copied: readonly string[];
-    readonly skipped: readonly string[];
-    readonly removed: readonly string[];
-}
-
-/** `Materializer`'s push observation channel (AGENTS §13, server). */
-export declare type MaterializerEventMap = {
-    readonly copy: readonly [path: string];
-    readonly write: readonly [path: string];
-    readonly remove: readonly [path: string];
-    readonly done: readonly [result: MaterializeResult];
-    readonly error: readonly [error: unknown];
-    readonly destroy: readonly [];
-};
-
-/** The materialization contract (server) — the only impure entity in the package. */
-export declare interface MaterializerInterface {
-    readonly emitter: EmitterInterface<MaterializerEventMap>;
-    materialize(plan: Plan, target: string): MaterializeResult;
-    repair(plan: Plan, audit: Audit, target: string, replace?: boolean): MaterializeResult;
-    prune(target: string, expected: Snapshot): MaterializeResult;
-    destroy(): void;
-}
-
-/**
- * Options for `createMaterializer` / the `Materializer` constructor (server).
- *
- * @remarks
- * `host` is the vendored-data root `host`-origin artifacts are copied FROM;
- * defaults to THIS PACKAGE'S OWN vendored data root (`dist/host`, resolved
- * from the installed module's own location) — the package vendors its host
- * data and ships it with itself, so the default host is never the caller's
- * working directory. A caller-supplied `host` pointing at a raw repo root
- * (no `manifest.json` alongside it) maps artifact paths 1:1 instead of
- * through the manifest — the sibling-repo / test-fixture shape.
- */
-export declare interface MaterializerOptions {
-    readonly host?: string;
-    readonly on?: EmitterHooks<MaterializerEventMap>;
-    readonly error?: EmitterErrorHandler;
-}
-
-/** The compiled, closed data-only `MaterializerOptions` contract. */
-export declare const materializerOptionsContract: ContractInterface<Readonly<{} & {
-    host?: string;
-}>>;
-
-/** Build the closed data-only `MaterializerOptions` shape. */
-export declare function materializerOptionsShape(): ObjectShape<{
-    host: OptionalShape<StringShape>;
-}, false>;
-
-/** Maximum normalized package-catalog description length. */
-export declare const MAX_CATALOG_DESCRIPTION_LENGTH = 500;
-
-/** Maximum caller-controlled filesystem path depth accepted before filesystem work. */
-export declare const MAX_FILESYSTEM_DEPTH = 64;
-
-/** Maximum UTF-8 bytes parsed from one local package guide. */
-export declare const MAX_GUIDE_BYTES = 5242880;
-
-/** Maximum directory nesting accepted by one vendored-host traversal. */
-export declare const MAX_HOST_DEPTH = 32;
-
-/** Maximum filesystem entries accepted by one vendored-host traversal. */
-export declare const MAX_HOST_ENTRIES = 4096;
-
-/** Maximum UTF-8 bytes accepted in one portable filesystem path segment. */
-export declare const MAX_PATH_SEGMENT_BYTES = 255;
-
-/** Maximum caller-supplied endpoint characters inspected before URL allocation. */
-export declare const MAX_SYNC_BASE_LENGTH = 2048;
-
-/** Maximum portable Git branch characters accepted by the guide endpoint. */
-export declare const MAX_SYNC_BRANCH_LENGTH = 255;
-
-/** Maximum configurable cumulative response bytes retained by one Sync operation. */
-export declare const MAX_SYNC_BUDGET = 104857600;
-
-/** Maximum simultaneous upstream requests accepted by `Sync`. */
-export declare const MAX_SYNC_CONCURRENCY = 64;
-
-/** Maximum configurable dependencies or catalog entries for one Sync operation. */
-export declare const MAX_SYNC_ITEMS = 1000;
-
-/** Maximum response body accepted by `Sync`, in bytes. */
-export declare const MAX_SYNC_LIMIT = 5242880;
-
-/** Maximum retry count accepted by `Sync`. */
-export declare const MAX_SYNC_RETRIES = 5;
-
-/** Maximum per-request timeout accepted by `Sync`, in milliseconds. */
-export declare const MAX_SYNC_TIMEOUT = 300000;
-
-/**
- * Remove the canonical Orkestrel scope from a dependency name.
- *
- * @param name - A dependency name.
- * @returns Its unscoped member when canonical, otherwise the original name.
- */
-export declare function packageShortName(name: string): string;
-
-/** Parse a bounded dense array of host filesystem paths without invoking caller methods. */
-export declare function parseFilesystemPaths(value: unknown, limit: number): readonly string[] | undefined;
-
-/** Parse exact materializer options before allocating its emitter. */
-export declare function parseMaterializerOptions(value: unknown): MaterializerOptions;
-
-/** Parse a bounded dense array of portable paths without invoking caller methods. */
-export declare function parsePortablePaths(value: unknown, limit: number): readonly string[] | undefined;
-
-/** Parse and normalize one upstream HTTP(S) endpoint base. */
-export declare function parseSyncBase(value: unknown): SyncBase;
-
-/** Parse a safe Git branch path for the canonical raw-guide URL. */
-export declare function parseSyncBranch(value: unknown): SyncBranch;
-
-/**
- * Snapshot only declared guide references while enforcing per-file and cumulative byte limits.
- *
- * @param value - The caller-supplied guide content map.
- * @param names - Exact dependency names eligible for selection.
- * @param budget - Maximum cumulative UTF-8 bytes.
- * @returns A frozen selected map, or `undefined` when no map was supplied.
- */
-export declare function parseSyncCurrent(value: Readonly<Record<string, string>> | undefined, names: readonly string[], budget: number): Readonly<Record<string, string>> | undefined;
-
-/** Parse and semantically validate dependency data before Sync performs network I/O. */
-export declare function parseSyncDependencies(value: unknown, external: boolean): readonly Dependency[];
-
-/**
- * Parse and semantically validate bare registry package names before Sync performs network I/O.
- *
- * @param value - Untrusted package-name collection.
- * @returns A frozen owned snapshot of valid unique npm package names.
- */
-export declare function parseSyncNames(value: unknown): readonly string[];
-
-/**
- * Parse the exact bounded `SyncOptions` boundary before allocating resources.
- *
- * @param value - Caller-supplied options.
- * @returns A fresh, validated options record.
- */
-export declare function parseSyncOptions(value: unknown): SyncOptions;
-
-/** Parse bounded exact transaction preconditions without invoking caller methods. */
-export declare function parseWritePreconditions(value: unknown, limit: number): readonly WritePrecondition[] | undefined;
-
-/**
- * The prune-owned directories. Files outside these roots are never candidates
- * for removal, including project-owned skills under `.agents/skills` and
- * `.claude/skills`.
- *
- * @example
- * ```ts
- * import { PRUNE_DIRECTORIES } from '@orkestrel/scaffold/server'
- *
- * PRUNE_DIRECTORIES // ['.claude/agents', '.codex/agents', 'scripts']
- * ```
- */
-export declare const PRUNE_DIRECTORIES: readonly string[];
-
-/**
- * List the repo-relative POSIX paths under `target`'s prune directories
- * (`.claude/agents`, `.codex/agents`, `scripts`) that the vendored `host`
- * allowlist does NOT declare — THE single source of truth for prune drift, consumed by both
- * `Materializer.prune` (which deletes exactly these paths) and the bin's
- * audit/preview UX (which now shows them honestly instead of a
- * structurally-always-zero `audit.foreign`).
- *
- * @param target - The target directory to scan for unexpected files.
- * @param host - The vendored host root the allowlist is derived from.
- * @returns The unexpected relative paths (e.g. `.claude/agents/rogue.md`); `[]`
- *   when a prune directory is absent under `target`, or when none of its
- *   files are unexpected. Pure read — never deletes anything.
- * @throws `ScaffoldError('TARGET', …)` when `host` cannot positively
- *   establish a vendored allowlist for a prune directory that DOES exist
- *   under `target` (see `vendoredPruneSet`'s fail-closed remarks).
- *
- * @example
- * ```ts
- * import { pruneTargets } from '@orkestrel/scaffold/server'
- *
- * pruneTargets('./packages/router', hostRoot()) // ['.claude/agents/rogue.md']
- * ```
- */
-export declare function pruneTargets(target: string, host: string): readonly string[];
-
-/**
- * Read one contained file as exact lowercase hexadecimal bytes.
- *
- * @param root - The declared containing root.
- * @param path - The root-relative file path.
- * @param code - The coded failure for containment or reading.
- * @param boundary - The boundary name used in diagnostics.
- * @returns The exact file bytes encoded as lowercase hexadecimal.
- */
-export declare function readFileHex(root: string, path: string, code: ScaffoldErrorCode, boundary: string, limit?: number): string;
-
-/**
- * Read one contained physical file as bounded UTF-8 text.
- *
- * @param root - The declared containing root.
- * @param path - The root-relative file path.
- * @param code - The coded failure for containment or reading.
- * @param boundary - The boundary name used in diagnostics.
- * @returns The exact file bytes decoded as UTF-8 text.
- */
-export declare function readFileText(root: string, path: string, code: ScaffoldErrorCode, boundary: string, limit?: number): string;
-
-/**
- * Read bounded physical local guide mirrors for package names.
- *
- * @param target - The package root.
- * @param names - The package names whose mirrors are eligible.
- * @returns Existing guide content keyed by package name.
- */
-export declare function readGuideReferences(target: string, names: readonly string[]): Readonly<Record<string, string>>;
-
-/**
- * Read and validate a vendored host root's `manifest.json`, when present.
- *
- * @param host - The host root to probe.
- * @returns The parsed complete manifest, or `undefined` when `host` has no
- *   `manifest.json` — the raw-repo-root fallback (`Materializer` then maps
- *   an artifact's `source` to `host` 1:1, no vendored staging indirection).
- * @throws `ScaffoldError('TARGET', …)` when `manifest.json` exists but is
- *   unreadable, malformed, membership-corrupted, collision-prone,
- *   root-incomplete, or does not map bijectively and case-exactly onto real
- *   contained storage files.
- *
- * @example
- * ```ts
- * import { readHostManifest } from '@orkestrel/scaffold/server'
- *
- * readHostManifest('./dist/host') // HostManifest | undefined
- * ```
- */
-export declare function readHostManifest(host: string): HostManifest | undefined;
-
-/**
- * Read `target/package.json` text — the read that feeds `manifestToDependencies`.
- *
- * @param target - The target directory to read the manifest from.
- * @returns The manifest file's raw text.
- * @throws `ScaffoldError('TARGET', …)` when the manifest is absent or
- *   unreadable (e.g. `EACCES` / `EPERM`) — carries the resolved `full` path
- *   in `context`.
- *
- * @example
- * ```ts
- * import { readManifest } from '@orkestrel/scaffold/server'
- *
- * readManifest('./packages/router') // '{ "name": "@orkestrel/router", … }'
- * ```
- */
-export declare function readManifest(target: string): string;
-
-/**
- * Read a target's current bytes at a set of relative paths into a
- * byte-exact hexadecimal {@link Snapshot} — the I/O that feeds `diffPlan`.
- *
- * @param target - The target directory to read from.
- * @param paths - The plan-relative artifact paths to probe.
- * @returns A snapshot keyed by path; each file maps to its exact lowercase
- *   hexadecimal bytes and a directly requested directory maps to `''`
- *   (presence only). An absent path is omitted entirely.
- * @throws `ScaffoldError('TARGET', …)` when an EXISTING path fails to read
- *   (e.g. `EACCES` / `EPERM`) — carries the offending relative `path` (and
- *   the resolved `full` path) in `context`. An absent path is never an
- *   error — it is simply omitted, per the return contract above.
- *
- * @example
- * ```ts
- * import { readTarget } from '@orkestrel/scaffold/server'
- *
- * readTarget('./packages/router', ['package.json', 'src/core/index.ts'])
- * // { 'package.json': '7b226e616d65223a…', 'src/core/index.ts': '6578706f7274…' }
- * ```
- */
-export declare function readTarget(target: string, paths: readonly string[]): Snapshot;
-
-/**
- * Map a manifest destination from an artifact's source prefix to its target prefix.
- *
- * @param artifact - The host artifact carrying the target path and optional source.
- * @param destination - The matched manifest destination.
- * @returns The exact target-relative path for the matched manifest file.
- * @throws `ScaffoldError('INVALID', …)` when `destination` is outside the source prefix.
- */
-export declare function remapArtifactPath(artifact: HostArtifact, destination: string): string;
-
-/**
- * Atomically promote a staged sibling directory while preserving recoverable state.
- *
- * @param staging - The completed staging directory.
- * @param target - The destination directory to replace.
- * @param backup - The sibling path reserved for the prior target.
- * @throws `ScaffoldError('WRITE', …)` with explicit `committed` and recovery paths.
- */
-export declare function replaceDirectory(staging: string, target: string, backup: string): void;
-
-/** Windows device names that remain reserved even when followed by an extension. */
-export declare const RESERVED_PATH_SEGMENT_PATTERN: RegExp;
-
-/** Existing repository metadata that a materialization target must never own. */
-export declare const RESERVED_TARGET_PATH_PATTERN: RegExp;
-
-/**
- * Resolve a path beneath a declared root and reject lexical or symlink escape.
- *
- * @param root - The containing filesystem root.
- * @param path - The candidate path, relative or absolute.
- * @param code - The coded error to raise on escape.
- * @param boundary - The boundary name used in diagnostics.
- * @returns The lexically resolved candidate after realpath-aware validation.
- */
-export declare function resolveContainedPath(root: string, path: string, code: ScaffoldErrorCode, boundary: string): string;
-
-/**
- * Resolve and completely preflight the canonical guide destinations a sync may write.
- *
- * @param guides - Structurally validated behind guide results.
- * @param target - The repository root that owns `guides/src`.
- * @returns Each guide paired with its contained destination.
- * @throws `ScaffoldError('WRITE', ...)` before mutation for ownership, collision,
- * containment, or existing filesystem-shape violations.
- */
-export declare function resolveGuideWrites(guides: readonly GuideSync[], target: string): readonly GuideWrite[];
-
-/**
- * Resolve a contained path whose existing ancestor chain contains no links.
- *
- * @param root - The trusted lexical and physical root.
- * @param path - The portable root-relative path.
- * @param code - The coded error to raise on failure.
- * @param boundary - The boundary name used in diagnostics.
- * @returns The contained destination.
- * @throws `ScaffoldError` when containment fails or an ancestor is not a real directory.
- */
-export declare function resolvePhysicalPath(root: string, path: string, code: ScaffoldErrorCode, boundary: string): string;
-
-/**
- * Resolve the deepest existing ancestor of a path through the real filesystem.
- *
- * @param path - The absolute or relative path to resolve.
- * @returns A path whose existing prefix has been resolved through symlinks.
- */
-export declare function resolveRealPath(path: string): string;
-
-/**
- * Restore quarantined files to their original target-relative paths.
- *
- * @param transaction - The nominal transaction that owns the quarantine and target.
- * @param paths - The relative paths to restore, in their original move order.
- * @throws `ScaffoldError('WRITE', …)` after attempting every reverse-order
- *   restoration when one or more files could not be restored.
- */
-export declare function restoreFiles(transaction: WriteTransaction, paths: readonly string[]): void;
-
-/**
- * Filter a manifest record's entries down to `@orkestrel/`-prefixed keys with
- * string values — the shared `dependencies` / `peerDependencies` /
- * `devDependencies` reader `deriveBlueprint` uses for every dependency-shaped
- * field.
- *
- * @param value - The candidate manifest field value (e.g. `parsed.dependencies`).
- * @returns The `@orkestrel/`-prefixed `[name, range]` entries; `[]` when
- *   `value` is not a plain object (per `isRecord`).
- *
- * @example
- * ```ts
- * import { selectOrkestrelEntries } from '@orkestrel/scaffold/server'
- *
- * selectOrkestrelEntries({ '@orkestrel/core': '^1.0.0', lodash: '^4.0.0' })
- * // [['@orkestrel/core', '^1.0.0']]
- * ```
- */
-export declare function selectOrkestrelEntries(value: unknown): readonly (readonly [string, string])[];
-
-/** Local configuration and credential-like paths that must never enter a vendored host. */
-export declare const SENSITIVE_HOST_PATH_PATTERN: RegExp;
-
-/**
- * Stage the vendored host set (byte-preserved copies + `manifest.json`) from
- * a repo root into an output directory — the BUILD-time primitive the
- * `build:host` npm script now calls directly (replacing a standalone build
- * script); `Materializer.materialize` is the RUNTIME reader of what this
- * writes (via `hostRoot` / `readHostManifest`).
+ * @returns The SHA-256 of that exact membership, in that exact order.
  *
- * @param root - The repo root every `paths` entry resolves against.
- * @param out - The output directory to replace after staging completes.
- * @param paths - The repo-relative file/directory entries to stage; defaults
- *   to the package's own vendored set (`HOST_PATHS`) — a caller passes an
- *   explicit list only to stage an arbitrary/test set.
  * @remarks
- * Every source, path collision, and root/output relationship is preflighted
- * before output mutation. Files are copied into a temporary sibling; the
- * completed staging tree atomically replaces `out`, with rollback when the
- * swap fails. The manifest records both sorted file `entries` and the
- * complete sorted directory `roots` inventory so destructive consumers can
- * distinguish a declared-empty root from a truncated manifest.
- * @returns The written manifest's entries (`{ storage, destination, executable }`).
- * @throws `ScaffoldError('TARGET', …)` for an invalid/escaping source or path
- *   collision, and `ScaffoldError('WRITE', …)` for staging/swap failures.
- *
- * @example
- * ```ts
- * import { stageHost } from '@orkestrel/scaffold/server'
- *
- * const entries = stageHost(process.cwd(), 'dist/host')
- * entries.length // number of files staged
- * ```
- */
-export declare function stageHost(root: string, out: string, paths?: readonly string[]): readonly ManifestEntry[];
-
-/**
- * Map a repo-relative path to its vendored-host STAGING path, per the
- * dotfile-mapping rule `stageHost` writes into `manifest.json`.
- *
- * @param path - The repo-relative source path (e.g. `.claude/agents/reviewer.md`).
- * @returns The mapped storage path: a leading-dot TOP-LEVEL FILE maps to
- *   `dotfiles/<name-without-dot>`; a leading-dot DIRECTORY segment loses its
- *   dot wherever it appears; an undotted path is unchanged.
+ * Independent of the manifest's own `digest` field, which is what lets a reader
+ * detect a membership edit that did not update it. Order is part of the claim
+ * rather than normalized away, because a staged manifest sorts its entries and
+ * roots once and a reordered copy is a different file. Each entry is projected
+ * to exactly the three declared fields, so a hand-added property cannot ride
+ * into the digest and cannot change it either.
  *
  * @example
  * ```ts
- * import { storagePath } from '@orkestrel/scaffold/server'
+ * import { computeManifestDigest } from '@orkestrel/scaffold/server'
  *
- * storagePath('.gitignore') // 'dotfiles/gitignore'
- * storagePath('.claude/agents/reviewer.md') // 'claude/agents/reviewer.md'
- * storagePath('.github/workflows/ci.yml') // 'github/workflows/ci.yml'
- * storagePath('AGENTS.md') // 'AGENTS.md'
+ * computeManifestDigest([], []) // the digest of the empty membership
  * ```
  */
-export declare function storagePath(path: string): string;
+export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[]): string;
 
 /**
- * The upstream-synchronization entity (server) — the impure FETCH sibling of
- * `Materializer`, Promise-based and network-only.
- *
- * @remarks
- * Every method reads upstream over HTTPS with a 10-second per-request
- * `AbortSignal.timeout` and bounded `concurrency` (default 6, never an
- * unbounded `Promise.all`). The default COLLECT posture captures each
- * dependency's `freshness` (`404` → `missing`, transport / other non-2xx →
- * `failed`) into the result; `strict` mode instead throws
- * `ScaffoldError('FETCH', …)` naming the failing URL. `guides`'s optional
- * `current` parameter is a caller-supplied local-mirror content map keyed by
- * dependency NAME (the `diffPlan` caller-supplied-reference pattern): WITH the
- * map, a fetched guide byte-equal to its entry verdicts `current`, anything
- * differing or absent from the map verdicts `behind`; WITHOUT the map, every
- * successful fetch verdicts `behind` (no reference means it needs syncing).
- * `pull` builds that map itself from the TARGET's declared dependency mirrors;
- * `mirror` builds it from the registry's exact organization package list,
- * excluding the target's own guide and issuing no registry version reads. Both
- * verdicts are target-relative; `write` commits only the
- * `behind` guides (never `current`, `missing`, or `failed`, which carries no
- * trustworthy content) under the same realpath-anchored containment law
- * `Materializer` enforces. After `destroy()` every method throws `DESTROYED`;
- * teardown is idempotent, emitter last.
- *
- * @example
- * ```ts
- * import { createSync } from '@orkestrel/scaffold/server'
+ * Construct a {@link Materializer}.
  *
- * const sync = createSync()
- * const report = await sync.pull('.')
- * if (report.failed === 0) await sync.write(report, '.')
- * sync.destroy()
- * ```
- */
-export declare class Sync implements SyncInterface {
-    #private;
-    constructor(options?: SyncOptions);
-    get emitter(): EmitterInterface<SyncEventMap>;
-    lookup(names: readonly string[]): Promise<readonly VersionLookup[]>;
-    guides(deps: readonly Dependency[], current?: Readonly<Record<string, string>>): Promise<readonly GuideSync[]>;
-    versions(deps: readonly Dependency[]): Promise<readonly VersionSync[]>;
-    /**
-     * The fleet package catalog, sourced from the npm registry — the
-     * AUTHORITATIVE enumeration (never a caller-supplied root).
+ * @param options - The vendored host root, the initial listeners, and the listener-error handler.
+ * @returns The materializer, typed as the contract consumers program against.
+ * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but is
+     * not an option bag the materializer accepts, and `TARGET` when the host carries
+     * a manifest that cannot be read or does not match what it stores.
      *
-     * @returns One {@link CatalogEntry} per `@orkestrel/*` package the registry
-     * lists, code-unit sorted by `name`.
-     * @remarks
-     * Three fetches build each entry: (1) the org's exact package-list
-     * (`-/org/orkestrel/package`) enumerates every published name — an
-     * unreachable or malformed response throws a coded `ScaffoldError('FETCH')`
-     * UNCONDITIONALLY (never gated by `strict`), since without it there is no
-     * catalog to build; (2) each name's own registry packument supplies
-     * `version` (`dist-tags.latest`) and a registry-path `description`
-     * fallback — a failed/malformed packument keeps the entry (degraded:
-     * `version: ''`) rather than dropping it, since the org list already
-     * proved the package exists; (3) each name's own guide
-     * (`guides/src/<short>.md`, same canonical URL as `guides()`, fetched
-     * unauthenticated — every fleet repo is public) supplies the PREFERRED
-     * `description` — its first blockquote's first paragraph — falling back
-     * to the packument description when the guide 404s, faults, or carries no
-     * blockquote; a 404 STAYS LISTED (it is a reachability signal, not an
-     * absence) with a note reading `guide unreachable (HTTP 404 — repo
-     * private or guide missing?)`. Emits `package` once per entry with a
-     * combined human-readable `note` (empty when both fetches succeeded)
-     * alongside the existing `error` events for each degraded sub-fetch.
+     * @example
+     * ```ts
+     * import { createMaterializer } from '@orkestrel/scaffold/server'
+     *
+     * const materializer = createMaterializer({ host: './dist/host' })
+     * materializer.destroy()
+     * ```
      */
-    catalog(): Promise<readonly CatalogEntry[]>;
-    pull(target: string, dependencies?: readonly Dependency[]): Promise<SyncReport>;
-    mirror(target: string): Promise<SyncReport>;
-    write(report: SyncReport, target: string): Promise<readonly string[]>;
-    destroy(): void;
-}
-
-/** Safe ASCII branch alphabet accepted before Git ref-component validation. */
-export declare const SYNC_BRANCH_PATTERN: RegExp;
-
-/** Mutable one-cell byte allowance shared by concurrent Sync readers. */
-export declare type SyncAllowance = Float64Array;
-
-/** One normalized upstream HTTP(S) endpoint base accepted by `Sync`. */
-export declare type SyncBase = string;
-
-/** One bounded Git-compatible branch path accepted by the guide endpoint. */
-export declare type SyncBranch = string;
-
-/**
- * `Sync`'s push observation channel (AGENTS §13, server).
- *
- * @remarks
- * `package` fires once per `catalog()` entry processed; its `note` is the
- * empty string when both the registry packument and the guide fetch
- * succeeded, else a human-readable explanation of which one degraded (and
- * why) — the same `''`-means-nothing convention `GuideSync.note` /
- * `VersionSync.note` use, just non-optional here since every `catalog()`
- * entry emits exactly once regardless of outcome.
- */
-export declare type SyncEventMap = {
-    readonly guide: readonly [name: string];
-    readonly version: readonly [name: string];
-    readonly package: readonly [name: string, note: string];
-    readonly write: readonly [path: string];
-    readonly done: readonly [report: SyncReport];
-    readonly error: readonly [error: unknown];
-    readonly destroy: readonly [];
-};
-
-/** Build the closed upstream-guide endpoint options shape. */
-export declare function syncGuideOptionsShape(): ObjectShape<{
-    base: OptionalShape<StringShape>;
-    branch: OptionalShape<StringShape>;
-    timeout: OptionalShape<NumberShape>;
-}, false>;
-
-/**
- * The upstream-synchronization contract (server) — the impure FETCH sibling
- * of `MaterializerInterface`.
- */
-export declare interface SyncInterface {
-    readonly emitter: EmitterInterface<SyncEventMap>;
-    lookup(names: readonly string[]): Promise<readonly VersionLookup[]>;
-    guides(deps: readonly Dependency[], current?: Readonly<Record<string, string>>): Promise<readonly GuideSync[]>;
-    versions(deps: readonly Dependency[]): Promise<readonly VersionSync[]>;
-    catalog(): Promise<readonly CatalogEntry[]>;
-    pull(target: string, dependencies?: readonly Dependency[]): Promise<SyncReport>;
-    mirror(target: string): Promise<SyncReport>;
-    write(report: SyncReport, target: string): Promise<readonly string[]>;
-    destroy(): void;
-}
-
-/**
- * Options for `createSync` / the `Sync` constructor (server).
- *
- * @remarks
- * The endpoint bases + branch are INJECTABLE — `guides.base` defaults to
- * `raw.githubusercontent.com`, `guides.branch` to `main`, `registry.base` to
- * `registry.npmjs.org`, and `guides.timeout` / `registry.timeout` to 10
- * seconds each. `concurrency` bounds in-flight requests (default 6, never an
- * unbounded `Promise.all`); `retries` opts into per-request retry on a
- * transport fault (default 0); `strict` flips a collect-mode failure into a
- * thrown `ScaffoldError('FETCH', …)` (default `false`). `limit` bounds the
- * bytes read from a single response body (declared `Content-Length` or
- * streamed total, whichever trips first) — default 5,242,880 (5 MiB); a body
- * that would exceed it is a transport fault, handled exactly like any other
- * (retry-eligible per `retries`, then `failed` / strict `FETCH`). Every fetch
- * is unauthenticated — no token, no `Authorization` header, anywhere; every
- * fleet repo is public, so plain reachability is the only signal (a guide
- * `404` degrades gracefully rather than needing credentials).
- * `registry.base` also anchors `catalog()`'s org package-list lookup
- * (`<registry.base>/-/org/orkestrel/package`) and its per-package packument
- * fetches (`<registry.base>/<name>`) — the same base every other registry
- * read already uses.
- */
-export declare interface SyncOptions {
-    readonly guides?: {
-        readonly base?: SyncBase;
-        readonly branch?: SyncBranch;
-        readonly timeout?: number;
-    };
-    readonly registry?: {
-        readonly base?: SyncBase;
-        readonly timeout?: number;
-    };
-    readonly concurrency?: number;
-    readonly retries?: number;
-    readonly strict?: boolean;
-    readonly limit?: number;
-    readonly items?: number;
-    readonly budget?: number;
-    readonly on?: EmitterHooks<SyncEventMap>;
-    readonly error?: EmitterErrorHandler;
-}
-
-/** The compiled, closed data-only `SyncOptions` contract. */
-export declare const syncOptionsContract: ContractInterface<Readonly<{} & {
-    guides?: Readonly<{} & {
-        base?: string;
-        branch?: string;
-        timeout?: number;
-    }>;
-    registry?: Readonly<{} & {
-        base?: string;
-        timeout?: number;
-    }>;
-    concurrency?: number;
-    retries?: number;
-    strict?: boolean;
-    limit?: number;
-    items?: number;
-    budget?: number;
-}>>;
-
-/** Build the closed data-only `SyncOptions` shape. */
-export declare function syncOptionsShape(): ObjectShape<{
-    guides: OptionalShape<ObjectShape<{
-        base: OptionalShape<StringShape>;
-        branch: OptionalShape<StringShape>;
-        timeout: OptionalShape<NumberShape>;
-    }, false>>;
-    registry: OptionalShape<ObjectShape<{
-        base: OptionalShape<StringShape>;
-        timeout: OptionalShape<NumberShape>;
-    }, false>>;
-    concurrency: OptionalShape<NumberShape>;
-    retries: OptionalShape<NumberShape>;
-    strict: OptionalShape<BooleanShape>;
-    limit: OptionalShape<NumberShape>;
-    items: OptionalShape<NumberShape>;
-    budget: OptionalShape<NumberShape>;
-}, false>;
-
-/** Build the closed registry endpoint options shape. */
-export declare function syncRegistryOptionsShape(): ObjectShape<{
-    base: OptionalShape<StringShape>;
-    timeout: OptionalShape<NumberShape>;
-}, false>;
-
-/**
- * Assemble one synchronization report from already ordered guide and version outcomes.
- *
- * @param target - The target package root.
- * @param guides - Guide outcomes.
- * @param versions - Version outcomes.
- * @returns The derived whole report.
- */
-export declare function syncReportOf(target: string, guides: readonly GuideSync[], versions: readonly VersionSync[]): SyncReport;
-
-/**
- * Revalidate one captured physical-directory identity without following links.
- *
- * @param anchor - The captured path, device, and inode.
- * @param boundary - The boundary name used in diagnostics.
- * @throws `ScaffoldError('WRITE', ...)` when the directory is missing or changed.
- */
-export declare function validateWriteAnchor(anchor: WriteAnchor, boundary: string): void;
-
-/**
- * Revalidate every private directory owned by a write transaction.
- *
- * @param transaction - The nominal transaction state.
- * @throws `ScaffoldError('WRITE', ...)` when any private directory changed.
- */
-export declare function validateWriteDirectories(transaction: WriteTransaction): void;
-
-/**
- * Revalidate the transaction target against its original or transaction-owned identity.
- *
- * @param transaction - The nominal transaction state.
- * @param owned - A target directory created by the current commit.
- * @throws `ScaffoldError('WRITE', ...)` when the target identity changed.
- */
-export declare function validateWriteTarget(transaction: WriteTransaction, owned: WriteAnchor | undefined): void;
-
-/**
- * The vendored set of destination-relative paths under `directory` (one of
- * `PRUNE_DIRECTORIES`) that `pruneTargets` must NOT report — read from the
- * manifest's `destination`s when `host` has one, else listed straight off
- * `host/<directory>`.
- *
- * @param host - The vendored host root to establish the allowlist from.
- * @param directory - The prune directory (one of `PRUNE_DIRECTORIES`) to scope the allowlist to.
- * @remarks
- * FAIL CLOSED: before returning any allowlist (even an empty one), the
- * vendored source must be POSITIVELY established, or a caller would treat an
- * unresolved host as "vendors nothing" and report every file under
- * `target/<directory>` as unexpected. A missing `host` root, or (no
- * `manifest.json` AND no `host/<directory>`), is a coded `TARGET` failure —
- * the distinction this guards is missing-host vs genuinely-empty-vendor: a
- * `host` that EXISTS and vendors zero files in `directory` (an existing empty
- * dir, or a manifest with zero entries for it) remains a valid empty allowlist.
- * @returns The allowed destination-relative paths under `directory`.
- * @throws `ScaffoldError('TARGET', …)` when `host` does not exist, or when
- *   `host` has no `manifest.json` and no `host/<directory>` either.
- *
- * @example
- * ```ts
- * import { vendoredPruneSet } from '@orkestrel/scaffold/server'
- *
- * vendoredPruneSet('./dist/host', '.claude/agents') // Set { '.claude/agents/reviewer.md', … }
- * ```
- */
-export declare function vendoredPruneSet(host: string, directory: string): ReadonlySet<string>;
-
-/** One bare-name registry lookup, without a caller-invented declaration range. */
-export declare type VersionLookup = {
-    readonly name: string;
-    readonly latest: string;
-    readonly freshness: 'behind';
-} | {
-    readonly name: string;
-    readonly freshness: 'missing' | 'failed';
-    readonly note: string;
-};
-
-/** Exact SHA-256 digest accepted by write preconditions. */
-export declare const WRITE_DIGEST_PATTERN: RegExp;
-
-/** A physical directory identity captured across a write transaction. */
-export declare interface WriteAnchor {
-    readonly path: string;
-    readonly device: number;
-    readonly inode: number;
-}
-
-/** Anchored result of creating a physical directory path one segment at a time. */
-export declare interface WriteDirectoryResult {
-    readonly anchor: WriteAnchor;
-    readonly created: readonly WriteAnchor[];
-}
-
-/** One destination snapshot required to remain stable through a write commit. */
-export declare interface WriteExpectation {
-    readonly path: string;
-    readonly shape: 'absent' | 'file' | 'directory';
-    readonly device?: number;
-    readonly inode?: number;
-    readonly modified?: number;
-    readonly size?: number;
-    readonly digest?: string;
-}
-
-/** Caller-observed destination state that a write transaction must still match. */
-export declare interface WritePrecondition {
-    readonly path: string;
-    readonly shape: 'absent' | 'file';
-    readonly digest?: string;
-}
-
-/**
- * Nominal, same-volume write-transaction state. Construction derives every
- * filesystem path from a target and portable relative paths; callers cannot
- * supply a deletion root or mutate captured arrays.
- */
-export declare class WriteTransaction {
-    #private;
-    constructor(token: unknown, target: string, root: string, stage: string, backup: string, expectations: readonly WriteExpectation[], parents: readonly WriteAnchor[], directories: readonly WriteAnchor[], anchor: WriteAnchor, existing: WriteAnchor | undefined);
-    /** Create private staging state and snapshot every destination before mutation. */
-    static create(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]): WriteTransaction;
-    get target(): string;
-    get root(): string;
-    get stage(): string;
-    get backup(): string;
-    get expectations(): readonly WriteExpectation[];
-    get parents(): readonly WriteAnchor[];
-    get directories(): readonly WriteAnchor[];
-    get anchor(): WriteAnchor;
-    get existing(): WriteAnchor | undefined;
-}
-
-export { }
+ export declare function createMaterializer(options?: MaterializerOptions): MaterializerInterface;
+
+ /**
+  * Construct an {@link Upstream}.
+  *
+  * @param options - The two endpoints, the request bounds, the initial listeners,
+  * and the listener-error handler.
+  * @returns The reader, typed as the contract consumers program against.
+  * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but is
+      * not an option bag the reader accepts, or when either endpoint names a scheme,
+      * host, or form the reader will not request.
+      *
+      * @example
+      * ```ts
+      * import { createUpstream } from '@orkestrel/scaffold/server'
+      *
+      * const upstream = createUpstream({ guides: { branch: 'main' } })
+      * upstream.destroy()
+      * ```
+      */
+  export declare function createUpstream(options?: UpstreamOptions): UpstreamInterface;
+
+  /**
+   * 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
+   * one algorithm rather than a variable run of bytes. Lowercase only, so two
+   * spellings of one digest can never compare unequal.
+   */
+  export declare const DIGEST_PATTERN: RegExp;
+
+  /**
+   * 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
+   * {@link INVALID_SEGMENT_CHARACTER_PATTERN}, which refuses one, so a stream name
+   * such as `file.txt:stream` cannot be smuggled through a later segment.
+   */
+  export declare const DRIVE_PATTERN: RegExp;
+
+  /**
+   * The complete vendored-host inventory.
+   *
+   * @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
+   * detected. A self-consistent replacement manifest defines its own smaller
+   * membership; authenticating omitted membership is outside a checksum's
+   * contract.
+   */
+  export declare interface HostManifest {
+      readonly entries: readonly ManifestEntry[];
+      readonly roots: readonly string[];
+      readonly digest: string;
+  }
+
+  /**
+   * Visible characters no host path segment may carry.
+   *
+   * @remarks
+   * Narrower than the core path law by exactly one character: a backslash is a
+   * separator on a Windows host rather than a forbidden character, so it is
+   * normalized to `/` before the segments are measured instead of refused here.
+   */
+  export declare const INVALID_SEGMENT_CHARACTER_PATTERN: RegExp;
+
+  /**
+   * Narrow a value to a Git branch the guide endpoint accepts.
+   *
+   * @remarks
+   * A branch reaches the guide URL's path, so the syntax is closed rather than
+   * merely bounded and no `..` is admitted anywhere in it.
+   *
+   * @example
+   * ```ts
+   * import { isBranch } from '@orkestrel/scaffold/server'
+   *
+   * isBranch('main') // true
+   * isBranch('main/../etc') // false
+   * ```
+   */
+  export declare const isBranch: Guard<string>;
+
+  /** Narrow 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. */
+  export declare const isDependencies: Guard<readonly Dependency[]>;
+
+  /**
+   * Narrow a value to a bounded list of `@orkestrel` package names.
+   *
+   * @remarks
+   * Composed from the core collection and dependency-name guards rather than
+   * restated, so the scope law that keeps a derived guide mirror inside its
+   * directory has exactly one home.
+   *
+   * @example
+   * ```ts
+   * import { isDependencyNames } from '@orkestrel/scaffold/server'
+   *
+   * isDependencyNames(['@orkestrel/router']) // true
+   * isDependencyNames(['router']) // false
+   * ```
+   */
+  export declare const isDependencyNames: Guard<readonly string[]>;
+
+  /**
+   * Narrow a value to one exact SHA-256 digest.
+   *
+   * @remarks
+   * The identity a vendored host manifest and a write precondition are both stated
+   * in. Fixed at sixty-four lowercase digits, so the value either is a digest of
+   * that algorithm or is refused; there is no shorter or longer accepted form.
+   *
+   * @example
+   * ```ts
+   * import { isDigest } from '@orkestrel/scaffold/server'
+   *
+   * isDigest('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855') // true
+   * isDigest('E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855') // false
+   * ```
+   */
+  export declare const isDigest: Guard<string>;
+
+  /**
+   * Narrow a value to a bounded upstream endpoint.
+   *
+   * @remarks
+   * Length only. Which schemes and hosts an endpoint may name is the reader's law,
+   * because it builds the request and can report why one was refused, where a
+   * guard has only `false` to say.
+   */
+  export declare const isEndpoint: Guard<string>;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * A direct file lookup follows the host's case-folding rules on Windows and
+   * common macOS filesystems. Reading each parent directory supplies the stored
+   * names, so this predicate can enforce the package's exact-case structural
+   * contract on every supported host.
+   *
+   * @example
+   * ```ts
+   * import { isExactCaseFile } from '@orkestrel/scaffold/server'
+   *
+   * isExactCaseFile('/tmp/project/src/bin/main.ts') // true only for that exact spelling
+   * ```
+   */
+  export declare function isExactCaseFile(path: string): boolean;
+
+  /**
+   * Narrow 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.
+   *
+   * @remarks
+   * The counterpart to the core path law, not a copy of it. A target directory and
+   * the vendored host root are locations on the machine rather than paths inside a
+   * workspace, so a drive prefix, a UNC share, and a backslash separator are all
+   * admitted here and `..` is a legitimate way to name a sibling directory.
+   * Containment is still enforced, but by the core law over the artifact paths
+   * written beneath the target, not by this one.
+   *
+   * What it does refuse is a segment no supported filesystem can hold: an empty
+   * one, a reserved Windows device name, a trailing dot or space, a wildcard or
+   * redirection character, a colon anywhere but the drive prefix, and a name past
+   * the byte ceiling. The character ceiling is read first so an oversized string is
+   * refused before it is split.
+   *
+   * @example
+   * ```ts
+   * import { isFilesystemPath } from '@orkestrel/scaffold/server'
+   *
+   * isFilesystemPath('C:/Users/sample/project') // true
+   * isFilesystemPath('../sibling') // true
+   * isFilesystemPath('project/nul') // false
+   * ```
+   */
+  export declare function isFilesystemPath(value: unknown): value is string;
+
+  /**
+   * Narrow a value to one {@link HostManifest}.
+   *
+   * @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.
+   */
+  export declare const isHostManifest: Guard<HostManifest>;
+
+  /**
+   * Narrow 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.
+   *
+   * @remarks
+   * Compose this ahead of an element guard exactly as the core collection guard is
+   * composed, and for the same reason: the item count is settled before anything
+   * walks the items, and a hostile `length` accessor answers `false` rather than
+   * escaping as a throw. It exists beside that guard rather than reusing it
+   * because the two bound different things — one bounds what a caller may hand a
+   * public method, this one bounds what a checkout may contain.
+   *
+   * @example
+   * ```ts
+   * import { isInventory } from '@orkestrel/scaffold/server'
+   *
+   * isInventory(['AGENTS.md']) // true
+   * isInventory('AGENTS.md') // false
+   * ```
+   */
+  export declare function isInventory(value: unknown): value is readonly unknown[];
+
+  /**
+   * Narrow a value to one {@link ManifestEntry}.
+   *
+   * @remarks
+   * Both paths are measured by the core path law, because a vendored host's
+   * storage name and the destination it maps to are each a path inside a
+   * workspace. That is what stops a hand-edited manifest from mapping a vendored
+   * file to a destination outside the target.
+   *
+   * @example
+   * ```ts
+   * import { isManifestEntry } from '@orkestrel/scaffold/server'
+   *
+   * isManifestEntry({ storage: 'AGENTS.md', destination: 'AGENTS.md', executable: false }) // true
+   * ```
+   */
+  export declare const isManifestEntry: Guard<ManifestEntry>;
+
+  /**
+   * Narrow a value to the materializer's initial listener record.
+   *
+   * @remarks
+   * Every event is optional and every declared value is a function. A key outside
+   * the materializer's event map is refused, so a listener wired to a misspelled
+   * event fails at construction instead of never firing.
+   */
+  export declare const isMaterializerHooks: Guard<EmitterHooks<MaterializerEventMap>>;
+
+  /**
+   * Narrow a value to {@link MaterializerOptions}.
+   *
+   * @example
+   * ```ts
+   * import { isMaterializerOptions } from '@orkestrel/scaffold/server'
+   *
+   * isMaterializerOptions({}) // true
+   * isMaterializerOptions({ host: 'dist/host*' }) // false
+   * ```
+   */
+  export declare const isMaterializerOptions: Guard<MaterializerOptions>;
+
+  /** Narrow a value to a bounded list of fetched guide mirrors. */
+  export declare const isMirrors: Guard<readonly Mirror[]>;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * A junction and a directory symbolic link both report as directories once
+   * followed, so the inspection deliberately does not follow: a redirected
+   * directory is refused here rather than silently accepted as the one the caller
+   * named.
+   *
+   * @example
+   * ```ts
+   * import { isPhysicalDirectory } from '@orkestrel/scaffold/server'
+   *
+   * isPhysicalDirectory('/tmp/project') // true for a plain directory
+   * ```
+   */
+  export declare function isPhysicalDirectory(path: string): boolean;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * The link tests are the point. A symbolic link is a path pointing somewhere
+   * else, so writing through one writes outside the target; a hard link means a
+   * second name shares the same bytes, so replacing them changes a file nobody
+   * asked about. Both are refused rather than followed.
+   *
+   * @example
+   * ```ts
+   * import { isPhysicalFile } from '@orkestrel/scaffold/server'
+   *
+   * isPhysicalFile('/tmp/project/AGENTS.md') // true for a plain file
+   * ```
+   */
+  export declare function isPhysicalFile(path: string): boolean;
+
+  /**
+   * Narrow a value to a {@link Repository}.
+   *
+   * @remarks
+   * Both path lists are target-relative, so both are measured by the core path
+   * law: a reported path that is not one this package could have planned is not a
+   * path it will delete. The inventory guard bounds the lists, because a checkout
+   * is legitimately far larger than any collection a caller hands a method.
+   *
+   * @example
+   * ```ts
+   * import { isRepository } from '@orkestrel/scaffold/server'
+   *
+   * isRepository({ tracked: ['AGENTS.md'], dirty: [] }) // true
+   * isRepository({ tracked: ['../secrets'], dirty: [] }) // false
+   * ```
+   */
+  export declare const isRepository: Guard<Repository>;
+
+  /**
+   * Narrow a value to a per-request timeout in milliseconds.
+   *
+   * @remarks
+   * A whole number of milliseconds, at least one and no more than
+   * {@link MAX_UPSTREAM_TIMEOUT}. Zero is refused because a request that may not
+   * take any time is a request that cannot succeed.
+   */
+  export declare const isTimeout: Guard<number>;
+
+  /**
+   * Narrow a value to the upstream reader's initial listener record.
+   *
+   * @remarks
+   * Closed to the reader's own four events for the same reason the materializer's
+   * record is closed to its five.
+   */
+  export declare const isUpstreamHooks: Guard<EmitterHooks<UpstreamEventMap>>;
+
+  /**
+   * Narrow a value to {@link UpstreamOptions}.
+   *
+   * @remarks
+   * Each grouped endpoint is closed to its own leaves, so a setting written under
+   * the wrong entity is refused rather than ignored. Every numeric leaf is a whole
+   * number inside a ceiling: an unbounded concurrency, retry count, response
+   * limit, or call budget is a way to exhaust the caller, so the ceiling is stated
+   * here rather than left to the reader. The two byte ceilings are the core
+   * artifact and total-artifact limits, because a fetched guide is an artifact and
+   * a whole call retains no more than a whole plan.
+   *
+   * @example
+   * ```ts
+   * import { isUpstreamOptions } from '@orkestrel/scaffold/server'
+   *
+   * isUpstreamOptions({ guides: { branch: 'main' }, concurrency: 4 }) // true
+   * isUpstreamOptions({ concurrency: 0 }) // false
+   * ```
+   */
+  export declare const isUpstreamOptions: Guard<UpstreamOptions>;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * The green-field law. A checkout of an empty repository is where a new
+   * workspace legitimately starts, so that one directory is admitted and nothing
+   * else is; anything more means the caller is repairing a workspace rather than
+   * creating one. Only the first two entries are read, so the answer costs the
+   * same on an empty directory and on a full one.
+   *
+   * @example
+   * ```ts
+   * import { isVacant } from '@orkestrel/scaffold/server'
+   *
+   * isVacant('./packages/router-new') // true when absent, empty, or `.git` only
+   * ```
+   */
+  export declare function isVacant(target: string): boolean;
+
+  /**
+   * List 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
+   * code-unit order, and `[]` when `root` is absent.
+   * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path.
+   * @throws `ScaffoldError('TARGET', …)` when `root` is present but is not a
+   * physical directory, cannot be read, holds a name this package could not plan,
+   * or carries more entries or more nesting than one inventory may report.
+   *
+   * @remarks
+   * The sibling of {@link listFiles}, under the same bounds and the same refusals,
+   * and it exists because a directory holding no file is invisible to a file walk.
+   * That is the half a vendored host's `roots` declares and the half a file
+   * inventory cannot check, so a stager needs both walks to state a complete
+   * membership.
+   *
+   * `root` itself is not listed, because the answer is root-relative and the root
+   * has no root-relative name. A redirected directory is not listed and is not
+   * walked into, so no traversal can leave the root and no cycle can form.
+   *
+   * @example
+   * ```ts
+   * import { listDirectories } from '@orkestrel/scaffold/server'
+   *
+   * listDirectories('./.claude') // ['agents', 'rules', 'skills', …]
+   * ```
+   */
+  export declare function listDirectories(root: string): readonly string[];
+
+  /**
+   * List 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
+   * code-unit order, and `[]` when `root` is absent.
+   * @throws `ScaffoldError('INVALID', …)` when `root` is not a host path.
+   * @throws `ScaffoldError('TARGET', …)` when `root` is present but is not a
+   * physical directory, cannot be read, holds a name this package could not plan,
+   * or carries more entries or more nesting than one inventory may report.
+   *
+   * @remarks
+   * A whole-tree answer throws where a single-path answer returns `undefined`, and
+   * the reason is that a partial inventory reads exactly like a complete one. A
+   * caller comparing a target against a plan would treat a truncated listing as
+   * proof that the missing files are not there.
+   *
+   * Absence is the one exception: nothing to inventory is a complete answer, so it
+   * is the empty list. Links are listed as files rather than followed, so no
+   * traversal can leave the root and no cycle can form.
+   *
+   * @example
+   * ```ts
+   * import { listFiles } from '@orkestrel/scaffold/server'
+   *
+   * listFiles('./dist/host') // ['AGENTS.md', 'claude/rules/names.md', …]
+   * ```
+   */
+  export declare function listFiles(root: string): readonly string[];
+
+  /**
+   * The reserved 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
+   * the manifest under it. The producer refuses a storage name equal to it and the
+   * reader looks for exactly this file, so both sides read one constant rather
+   * than repeating a literal that only agrees by inspection.
+   */
+  export declare const MANIFEST_NAME = "manifest.json";
+
+  /** One file record of the vendored host's manifest. */
+  export declare interface ManifestEntry {
+      readonly storage: string;
+      readonly destination: string;
+      readonly executable: boolean;
+  }
+
+  /**
+   * Test 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.
+   *
+   * @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.
+   *
+   * @example
+   * ```ts
+   * import { matchesAnchor, readAnchor } from '@orkestrel/scaffold/server'
+   *
+   * const anchor = readAnchor('/tmp/project')
+   * anchor !== undefined && matchesAnchor(anchor) // true while it is untouched
+   * ```
+   */
+  export declare function matchesAnchor(anchor: WriteAnchor): boolean;
+
+  /**
+   * Test whether a destination still holds what was captured of it.
+   *
+   * @param expectation - The state captured earlier.
+   * @returns `true` when re-reading the destination now produces that same state.
+   *
+   * @remarks
+   * Compared field for field against a fresh {@link readExpectation}, so an
+   * expectation recorded without a digest matches only a destination that still
+   * has no digest to give. That is what keeps the comparison honest in both
+   * directions: nothing is treated as satisfied because it was never measured.
+   *
+   * @example
+   * ```ts
+   * import { matchesExpectation, readExpectation } from '@orkestrel/scaffold/server'
+   *
+   * const expectation = readExpectation('/tmp/project/AGENTS.md')
+   * expectation !== undefined && matchesExpectation(expectation) // true while untouched
+   * ```
+   */
+  export declare function matchesExpectation(expectation: WriteExpectation): boolean;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * The one home of the `.git` membership rule, read from two directions. A target
+   * holding nothing but this directory is still vacant, because a checkout of an
+   * empty repository is where a fresh workspace legitimately starts. A path
+   * beneath it is never removed and never vendored, because deleting a target's
+   * history is not a repair.
+   *
+   * @example
+   * ```ts
+   * import { matchesGitPath } from '@orkestrel/scaffold/server'
+   *
+   * matchesGitPath('.git') // true
+   * matchesGitPath('.git/config') // true
+   * matchesGitPath('.gitignore') // false
+   * ```
+   */
+  export declare function matchesGitPath(path: string): boolean;
+
+  /**
+   * Test 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`.
+   *
+   * @remarks
+   * The one place absence is told apart from failure. Every read here answers
+   * `undefined` or an empty result for a path that is not there and reports a path
+   * that is there but unreadable, so the two must never be read from the same
+   * caught value by eye. Total for any caught value, including a hostile one.
+   *
+   * @example
+   * ```ts
+   * import { matchesMissingPath } from '@orkestrel/scaffold/server'
+   *
+   * matchesMissingPath(Object.assign(new Error('gone'), { code: 'ENOENT' })) // true
+   * matchesMissingPath(new Error('gone')) // false
+   * ```
+   */
+  export declare function matchesMissingPath(error: unknown): boolean;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * Narrower than {@link matchesExpectation} on purpose. A caller observed bytes,
+   * not inodes and timestamps, so binding a write to a device identity it never
+   * saw would refuse writes that are perfectly safe — a file rewritten to
+   * identical bytes by an editor is still the file the caller read. A precondition
+   * that states no digest claims presence only.
+   *
+   * @example
+   * ```ts
+   * import { matchesPrecondition } from '@orkestrel/scaffold/server'
+   *
+   * matchesPrecondition({ path: '/tmp/project/new.md', shape: 'absent' }) // true while absent
+   * ```
+   */
+  export declare function matchesPrecondition(precondition: WritePrecondition): boolean;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * The deletion deny-list, stated as a rule over paths rather than as a list of
+   * directories. It is the inversion the contract asks for: the candidate set
+   * comes from an audit's foreign findings narrowed by what git tracks, and this
+   * is what that set is then measured against. Repository metadata is protected
+   * because losing history is not a repair, and a target's own `src` and `app`
+   * trees are protected because a workspace's source is the one thing scaffold
+   * never plans and never owns, whatever an audit reports about it.
+   *
+   * @example
+   * ```ts
+   * import { matchesProtectedPath } from '@orkestrel/scaffold/server'
+   *
+   * matchesProtectedPath('src/core/index.ts') // true
+   * matchesProtectedPath('.git/config') // true
+   * matchesProtectedPath('.claude/agents/rogue.md') // false
+   * ```
+   */
+  export declare function matchesProtectedPath(path: string): boolean;
+
+  /**
+   * Test 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.
+   *
+   * @remarks
+   * The vendoring deny-list. A host root is staged from a real checkout, so the
+   * refusal is stated over the path rather than over the file's content: a
+   * credential is recognizable by where it sits and what it is called long before
+   * anything reads it. Repository metadata is included through
+   * {@link matchesGitPath}, so one call answers the whole question and no caller
+   * has to remember to ask twice.
+   *
+   * @example
+   * ```ts
+   * import { matchesSensitivePath } from '@orkestrel/scaffold/server'
+   *
+   * matchesSensitivePath('.npmrc') // true
+   * matchesSensitivePath('.claude/settings.local.json') // true
+   * matchesSensitivePath('.claude/settings.json') // false
+   * ```
+   */
+  export declare function matchesSensitivePath(path: string): boolean;
+
+  /**
+   * The mutation spine: read the vendored host, re-derive the target, stage, swap.
+   *
+   * @remarks
+   * Every verb runs the same three steps. It snapshots each caller-supplied value
+   * and guards the snapshot, so a property backed by an accessor never reaches a
+   * decision. It re-derives what it is about to touch and compares that against
+   * the observation the caller handed in, refusing the whole call when anything
+   * moved. Only then does it open a {@link WriteTransaction}, which stages every
+   * byte in a private sibling directory and swaps them into place.
+   *
+   * The vendored host is read once, at construction, and cross-checked once. Its
+   * manifest authenticates its own membership, which is all a checksum sitting
+   * beside the data can do; matching that membership against the files actually
+   * stored is this class's job. The comparison is exact text and therefore exact
+   * case, so a manifest naming `agents.md` for a stored `AGENTS.md` is refused on
+   * a case-insensitive filesystem rather than silently resolved.
+   *
+   * What a mutation guarantees is exactly what {@link WriteTransaction}
+   * guarantees, and no more: a caught failure part way through a commit rolls the
+   * whole commit back, no destination ever receives half-written bytes, and a
+   * process killed mid-commit leaves a mixed target. This is not a journal and
+   * does not claim to be one.
+   *
+   * Every error is emitted on `error` immediately before it is thrown, so an
+   * observer sees a refusal even where the caller catches it.
+   *
+   * @example
+   * ```ts
+   * import type { Plan } from '@orkestrel/scaffold'
+   * import { Materializer } from '@orkestrel/scaffold/server'
+   *
+   * declare const plan: Plan
+   *
+   * const materializer = new Materializer({ host: './dist/host' })
+   * materializer.materialize(plan, './packages/router')
+   * materializer.destroy()
+   * ```
+   */
+  export declare class Materializer implements MaterializerInterface {
+      #private;
+      /**
+       * Construct a materializer over one vendored host root.
+       *
+       * @param options - The vendored host root, the initial listeners, and the
+       * listener-error handler.
+       * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
+           * is not an option bag this materializer accepts, and `TARGET` when the host
+           * carries a manifest that cannot be read or does not match what it stores.
+           *
+           * @remarks
+           * `host` defaults to this package's own vendored root, resolved from this
+           * module's own location so it never depends on the caller's working
+           * directory. A host carrying no manifest is read as a raw checkout and every
+           * artifact maps onto it one to one.
+           *
+           * The host is read here rather than on first use, so a broken vendored root
+           * fails at construction where the caller can still act on it, and so nothing
+           * has to carry a second flag recording whether the read has happened yet.
+           */
+       constructor(options?: MaterializerOptions);
+       /** The materializer's observation channel. */
+       get emitter(): EmitterInterface<MaterializerEventMap>;
+       /**
+        * Compare 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.
+        * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+        * @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.
+            *
+            * @remarks
+            * Host directories expand before the target is read, so this method and
+            * {@link repair} compare the same paths with the same ownership. Foreign
+            * candidates are files beneath those expanded roots only; a root file never
+            * becomes a deletion candidate merely because its group is selected.
+            */
+        audit(plan: Plan, target: string): Audit;
+        /**
+         * Write 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.
+         * @returns The paths written and skipped.
+         * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+             * exact shape, `TARGET` when the target is not vacant or the host does not
+             * carry a planned artifact, `WRITE` when the write cannot be staged or
+             * committed, and `DESTROYED` after teardown.
+             *
+             * @remarks
+             * The plan's own bytes are not trusted: every host-origin artifact is re-read
+             * from the vendored root, so what lands is what this package ships rather than
+             * what a caller-built plan claimed it ships. A vendored directory expands into
+             * one artifact per file beneath it, and a vendored directory holding no file
+             * at all is created as an empty directory.
+             */
+         materialize(plan: Plan, target: string): MaterializeResult;
+         /**
+          * Write 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.
+          * @param target - The directory to write into.
+          * @returns The paths written and skipped, each decided by its artifact's ownership.
+          * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+              * exact shape, `TARGET` when the target moved since its audit, `WRITE` when
+              * the write cannot be staged or committed, and `DESTROYED` after teardown.
+              *
+              * @remarks
+              * 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.
+              */
+          repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
+          /**
+           * Write 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.
+           * @returns The mirror paths written and skipped; a mirror already current is skipped.
+           * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+               * exact shape, `TARGET` when a mirror moved since it was fetched, `WRITE` when
+               * 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.
+               */
+           mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
+           /**
+            * Rewrite the marker-bounded package table in the target's catalog agent file.
+            *
+            * @param entries - The published packages the table should list.
+            * @param target - The directory to write into.
+            * @returns The catalog path, written when the region's bytes moved and skipped otherwise.
+            * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+                * exact shape, `TARGET` when the file is unreadable or carries no marked
+                * region, `WRITE` when the write cannot be staged or committed, and
+                * `DESTROYED` after teardown.
+                *
+                * @remarks
+                * Only the text between the two markers is replaced, so every word a consumer
+                * wrote around the table survives the call. A row whose lookup produced no
+                * version prints the cause it carries instead, because dropping the row would
+                * hide a package the organization publishes behind one failed request.
+                */
+            catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
+            /**
+             * Rewrite the `@orkestrel/*` range set in the target's manifest.
+             *
+             * @param dependencies - The names and ranges the manifest should declare.
+             * @param target - The directory to write into.
+             * @returns The manifest path, written when a declared range moved and skipped otherwise.
+             * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+                 * exact shape or names a package the manifest does not declare, `TARGET` when
+                 * the manifest is unreadable, `WRITE` when the write cannot be staged or
+                 * committed, and `DESTROYED` after teardown.
+                 *
+                 * @remarks
+                 * No other part of the manifest is read back out or rewritten, so a consumer's
+                 * own description, keywords, scripts, and formatting survive the call. Only a
+                 * range already declared is rewritten: inserting a package would mean
+                 * re-serializing the whole manifest, which is exactly the edit this verb
+                 * promises not to make, so an undeclared name is refused by name instead.
+                 */
+             declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+             /**
+              * Delete the files the plan does not own.
+              *
+              * @param audit - The preview returned by this materializer's `audit` method; its foreign findings are the candidate set.
+              * @param repository - The target's git state; only a tracked path is ever deleted.
+              * @param target - The directory to delete from.
+              * @returns The paths removed.
+              * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
+                  * exact shape, `TARGET` when the tree carries uncommitted changes or a
+                  * candidate moved since its audit, `WRITE` when the deletion cannot be staged
+                  * or committed, and `DESTROYED` after teardown.
+                  *
+                  * @remarks
+                  * The candidate set is re-derived and compared against the audit before
+                  * anything moves, and every file is quarantined and re-verified rather than
+                  * 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, and neither is anything git does not track: git is the
+                  * recovery mechanism, so a path it cannot restore is not one this verb takes.
+                  * A tree carrying uncommitted work is refused whole for the same reason.
+                  */
+              remove(audit: Audit, repository: Repository, target: string): MaterializeResult;
+              /**
+               * Tear the materializer down. Every later call throws, and teardown is idempotent.
+               *
+               * @returns Nothing.
+               *
+               * @example
+               * ```ts
+               * import { Materializer } from '@orkestrel/scaffold/server'
+               *
+               * const materializer = new Materializer()
+               * materializer.destroy()
+               * materializer.emitter.destroyed // true
+               * ```
+               */
+              destroy(): void;
+             }
+
+             /**
+              * The outcome of one mutation of a target.
+              *
+              * @remarks
+              * `written` names every path this call created or replaced. `skipped` names
+              * every path it considered and left alone, whether because the target already
+              * matched or because the artifact's ownership forbade touching it. `removed`
+              * names every path it deleted.
+              */
+             export declare interface MaterializeResult {
+                 readonly target: string;
+                 readonly written: readonly string[];
+                 readonly skipped: readonly string[];
+                 readonly removed: readonly string[];
+             }
+
+             /** The materializer's observation channel. */
+             export declare type MaterializerEventMap = {
+                 readonly write: readonly [path: string];
+                 readonly remove: readonly [path: string];
+                 readonly finish: readonly [result: MaterializeResult];
+                 readonly error: readonly [error: unknown];
+                 readonly destroy: readonly [];
+             };
+
+             /**
+              * 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
+              * about to touch, compares that against the supplied preview, and refuses the
+              * whole call when membership or bytes moved, rather than racing to be the last
+              * writer.
+              */
+             export declare interface MaterializerInterface {
+                 readonly emitter: EmitterInterface<MaterializerEventMap>;
+                 /**
+                  * Compare 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.
+                  * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+                  */
+                 audit(plan: Plan, target: string): Audit;
+                 /**
+                  * Write 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.
+                  * @returns The paths written and skipped.
+                  */
+                 materialize(plan: Plan, target: string): MaterializeResult;
+                 /**
+                  * Write 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.
+                  * @param target - The directory to write into.
+                  * @returns The paths written and skipped, each decided by its artifact's ownership.
+                  */
+                 repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
+                 /**
+                  * Write 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.
+                  * @returns The mirror paths written and skipped; a mirror already current is skipped.
+                  */
+                 mirror(mirrors: readonly Mirror[], target: string): MaterializeResult;
+                 /**
+                  * Rewrite the marker-bounded package table in the target's catalog agent file.
+                  *
+                  * @param entries - The published packages the table should list.
+                  * @param target - The directory to write into.
+                  * @returns The catalog path, written when the region's bytes moved and skipped otherwise.
+                  */
+                 catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
+                 /**
+                  * Rewrite the `@orkestrel/*` range set in the target's manifest.
+                  *
+                  * @param dependencies - The names and ranges the manifest should declare.
+                  * @param target - The directory to write into.
+                  * @returns The manifest path, written when a declared range moved and skipped otherwise.
+                  *
+                  * @remarks
+                  * No other part of the manifest is read back out or rewritten, so a
+                  * consumer's own description, keywords, and scripts survive the call.
+                  */
+                 declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+                 /**
+                  * Delete the files the plan does not own.
+                  *
+                  * @param audit - The preview returned by this materializer's `audit` method; its foreign findings are the candidate set.
+                  * @param repository - The target's git state; only a tracked path is ever deleted.
+                  * @param target - The directory to delete from.
+                  * @returns The paths removed.
+                  *
+                  * @remarks
+                  * The candidate set is re-derived and compared against the audit before
+                  * anything moves, and every file is quarantined and re-verified rather than
+                  * 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.
+                  */
+                 remove(audit: Audit, repository: Repository, target: string): MaterializeResult;
+                 /**
+                  * Tear the materializer down. Every later call throws, and teardown is idempotent.
+                  *
+                  * @returns Nothing.
+                  */
+                 destroy(): void;
+             }
+
+             /**
+              * Options for the materializer.
+              *
+              * @remarks
+              * `host` is the vendored data root host-origin artifacts are copied from. It
+              * defaults to this package's own vendored root, resolved from the installed
+              * module's location rather than the caller's working directory. A host that
+              * carries no manifest beside it maps artifact paths one to one instead of
+              * through the manifest.
+              */
+             export declare interface MaterializerOptions {
+                 readonly host?: string;
+                 readonly on?: EmitterHooks<MaterializerEventMap>;
+                 readonly error?: EmitterErrorHandler;
+             }
+
+             /** Maximum characters one guide branch may carry. */
+             export declare const MAX_BRANCH_LENGTH = 255;
+
+             /** Maximum 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.
+              *
+              * @remarks
+              * Far above the core collection ceiling, and deliberately so. A tracked or dirty
+              * path list is the target repository's own fact rather than an argument a caller
+              * authored, so measuring it against the ceiling that bounds a public collection
+              * would read a legitimately large checkout as hostile and refuse the deletion
+              * verb on it.
+              */
+             export declare const MAX_INVENTORY_PATHS = 100000;
+
+             /**
+              * Maximum segments one host path may carry.
+              *
+              * @remarks
+              * Bounds the work a path decision costs before any filesystem call is made. With
+              * {@link MAX_PATH_SEGMENT_BYTES} it is also the real length ceiling of an
+              * accepted path, well inside the core character ceiling.
+              */
+             export declare const MAX_PATH_DEPTH = 64;
+
+             /**
+              * Maximum 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
+              * count rather than a character count, because that is the unit the filesystem
+              * imposes it in: eighty-six three-byte characters are already past it.
+              */
+             export declare const MAX_PATH_SEGMENT_BYTES = 255;
+
+             /**
+              * Maximum simultaneous upstream requests.
+              *
+              * @remarks
+              * A ceiling rather than a default: the reader picks what it opens by, and this
+              * is only what a caller may raise it to.
+              */
+             export declare const MAX_UPSTREAM_CONCURRENCY = 64;
+
+             /** Maximum 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. */
+             export declare const MAX_UPSTREAM_TIMEOUT = 300000;
+
+             /**
+              * Project 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.
+              *
+              * @remarks
+              * A staged host is a plain directory that npm packs, and npm's own ignore rules
+              * would drop a leading-dot entry from the tarball. So every dot that opens a
+              * segment comes off, and a dotted file at the root moves under `dotfiles/` to
+              * keep it from colliding with an undotted sibling of the same name. The mapping
+              * is one direction only: a staged host's manifest records the destination each
+              * storage name answers for, so the reader never re-derives this.
+              *
+              * @example
+              * ```ts
+              * import { pathToStorage } from '@orkestrel/scaffold/server'
+              *
+              * pathToStorage('.gitignore') // 'dotfiles/gitignore'
+              * pathToStorage('.claude/rules/names.md') // 'claude/rules/names.md'
+              * pathToStorage('AGENTS.md') // 'AGENTS.md'
+              * ```
+              */
+             export declare function pathToStorage(path: string): string;
+
+             /**
+              * Capture one directory's physical identity.
+              *
+              * @param path - The resolved directory path to capture.
+              * @returns The anchor, or `undefined` when the path is not a physical directory.
+              *
+              * @remarks
+              * 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.
+              *
+              * @example
+              * ```ts
+              * import { readAnchor } from '@orkestrel/scaffold/server'
+              *
+              * readAnchor('/tmp/project') // { path: '/tmp/project', device: 1, inode: 2 }
+              * ```
+              */
+             export declare function readAnchor(path: string): WriteAnchor | undefined;
+
+             /**
+              * Capture what one destination holds before a write.
+              *
+              * @param path - The resolved destination path to capture.
+              * @returns The expectation, or `undefined` when the destination is a link or a
+              * shape this package will not write over.
+              *
+              * @remarks
+              * Absence is a captured state rather than a failure, because most writes expect
+              * exactly that. Each shape carries only the facts it supplies: a directory
+              * carries its identity, a file carries its identity, size, and bytes, and an
+              * absent destination carries nothing at all. A file past the artifact ceiling
+              * carries no digest and is bound by its identity, size, and modification time
+              * alone, which is the strongest honest claim about bytes nobody read.
+              *
+              * @example
+              * ```ts
+              * import { readExpectation } from '@orkestrel/scaffold/server'
+              *
+              * readExpectation('/tmp/project/absent.md') // { path: …, shape: 'absent' }
+              * ```
+              */
+             export declare function readExpectation(path: string): WriteExpectation | undefined;
+
+             /**
+              * Read one contained file as its exact bytes in lowercase hexadecimal.
+              *
+              * @param root - The containing host directory.
+              * @param path - The portable root-relative file path.
+              * @param limit - The most bytes this read accepts; the artifact ceiling by default.
+              * @returns The exact bytes as hexadecimal, or `undefined` when the file is
+              * absent, is not a physical readable file, is past `limit`, or moved while it
+              * was being read.
+              * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
+              * `path` leaves `root`.
+              *
+              * @remarks
+              * Hexadecimal rather than text, because this is what a byte comparison is stated
+              * in everywhere in this package: a plan's artifact, an audit finding, and a
+              * snapshot all compare as the same digits. The file's identity and size are
+              * measured before and after the read, and one extra byte is requested past the
+              * declared size, so a file that grew or was replaced mid-read answers
+              * `undefined` rather than half of two files.
+              *
+              * @example
+              * ```ts
+              * import { readFileHex } from '@orkestrel/scaffold/server'
+              *
+              * readFileHex('/tmp/project', 'AGENTS.md') // '2320416765…'
+              * ```
+              */
+             export declare function readFileHex(root: string, path: string, limit?: number): string | undefined;
+
+             /**
+              * Read one contained file as bounded UTF-8 text.
+              *
+              * @param root - The containing host directory.
+              * @param path - The portable root-relative file path.
+              * @param limit - The most bytes this read accepts; the artifact ceiling by default.
+              * @returns The decoded text, or `undefined` when {@link readFileHex} answers
+              * nothing or the bytes are not valid UTF-8.
+              * @throws `ScaffoldError('INVALID', …)` when the arguments are off contract or
+              * `path` leaves `root`.
+              *
+              * @remarks
+              * Decoding is strict, so a file carrying an invalid sequence answers `undefined`
+              * rather than text carrying replacement characters. That matters because the
+              * text is parsed next: a manifest silently repaired into valid JSON by lossy
+              * decoding would be trusted.
+              *
+              * @example
+              * ```ts
+              * import { readFileText } from '@orkestrel/scaffold/server'
+              *
+              * readFileText('/tmp/project', 'package.json') // '{ "name": "@orkestrel/router", … }'
+              * ```
+              */
+             export declare function readFileText(root: string, path: string, limit?: number): string | undefined;
+
+             /**
+              * Read a vendored host's manifest, when it carries one.
+              *
+              * @param host - The vendored host root to read.
+              * @returns The manifest, or `undefined` when the host carries none.
+              * @throws `ScaffoldError('INVALID', …)` when `host` is not a host path.
+              * @throws `ScaffoldError('TARGET', …)` when the manifest is there but cannot be
+              * read, is not the declared shape, or does not match its own membership.
+              *
+              * @remarks
+              * The two failures are held apart deliberately. A host with no manifest is a
+              * raw checkout, and a caller reads it by mapping each path one to one. A host
+              * with a manifest that does not verify is a staged host that has been edited,
+              * and answering `undefined` there would degrade it to that same one-to-one
+              * mapping — which is how an edited manifest would get a caller to read files it
+              * never declared. So absence answers and corruption throws.
+              *
+              * Verification here is the manifest's own self-consistency: the digest against
+              * the exact membership beside it. Whether that membership matches the files
+              * actually stored is a separate question, and it belongs to the reader that
+              * walks the host.
+              *
+              * @example
+              * ```ts
+              * import { readHostManifest } from '@orkestrel/scaffold/server'
+              *
+              * readHostManifest('./dist/host') // the manifest, or undefined for a raw root
+              * ```
+              */
+             export declare function readHostManifest(host: string): HostManifest | undefined;
+
+             /**
+              * Derive one vendored-host manifest entry from a file in a checkout.
+              *
+              * @param destination - The target-relative path the file is written to.
+              * @param source - The resolved host path the bytes are read from.
+              * @returns The entry, or `undefined` when `source` is not a physical file this
+              * package will vendor or carries more bytes than one artifact may.
+              *
+              * @remarks
+              * The one place the 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.
+              *
+              * 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.
+              *
+              * @example
+              * ```ts
+              * import { readManifestEntry } from '@orkestrel/scaffold/server'
+              *
+              * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
+              * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false }
+              * ```
+              */
+             export declare function readManifestEntry(destination: string, source: string): ManifestEntry | undefined;
+
+             /**
+              * Read a target's current bytes at the paths a plan claims.
+              *
+              * @param target - The target directory to read.
+              * @param paths - The plan-relative paths to probe.
+              * @returns One entry per path that is there: a file maps to its exact bytes as
+              * hexadecimal and a directory maps to `''`, which records presence with no bytes
+              * to compare. An absent path is omitted.
+              * @throws `ScaffoldError('INVALID', …)` when `target` is not a host path or
+              * `paths` is not a bounded list of plannable paths.
+              * @throws `ScaffoldError('TARGET', …)` when a path that is there cannot be read,
+              * or when the whole read would retain more bytes than one plan may.
+              *
+              * @remarks
+              * The one door from a real directory into the vocabulary an audit compares in.
+              * Absence is omission rather than an empty value, because core reads a missing
+              * key as a missing destination and an empty string as a present directory; the
+              * two are different verdicts. A path that is there but unreadable throws instead
+              * of being omitted, because omission would report it as missing and a repair
+              * would then overwrite whatever is actually sitting there.
+              *
+              * @example
+              * ```ts
+              * import { readSnapshot } from '@orkestrel/scaffold/server'
+              *
+              * readSnapshot('./packages/router', ['package.json', 'guides'])
+              * // { 'package.json': '7b226e…', guides: '' }
+              * ```
+              */
+             export declare function readSnapshot(target: string, paths: readonly string[]): Snapshot;
+
+             /**
+              * What git reports about a target's working tree.
+              *
+              * @remarks
+              * `tracked` is the only set a deletion may draw from: git does not report the
+              * loss of an untracked path and `git diff` cannot restore it, so an ignored
+              * path such as an installed dependency tree, a build output, or an editor
+              * directory survives every verb. `dirty` is every path carrying an uncommitted
+              * change, taken repo-wide rather than over a write set, because deletion makes
+              * the write set the whole workspace. A clean tree is an empty `dirty`. A target
+              * that is not a git repository yields no `Repository` at all, so the caller
+              * decides what to do about that rather than reading it out of an invented
+              * empty value.
+              */
+             export declare interface Repository {
+                 readonly tracked: readonly string[];
+                 readonly dirty: readonly string[];
+             }
+
+             /**
+              * The Windows device names that stay reserved even when an extension follows.
+              *
+              * @remarks
+              * Refused on every host rather than only on Windows. A generated workspace is
+              * checked out on all of them, so a directory this package writes on Linux must
+              * still be a name Windows can hold.
+              */
+             export declare const RESERVED_SEGMENT_PATTERN: RegExp;
+
+             /**
+              * Resolve a root-relative path and refuse one that leaves its root.
+              *
+              * @param root - The containing host directory.
+              * @param path - The portable root-relative path.
+              * @returns The destination as this package will address it, or `undefined` when
+              * either argument is off contract or the destination lies outside `root`.
+              *
+              * @remarks
+              * The containment law, and the one door every read in this module goes through.
+              * Both sides are resolved through the real filesystem before they are compared,
+              * 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.
+              *
+              * 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.
+              *
+              * @example
+              * ```ts
+              * import { resolveContainedPath } from '@orkestrel/scaffold/server'
+              *
+              * resolveContainedPath('/tmp/project', 'guides/router.md') // '/tmp/project/guides/router.md'
+              * resolveContainedPath('/tmp/project', '../secrets') // undefined
+              * ```
+              */
+             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.
+              *
+              * @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.
+              *
+              * @remarks
+              * A containment decision has to be made about a destination that does not exist
+              * yet, and a lexical answer is not enough: a link anywhere in the existing
+              * prefix moves the destination somewhere the text never named. So the deepest
+              * existing ancestor is resolved and the remaining segments are re-joined onto
+              * it. The climb is bounded by the path-depth ceiling, so an adversarial path
+              * cannot make it walk indefinitely.
+              *
+              * @example
+              * ```ts
+              * import { resolveRealPath } from '@orkestrel/scaffold/server'
+              *
+              * resolveRealPath('./packages/new/src') // the real path of `packages`, plus `new/src`
+              * ```
+              */
+             export declare function resolveRealPath(path: string): string | undefined;
+
+             /**
+              * Stage 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.
+              * @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.
+              * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
+              * be written.
+              *
+              * @remarks
+              * This is the producer half of the vendored host, and it is not the mutation
+              * contract `MaterializerInterface` states. That contract owns **target**
+              * writes: it materializes a compiled plan into a consumer's workspace, binds
+              * every destination to what the caller observed, and rolls a failed commit back.
+              * This reads this package's own checkout at build time and fills its own build
+              * output. Different direction, different lifetime, no consumer target involved,
+              * so the two do not overlap and neither one belongs inside the other.
+              *
+              * Staging is plain rather than transactional for the same reason. A
+              * `WriteTransaction` exists to hold a directory that already holds work
+              * still; a build output holds nothing, is deleted whole before every build, and
+              * has no concurrent reader. What replaces it is refusing early and ordering the
+              * writes: the whole membership is derived before anything is created, so a
+              * 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
+              * reader treats as a raw checkout and fails loudly on.
+              *
+              * A missing vendored path is refused rather than staged around. A partial root
+              * is not detectably partial: it fails later, in a consumer's terminal, on
+              * whichever path the plan reached first. Refusing here fails the build that
+              * produced it, where the maintainer can act, and it names every missing path at
+              * once. A directory is the same case — declaring an absent directory as an empty
+              * root would create an empty directory in every generated workspace.
+              *
+              * The vendoring deny-list applies to what the walk discovers beneath a vendored
+              * directory, where a maintainer's local credential can legitimately sit, and
+              * such a path is skipped. A path `HOST_PATHS` names itself is curated data
+              * rather than discovery, so it is staged or the stage is refused.
+              *
+              * @example
+              * ```ts
+              * import { stageHost } from '@orkestrel/scaffold/server'
+              *
+              * stageHost(process.cwd(), 'dist/host').length // the files staged
+              * ```
+              */
+             export declare function stageHost(checkout: string, host: string): readonly ManifestEntry[];
+
+             /**
+              * The reading spine: one bounded, unauthenticated, redirect-free request per answer.
+              *
+              * @remarks
+              * This is the package's only network reader, and it never writes. Every call
+              * opens one byte allowance and spends it across every read the call makes, so a
+              * caller is bounded twice over: `limit` refuses one oversized answer and
+              * `budget` refuses many small ones. The two are separate exhaustion routes and
+              * neither bound covers the other.
+              *
+              * A per-package failure never escapes as a throw. It is projected into the
+              * verdict that package's row already carries — `missing` for an upstream `404`,
+              * which is a definite answer, and `failed` for a transport fault, which is no
+              * answer at all — so one unreachable package never costs the caller the rest of
+              * the answer. The organization package list is the one exception: without it
+              * there is no fleet to report, so an unreachable or malformed list is a coded
+              * `FETCH` failure.
+              *
+              * Requests are unauthenticated because every fleet repository is public, and
+              * they follow no redirect, so a misconfigured or hostile endpoint cannot move a
+              * read to another host. Each one is bounded by its endpoint's timeout and by the
+              * reader's own abort signal, so {@link Upstream.destroy} cancels what is in
+              * flight instead of waiting for it.
+              *
+              * The allowance is threaded through the private reads as a mutable
+              * `{ remaining: number }` carrier rather than held on the instance, because
+              * concurrent calls each own their own budget and must not spend each other's.
+              *
+              * @example
+              * ```ts
+              * import { Upstream } from '@orkestrel/scaffold/server'
+              *
+              * const upstream = new Upstream({ registry: { timeout: 5_000 } })
+              * const releases = await upstream.lookup([{ name: '@orkestrel/emitter', range: '^0.0.5' }])
+              * upstream.destroy()
+              * ```
+              */
+             export declare class Upstream implements UpstreamInterface {
+                 #private;
+                 /**
+                  * Construct a reader over one guide host and one registry.
+                  *
+                  * @param options - The two endpoints, the request bounds, the initial
+                  * listeners, and the listener-error handler.
+                  * @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
+                      * is not an option bag this reader accepts, or when either endpoint names a
+                      * scheme, host, or form this reader will not request.
+                      *
+                      * @remarks
+                      * `isEndpoint` bounds an endpoint's length and nothing else, so the scheme and
+                      * host law is settled here, where a refusal can say which endpoint was refused
+                      * and why. An endpoint must be HTTPS, or HTTP to a loopback host — the one
+                      * place an unencrypted request has no network between the two ends. That
+                      * refuses `file:`, `data:`, and plain HTTP to a real host, and it is what
+                      * keeps a fixture reachable without weakening transport security anywhere a
+                      * real request goes. An endpoint carrying credentials, a query, or a fragment
+                      * is refused too: this reader authenticates nothing and appends its own path.
+                      */
+                  constructor(options?: UpstreamOptions);
+                  /** The upstream reader's observation channel. */
+                  get emitter(): EmitterInterface<UpstreamEventMap>;
+                  /**
+                   * Look up the registry's latest release for each declared dependency.
+                   *
+                   * @param dependencies - The declared dependencies to look up.
+                   * @returns One release verdict per dependency, in input order.
+                   * @throws {@link ScaffoldError} coded `INVALID` when `dependencies` is not a
+                       * bounded list of declared dependencies, and `DESTROYED` when the reader is
+                       * torn down before or during the call.
+                       *
+                       * @remarks
+                       * Whether the declared range already admits the reported version is not
+                       * decided here and is not stored on the verdict: it is a function of the
+                       * `range` and `latest` sitting beside each other, and one centralized helper
+                       * answers it for every caller.
+                       *
+                       * @example
+                       * ```ts
+                       * import { Upstream } from '@orkestrel/scaffold/server'
+                       *
+                       * const upstream = new Upstream()
+                       * await upstream.lookup([{ name: '@orkestrel/router', range: '^0.0.8' }])
+                       * upstream.destroy()
+                       * ```
+                       */
+                   lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
+                   /**
+                    * Fetch each named package's guide, beside the local mirror it answers for.
+                    *
+                    * @param names - The packages to fetch: the target's declared set, or the whole organization.
+                    * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
+                    * @returns One mirror verdict per name, in input order.
+                    * @throws {@link ScaffoldError} coded `INVALID` when `names` is not a bounded
+                        * list of fleet package names or `current` is not a snapshot, and `DESTROYED`
+                        * when the reader is torn down before or during the call.
+                        *
+                        * @remarks
+                        * The mirror path is derived from the package name by the same helper the plan
+                        * derives it with, and the fetched URL ends in that exact path, so a verdict
+                        * always answers for the file it names. `observed` is carried through from
+                        * `current` whatever the lookup produced, because it is the precondition the
+                        * later write is held to and a failed fetch does not change what the target
+                        * currently holds.
+                        *
+                        * @example
+                        * ```ts
+                        * import { Upstream } from '@orkestrel/scaffold/server'
+                        *
+                        * const upstream = new Upstream()
+                        * await upstream.fetch(['@orkestrel/router'], { 'guides/router.md': '2320526f75746572' })
+                        * upstream.destroy()
+                        * ```
+                        */
+                    fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
+                    /**
+                     * Catalog the published fleet from the registry's organization package list.
+                     *
+                     * @returns One row per published package, sorted by name.
+                     * @throws {@link ScaffoldError} coded `FETCH` when the organization package
+                         * list is unreachable, malformed, empty, or larger than one bounded
+                         * collection, and `DESTROYED` when the reader is torn down before or during
+                         * the call.
+                         *
+                         * @remarks
+                         * The organization list is the exact membership the registry publishes, not a
+                         * relevance search, and it is the whole reason this answer can claim to be the
+                         * fleet. So it fails hard where a per-package lookup fails soft: an empty or
+                         * unreadable list would otherwise be written into a target's catalog table as
+                         * a fleet with no packages in it. A package whose own version lookup then
+                         * fails still keeps its row, carrying the cause instead of a version, because
+                         * the list already proved the package is published.
+                         *
+                         * @example
+                         * ```ts
+                         * import { Upstream } from '@orkestrel/scaffold/server'
+                         *
+                         * const upstream = new Upstream()
+                         * const entries = await upstream.catalog()
+                         * upstream.destroy()
+                         * ```
+                         */
+                     catalog(): Promise<readonly CatalogEntry[]>;
+                     /**
+                      * Tear the reader down, aborting every request in flight. Teardown is idempotent.
+                      *
+                      * @returns Nothing.
+                      *
+                      * @remarks
+                      * A call still in flight rejects with a `DESTROYED` error rather than
+                      * resolving to a partial answer, because half a fleet reads exactly like a
+                      * whole one.
+                      *
+                      * @example
+                      * ```ts
+                      * import { Upstream } from '@orkestrel/scaffold/server'
+                      *
+                      * const upstream = new Upstream()
+                      * upstream.destroy()
+                      * upstream.emitter.destroyed // true
+                      * ```
+                      */
+                     destroy(): void;
+                    }
+
+                    /**
+                     * The upstream reader's observation channel.
+                     *
+                     * @remarks
+                     * Each verdict is published whole rather than as a name beside a summary, so a
+                     * listener reads the same value the call returns and a failed lookup is told
+                     * apart from a successful one by the verdict's own discriminant rather than by
+                     * which event carried it.
+                     */
+                    export declare type UpstreamEventMap = {
+                        readonly release: readonly [release: Release];
+                        readonly mirror: readonly [mirror: Mirror];
+                        readonly error: readonly [error: unknown];
+                        readonly destroy: readonly [];
+                    };
+
+                    /**
+                     * The upstream contract: the package's only network reader, and it never writes.
+                     *
+                     * @remarks
+                     * A per-package failure is collected as a verdict carrying its cause, not
+                     * thrown, so one unreachable package never costs the caller the rest of the
+                     * answer. The organization list is the exception: without it there is no fleet
+                     * to report, so an unreachable or malformed list is a coded failure.
+                     */
+                    export declare interface UpstreamInterface {
+                        readonly emitter: EmitterInterface<UpstreamEventMap>;
+                        /**
+                         * Look up the registry's latest release for each declared dependency.
+                         *
+                         * @param dependencies - The declared dependencies to look up.
+                         * @returns One release verdict per dependency, in input order.
+                         */
+                        lookup(dependencies: readonly Dependency[]): Promise<readonly Release[]>;
+                        /**
+                         * Fetch each named package's guide, beside the local mirror it answers for.
+                         *
+                         * @param names - The packages to fetch: the target's declared set, or the whole organization.
+                         * @param current - The target's local mirrors as exact bytes, keyed by mirror path.
+                         * @returns One mirror verdict per name, in input order.
+                         */
+                        fetch(names: readonly string[], current: Snapshot): Promise<readonly Mirror[]>;
+                        /**
+                         * Catalog the published fleet from the registry's organization package list.
+                         *
+                         * @returns One row per published package, sorted by name.
+                         */
+                        catalog(): Promise<readonly CatalogEntry[]>;
+                        /**
+                         * Tear the reader down, aborting every request in flight. Teardown is idempotent.
+                         *
+                         * @returns Nothing.
+                         */
+                        destroy(): void;
+                    }
+
+                    /**
+                     * Options for the upstream reader.
+                     *
+                     * @remarks
+                     * The two endpoints are grouped under the entity each configures: `guides`
+                     * takes the guide host's `base`, its `branch`, and its `timeout`; `registry`
+                     * takes the registry's `base` and `timeout`. `concurrency` bounds requests in
+                     * flight and `retries` opts into per-request retry on a transport fault.
+                     * `limit` bounds the bytes read from one response body and `budget` bounds the
+                     * bytes read across a whole call, so neither one oversized answer nor many
+                     * small ones can exhaust the caller. Every request is unauthenticated and
+                     * follows no redirect.
+                     */
+                    export declare interface UpstreamOptions {
+                        readonly guides?: {
+                            readonly base?: string;
+                            readonly branch?: string;
+                            readonly timeout?: number;
+                        };
+                        readonly registry?: {
+                            readonly base?: string;
+                            readonly timeout?: number;
+                        };
+                        readonly concurrency?: number;
+                        readonly retries?: number;
+                        readonly limit?: number;
+                        readonly budget?: number;
+                        readonly on?: EmitterHooks<UpstreamEventMap>;
+                        readonly error?: EmitterErrorHandler;
+                    }
+
+                    /** One physical directory identity captured across a write transaction. */
+                    export declare interface WriteAnchor {
+                        readonly path: string;
+                        readonly device: number;
+                        readonly inode: number;
+                    }
+
+                    /** The final directory anchor of a write transaction and the subset one call created. */
+                    export declare interface WriteDirectoryResult {
+                        readonly anchor: WriteAnchor;
+                        readonly created: readonly WriteAnchor[];
+                    }
+
+                    /**
+                     * One destination snapshot captured before a write and required to survive it.
+                     *
+                     * @remarks
+                     * `device`, `inode`, `modified`, `size`, and `digest` are present only where
+                     * the observed shape supplies them.
+                     */
+                    export declare interface WriteExpectation {
+                        readonly path: string;
+                        readonly shape: 'absent' | 'file' | 'directory';
+                        readonly device?: number;
+                        readonly inode?: number;
+                        readonly modified?: number;
+                        readonly size?: number;
+                        readonly digest?: string;
+                    }
+
+                    /** The narrower caller-observed destination state a write transaction must still match. */
+                    export declare interface WritePrecondition {
+                        readonly path: string;
+                        readonly shape: 'absent' | 'file';
+                        readonly digest?: string;
+                    }
+
+                    /**
+                     * One staged, reversible mutation of one target directory.
+                     *
+                     * @remarks
+                     * The transaction owns a private root beside the target — a sibling directory on
+                     * the same volume, so every promotion is a rename rather than a copy. Staging
+                     * writes go into that root and nothing else, so a call that fails while staging
+                     * has not touched the target at all. Commit is the only step that mutates the
+                     * target, and it is the only step that can need rolling back.
+                     *
+                     * Two bindings hold a destination still. A **precondition** is what the caller
+                     * observed earlier and is checked once, at construction, so a target that moved
+                     * between the caller's read and this transaction fails before anything is
+                     * created. An **expectation** is captured here, at construction, and re-checked
+                     * at commit, so a target that moves while the write is being staged fails before
+                     * anything is promoted.
+                     *
+                     * What this provides, exactly:
+                     *
+                     * - **Across destinations, staged-then-swapped with rollback on a caught
+                     *   failure.** A failure part way through commit restores every destination it
+                     *   already promoted, restores every file it already took, and removes every
+                     *   directory it created, then reports what recovery could not undo. This is
+                     *   measured: a promotion is driven to fail after an earlier one landed, and the
+                     *   earlier destination is read back.
+                     * - **No partly written destination.** Every file is written whole into the
+                     *   private root and digested there before commit, so a destination never
+                     *   receives bytes that were still being produced.
+                     * - **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
+                     *   root's name is the only record a later run could read.
+                     *
+                     * A destination is preserved by hard link and then replaced by a single
+                     * `rename`, rather than moved aside and replaced, so the path continues to name
+                     * the old file right up to the swap. That is a property of `rename` on the host,
+                     * not one this package's tests measure: telling it apart from move-then-replace
+                     * needs a reader observing the destination inside the swap, and no test here
+                     * does that. Read the claim as the mechanism it describes, not as a proven
+                     * guarantee about a concurrent reader.
+                     *
+                     * A path names a file this transaction writes, takes, or establishes as a
+                     * directory; every path is target-relative and is measured by the portable-path
+                     * law. An expectation and a precondition both name the resolved destination
+                     * instead, because that is the path each is re-read at.
+                     *
+                     * @example
+                     * ```ts
+                     * import { WriteTransaction } from '@orkestrel/scaffold/server'
+                     *
+                     * const transaction = new WriteTransaction('./packages/router', ['AGENTS.md'])
+                     * try {
+                     * 	transaction.write('AGENTS.md', '# Agents\n')
+                     * 	transaction.commit() // ['AGENTS.md']
+                     * } finally {
+                     * 	transaction.discard()
+                     * }
+                     * ```
+                     */
+                    export declare class WriteTransaction {
+                        #private;
+                        /**
+                         * Open a transaction over one target directory.
+                         *
+                         * @param target - The directory every path is written beneath.
+                         * @param paths - Every target-relative path this transaction may touch.
+                         * @param preconditions - The caller-observed destination states the whole
+                         * transaction is held to, each naming a resolved destination of `paths`.
+                         * @throws {@link ScaffoldError} coded `INVALID` when an argument is off
+                             * contract, `TARGET` when a destination is a shape this package will not write
+                             * over or no longer matches its precondition, and `WRITE` when the private
+                             * root cannot be established.
+                             *
+                             * @remarks
+                             * Nothing is created until every destination has been inspected and every
+                             * precondition has held, so a refused transaction leaves no residue at all.
+                             * The private root is created last and carries a random name, so two
+                             * transactions over one target never collide.
+                             */
+                         constructor(target: string, paths: readonly string[], preconditions?: readonly WritePrecondition[]);
+                         /** The resolved directory every path is written beneath. */
+                         get target(): string;
+                         /** What each destination held when the transaction opened, in path order. */
+                         get expectations(): readonly WriteExpectation[];
+                         /** Whether the transaction can still be committed or discarded. */
+                         get open(): boolean;
+                         /**
+                          * Stage one text file.
+                          *
+                          * @param path - The target-relative path to write.
+                          * @param content - The exact UTF-8 text the destination should hold.
+                          * @returns Nothing.
+                          * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                              * transaction opened or is already staged, `TARGET` when the destination holds
+                              * a directory, and `WRITE` when the staged file cannot be written or does not
+                              * carry the bytes it was given.
+                              *
+                              * @remarks
+                              * The staged file is read back and digested against the text it was given, so
+                              * a partial or interrupted write is refused here rather than promoted later.
+                              */
+                          write(path: string, content: string): void;
+                          /**
+                           * Stage one byte-for-byte copy of a file that already exists on this host.
+                           *
+                           * @param path - The target-relative path to write.
+                           * @param source - The resolved absolute path to copy the bytes from.
+                           * @param executable - Whether the destination should carry the executable bit.
+                           * @returns Nothing.
+                           * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                               * transaction opened or is already staged, `TARGET` when the destination holds
+                               * a directory or the source is not a physical file, and `WRITE` when the copy
+                               * cannot be made or does not digest to the source's bytes.
+                               *
+                               * @remarks
+                               * The source is digested before the copy and the copy is digested after it, so
+                               * a source that changed mid-copy is refused instead of staged.
+                               */
+                           copy(path: string, source: string, executable: boolean): void;
+                           /**
+                            * Establish one directory inside the target, one segment at a time.
+                            *
+                            * @param path - The target-relative directory to establish.
+                            * @returns The directory's identity and every segment this call created.
+                            * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                * transaction opened, `TARGET` when the destination holds a file, and `WRITE`
+                                * when a segment cannot be created or changed while it was being created.
+                                *
+                                * @remarks
+                                * A directory is created immediately rather than staged, because creating one
+                                * destroys nothing: rollback removes exactly the segments this call created,
+                                * innermost first, and leaves every segment that was already there. Each
+                                * created segment is captured by device and inode, so a segment swapped
+                                * underneath the transaction is detected rather than written into.
+                                */
+                            directory(path: string): WriteDirectoryResult;
+                            /**
+                             * Mark one file for deletion at commit.
+                             *
+                             * @param path - The target-relative file to delete.
+                             * @returns Nothing.
+                             * @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
+                                 * transaction opened or is already claimed, and `TARGET` when the destination
+                                 * does not hold a file.
+                                 *
+                                 * @remarks
+                                 * Nothing moves here. Commit renames the file into the private backup rather
+                                 * than unlinking it, so a later failure in the same commit puts it back.
+                                 */
+                             remove(path: string): void;
+                             /**
+                              * Promote every staged file and take every marked file, or roll the whole call back.
+                              *
+                              * @returns Every target-relative path whose destination changed: the files
+                              * promoted, then the directories established, then the files taken.
+                              * @throws {@link ScaffoldError} coded `WRITE` when the transaction is closed,
+                                  * when a destination moved since the transaction opened, or when the commit
+                                  * failed; a failure reports what rollback could not undo in its context.
+                                  *
+                                  * @remarks
+                                  * Every destination and every directory this transaction created is re-checked
+                                  * before anything moves, so the common failure moves nothing at all. That
+                                  * check runs inside the same rollback as the promotions, because a transaction
+                                  * that refuses before it starts still has a private root and created
+                                  * directories to clear. The transaction is closed either way: a committed one
+                                  * has nothing left to undo and a failed one has already been rolled back.
+                                  */
+                              commit(): readonly string[];
+                              /**
+                               * Abandon the transaction and remove everything it created.
+                               *
+                               * @returns Nothing.
+                               * @throws {@link ScaffoldError} coded `WRITE` when residue could not be
+                                   * removed, naming the private root that still holds it.
+                                   *
+                                   * @remarks
+                                   * Idempotent, and a no-op on a transaction that already committed or already
+                                   * failed, so a caller can put it in a `finally` beside the work it guards.
+                                   */
+                               discard(): void;
+                              }
+
+                              export { }