@orkestrel/scaffold 0.0.2 → 0.0.4

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

@@ -1,15 +1,27 @@
 import { Audit } from '../core/index.ts';
 import { Blueprint } from '../core/index.ts';
+import { BooleanShape } from '@orkestrel/contract';
 import { CatalogEntry } from '../core/index.ts';
+import { ContractInterface } from '@orkestrel/contract';
 import { Dependency } from '../core/index.ts';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { GuideSync } from '../core/index.ts';
+import { HostArtifact } from '../core/index.ts';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
 import { Plan } from '../core/index.ts';
+import { ScaffoldErrorCode } from '../core/index.ts';
+import { Snapshot } from '../core/index.ts';
+import { StringShape } from '@orkestrel/contract';
 import { SyncReport } from '../core/index.ts';
 import { VersionSync } from '../core/index.ts';
 
+/** 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
@@ -42,7 +54,20 @@ import { VersionSync } from '../core/index.ts';
  * catalogPackages(['/repos']) // [{ name: '@orkestrel/contract', version: '0.0.5', description: '…' }, …]
  * ```
  */
-export declare function catalogPackages(roots: readonly string[]): readonly CatalogEntry[];
+export declare function catalogPackages(roots: readonly string[], limit?: number): readonly CatalogEntry[];
+
+/**
+ * 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,
@@ -78,6 +103,30 @@ export declare function createMaterializer(options?: MaterializerOptions): Mater
  */
 export declare function createSync(options?: SyncOptions): SyncInterface;
 
+/**
+ * Create a physical directory path one segment at a time behind captured identities.
+ *
+ * @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
@@ -85,12 +134,12 @@ export declare function createSync(options?: SyncOptions): SyncInterface;
  *
  * @param target - The existing package directory to derive a `Blueprint` from.
  * @remarks
- * `name` strips the `@orkestrel/` prefix off `manifest.name` — a non-`@orkestrel`
- * name is a coded `TARGET` failure, since this tool derives only `@orkestrel`
- * packages. `surfaces` is read off the LIVE line: every surface the package
- * carries has a `src/<surface>/` directory, so each of `'core' | 'browser' |
- * 'server'` is included iff that directory exists at `target`; a target with
- * NONE of the three is also a coded `TARGET` failure. `dependencies` /
+ * 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. `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
@@ -102,24 +151,56 @@ export declare function createSync(options?: SyncOptions): SyncInterface;
  * ALSO present in
  * `manifest.peerDependencies` or `manifest.dependencies` (e.g. a peer
  * dev-installed for local testing) is likewise excluded from `extras` — it
- * already surfaces as a `peer`/`dependency` above, and double-counting it as
+ * 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 know a caller's
  * template-override intent.
  * @returns The reconstructed `Blueprint`.
  * @throws `ScaffoldError('TARGET', …)` when `target`'s manifest is unreadable
- *   (via `readManifest`), is not valid JSON, its `name` is not `@orkestrel`-
- *   prefixed, or `target` carries none of the three surface directories.
+ *   (via `readManifest`), is not valid JSON, its name is unsafe for its
+ *   publication mode, or `target` carries no source or application environment.
  *
  * @example
  * ```ts
  * import { deriveBlueprint } from '@orkestrel/scaffold/server'
  *
- * deriveBlueprint('./packages/router') // { name: 'router', surfaces: ['core', 'server'], … }
+ * deriveBlueprint('./packages/router') // { name: 'router', src: ['core', 'server'], … }
  * ```
  */
 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;
+
+/**
+ * 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.
  *
@@ -137,7 +218,47 @@ export declare function deriveBlueprint(target: string): Blueprint;
  * discoverPackages('./packages') // ['/abs/packages/router', '/abs/packages/budget']
  * ```
  */
-export declare function discoverPackages(root: string): readonly string[];
+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[];
+}
 
 /**
  * Locate this MODULE's own installed package root — the nearest ancestor of
@@ -164,16 +285,18 @@ export declare function discoverPackages(root: string): readonly string[];
 export declare function hostRoot(): string;
 
 /**
- * Rehydrate a `Plan`'s `host`-origin artifacts with their real byte content
- * read from `host` — manifest-aware, via `locateHostSource`.
+ * 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 `content`;
- *   `template` / `computed` artifacts and directory-shaped `host` artifacts
- *   (no single storage file to read) pass through untouched.
- * @throws `ScaffoldError('TARGET', …)` when a resolved, existing host source
- *   file fails to read.
+ * @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
@@ -184,38 +307,77 @@ export declare function hostRoot(): string;
  */
 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;
+
 /**
- * Whether `value` is a well-formed `host/manifest.json` entry — a string
- * `storage`, a string `destination`, and a boolean `executable`.
+ * Narrow a value to one exact complete vendored-host manifest.
  *
- * @param value - The candidate raw manifest entry.
- * @returns `true` when `value` narrows to `ManifestEntry`.
- *
- * @example
- * ```ts
- * import { isManifestEntry } from '@orkestrel/scaffold/server'
+ * @param value - The candidate manifest value.
+ * @returns `true` only for an exact `{ entries, roots }` record with safe paths.
+ */
+export declare function isHostManifest(value: unknown): value is HostManifest;
+
+/**
+ * Narrow a value to one exact vendored-host manifest entry.
  *
- * isManifestEntry({ storage: 'a', destination: 'b', executable: false }) // true
- * isManifestEntry({ storage: 'a', destination: 'b' }) // false — missing `executable`
- * ```
+ * @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>;
+
 /**
- * Whether `value` is a plain object (not `null`, not an array).
+ * Determine whether a caught filesystem error reports an absent path.
  *
- * @param value - The candidate value.
- * @returns `true` when `value` narrows to `Record<string, unknown>`.
+ * @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.
  *
- * @example
- * ```ts
- * import { isRecord } from '@orkestrel/scaffold/server'
+ * @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.
  *
- * isRecord({ a: 1 }) // true
- * isRecord(null) // false
- * ```
+ * @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;
+
+/** 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 isRecord(value: unknown): value is Record<string, unknown>;
+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`
@@ -233,12 +395,23 @@ export declare function isRecord(value: unknown): value is Record<string, unknow
  */
 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), or `[]`
- *   when `root` is absent.
+ * @returns Root-relative file paths (posix-style `/` separators), code-unit
+ *   sorted, or `[]` when `root` is absent.
  *
  * @example
  * ```ts
@@ -253,7 +426,7 @@ 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 host's parsed `manifest.json` entries, or `undefined`
+ * @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.
@@ -269,11 +442,18 @@ export declare function listFiles(root: string): readonly string[];
  * import { locateHostSource } from '@orkestrel/scaffold/server'
  *
  * locateHostSource(undefined, 'package.json', './dist/host') // './dist/host/package.json'
- * locateHostSource([{ storage: 'pkg.tmpl', destination: 'package.json', executable: false }], 'package.json', './dist/host')
+ * locateHostSource(
+ *   {
+ *     entries: [{ storage: 'pkg.tmpl', destination: 'package.json', executable: false }],
+ *     roots: [],
+ *   },
+ *   'package.json',
+ *   './dist/host',
+ * )
  * // './dist/host/pkg.tmpl'
  * ```
  */
-export declare function locateHostSource(manifest: readonly ManifestEntry[] | undefined, source: string, host: string): string | undefined;
+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 {
@@ -283,7 +463,7 @@ export declare interface ManifestEntry {
 }
 
 /**
- * The materialization entity (server) — the only impure surface in the
+ * The materialization entity (server) — the only impure environment in the
  * package, writing a `Plan` to `node:fs` behind an explicit call.
  *
  * @remarks
@@ -293,10 +473,16 @@ export declare interface ManifestEntry {
  * `content`, failing fast on any write error (`ScaffoldError('WRITE', …)`).
  * `repair` is into-existing: it skips the vacancy check and writes ONLY the
  * `missing` / `stale` artifacts an `Audit` names, leaving `aligned` ones
- * untouched. `prune` deletes stale files under `target/.claude/agents/` and
- * `target/scripts/` that the vendored `host` no longer names — the retired
- * `mirror.sh`/`scaffold.sh` cleanup step, now a method. After `destroy()`
+ * untouched. 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
@@ -356,7 +542,7 @@ export declare interface ManifestEntry {
  * import { blueprint, blueprintToPlan } from '@orkestrel/scaffold'
  * import { createMaterializer } from '@orkestrel/scaffold/server'
  *
- * const plan = blueprintToPlan(blueprint('budget', { surfaces: ['core'] }))
+ * const plan = blueprintToPlan(blueprint('budget', { src: ['core'] }))
  * const materializer = createMaterializer()
  * materializer.materialize(plan, './packages/budget-new')
  * materializer.destroy()
@@ -368,7 +554,7 @@ export declare class Materializer implements MaterializerInterface {
     get emitter(): EmitterInterface<MaterializerEventMap>;
     materialize(plan: Plan, target: string): MaterializeResult;
     repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
-    prune(target: string): MaterializeResult;
+    prune(target: string, expected: Readonly<Record<string, string>>): MaterializeResult;
     destroy(): void;
 }
 
@@ -381,7 +567,7 @@ export declare interface MaterializeResult {
     readonly removed: readonly string[];
 }
 
-/** `Materializer`'s push observation surface (AGENTS §13, server). */
+/** `Materializer`'s push observation channel (AGENTS §13, server). */
 export declare type MaterializerEventMap = {
     readonly copy: readonly [path: string];
     readonly write: readonly [path: string];
@@ -396,7 +582,7 @@ export declare interface MaterializerInterface {
     readonly emitter: EmitterInterface<MaterializerEventMap>;
     materialize(plan: Plan, target: string): MaterializeResult;
     repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
-    prune(target: string): MaterializeResult;
+    prune(target: string, expected: Snapshot): MaterializeResult;
     destroy(): void;
 }
 
@@ -418,23 +604,123 @@ export declare interface MaterializerOptions {
     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;
+
 /**
- * The `prune`-owned directories — a hard allowlist; `pruneTargets` (and the
- * `Materializer.prune` that consumes it) never scans anything outside these two.
+ * 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 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', 'scripts']
+ * PRUNE_DIRECTORIES // ['.claude/agents', '.codex/agents', 'scripts']
  * ```
  */
-export declare const PRUNE_DIRECTORIES: readonly [".claude/agents", "scripts"];
+export declare const PRUNE_DIRECTORIES: readonly string[];
 
 /**
  * List the repo-relative POSIX paths under `target`'s prune directories
- * (`.claude/agents`, `scripts`) that the vendored `host` allowlist does NOT
- * declare — THE single source of truth for prune drift, consumed by both
+ * (`.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`).
@@ -457,24 +743,56 @@ export declare const PRUNE_DIRECTORIES: readonly [".claude/agents", "scripts"];
  */
 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 declared dependencies.
+ *
+ * @param target - The package root.
+ * @param dependencies - The declared dependencies whose mirrors are eligible.
+ * @returns Existing guide content keyed by dependency name.
+ */
+export declare function readGuideReferences(target: string, dependencies: readonly Dependency[]): 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 entries, or `undefined` when `host` has no
+ * @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, is not valid JSON, or is not an array of `ManifestEntry`.
+ *   unreadable, malformed, 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') // readonly ManifestEntry[] | undefined
+ * readHostManifest('./dist/host') // HostManifest | undefined
  * ```
  */
-export declare function readHostManifest(host: string): readonly ManifestEntry[] | undefined;
+export declare function readHostManifest(host: string): HostManifest | undefined;
 
 /**
  * Read `target/package.json` text — the read that feeds `manifestToDependencies`.
@@ -495,15 +813,14 @@ export declare function readHostManifest(host: string): readonly ManifestEntry[]
 export declare function readManifest(target: string): string;
 
 /**
- * Read a target's current content at a set of relative paths into a
- * `Record<string, string>` — the I/O that feeds the pure `diffPlan`.
+ * 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 record keyed by path; a directory entry maps to `''` (presence
- *   only — a `host`-origin directory artifact is audited by presence, never
- *   content), an absent path is OMITTED entirely (never an empty-string
- *   placeholder for a missing file, so `diffPlan` reports it `missing`).
+ * @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
@@ -514,10 +831,88 @@ export declare function readManifest(target: string): string;
  * import { readTarget } from '@orkestrel/scaffold/server'
  *
  * readTarget('./packages/router', ['package.json', 'src/core/index.ts'])
- * // { 'package.json': '{ "name": … }', 'src/core/index.ts': '…' }
+ * // { 'package.json': '7b226e616d65223a…', 'src/core/index.ts': '6578706f7274…' }
  * ```
  */
-export declare function readTarget(target: string, paths: readonly string[]): Readonly<Record<string, string>>;
+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
@@ -539,6 +934,9 @@ export declare function readTarget(target: string, paths: readonly string[]): Re
  */
 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
@@ -547,26 +945,20 @@ export declare function selectOrkestrelEntries(value: unknown): readonly (readon
  * writes (via `hostRoot` / `readHostManifest`).
  *
  * @param root - The repo root every `paths` entry resolves against.
- * @param out - The output directory to wipe and stage into (typically `dist/host`).
+ * @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
- * `out` is wiped (`rmSync(out, { recursive: true, force: true })`) BEFORE
- * staging, so a stale file left over from a prior run never lingers. Each
- * `paths` entry is walked to its per-file leaves (a directory recursively,
- * via `listFiles`; a file, itself) and copied byte-for-byte
- * (`copyFileSync`) to `<out>/<storagePath(path)>`. The `executable` flag
- * `entries` reports is derived from the `.sh` suffix on `destination` —
- * deterministic on every build platform (Windows `stat` carries no execute
- * bit); all vendored executables are shell scripts by construction.
- * `manifest.json` is written LAST, as `entries` code-unit sorted by
- * `destination`, tab-indented JSON with a trailing newline.
+ * 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', …)` naming the offending path when a
- *   `paths` entry has no source under `root`, or naming BOTH colliding
- *   destinations when two entries map to the same `storagePath` (the guard
- *   run BEFORE `manifest.json` is written).
+ * @throws `ScaffoldError('TARGET', …)` for an invalid/escaping source or path
+ *   collision, and `ScaffoldError('WRITE', …)` for staging/swap failures.
  *
  * @example
  * ```ts
@@ -582,7 +974,7 @@ export declare function stageHost(root: string, out: string, paths?: readonly st
  * 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/scout.md`).
+ * @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.
@@ -592,7 +984,7 @@ export declare function stageHost(root: string, out: string, paths?: readonly st
  * import { storagePath } from '@orkestrel/scaffold/server'
  *
  * storagePath('.gitignore') // 'dotfiles/gitignore'
- * storagePath('.claude/agents/scout.md') // 'claude/agents/scout.md'
+ * storagePath('.claude/agents/reviewer.md') // 'claude/agents/reviewer.md'
  * storagePath('.github/workflows/ci.yml') // 'github/workflows/ci.yml'
  * storagePath('AGENTS.md') // 'AGENTS.md'
  * ```
@@ -665,13 +1057,25 @@ export declare class Sync implements SyncInterface {
      * alongside the existing `error` events for each degraded sub-fetch.
      */
     catalog(): Promise<readonly CatalogEntry[]>;
-    pull(target: string): Promise<SyncReport>;
+    pull(target: string, dependencies?: readonly Dependency[]): 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 surface (AGENTS §13, server).
+ * `Sync`'s push observation channel (AGENTS §13, server).
  *
  * @remarks
  * `package` fires once per `catalog()` entry processed; its `note` is the
@@ -691,6 +1095,13 @@ export declare type SyncEventMap = {
     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`.
@@ -700,7 +1111,7 @@ export declare interface SyncInterface {
     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): Promise<SyncReport>;
+    pull(target: string, dependencies?: readonly Dependency[]): Promise<SyncReport>;
     write(report: SyncReport, target: string): Promise<readonly string[]>;
     destroy(): void;
 }
@@ -730,22 +1141,104 @@ export declare interface SyncInterface {
  */
 export declare interface SyncOptions {
     readonly guides?: {
-        readonly base?: string;
-        readonly branch?: string;
+        readonly base?: SyncBase;
+        readonly branch?: SyncBranch;
         readonly timeout?: number;
     };
     readonly registry?: {
-        readonly base?: string;
+        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
@@ -771,9 +1264,64 @@ export declare interface SyncOptions {
  * ```ts
  * import { vendoredPruneSet } from '@orkestrel/scaffold/server'
  *
- * vendoredPruneSet('./dist/host', '.claude/agents') // Set { '.claude/agents/scout.md', … }
+ * vendoredPruneSet('./dist/host', '.claude/agents') // Set { '.claude/agents/reviewer.md', … }
  * ```
  */
 export declare function vendoredPruneSet(host: string, directory: string): ReadonlySet<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 { }