@zero-transfer/sdk 0.3.1 → 0.4.2

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { SecureVersion, PeerCertificate } from 'node:tls';
 import { Readable } from 'node:stream';
 import { Buffer as Buffer$1 } from 'node:buffer';
 import { Socket } from 'node:net';
+import { KeyObject } from 'node:crypto';
 
 /**
  * Structured logging contracts and helpers for ZeroTransfer.
@@ -834,7 +835,41 @@ interface TransferEngineOptions {
     /** Clock used for receipts and progress events. Defaults to `new Date()`. */
     now?: () => Date;
 }
-/** Executes transfer jobs and produces audit-friendly receipts. */
+/**
+ * Executes transfer jobs and produces audit-friendly receipts.
+ *
+ * The engine is the lowest-level entry point in the transfer stack: it owns
+ * retry policy, attempt history, abort propagation, progress event
+ * normalization, and receipt construction. Most callers reach the engine
+ * indirectly through {@link runRoute}, {@link uploadFile}, {@link downloadFile},
+ * {@link copyBetween}, or {@link TransferQueue}; instantiate it directly when
+ * you need full control over execution semantics.
+ *
+ * @example Execute a single job with a custom executor
+ * ```ts
+ * import { TransferEngine, type TransferExecutor, type TransferJob } from "@zero-transfer/sdk";
+ *
+ * const engine = new TransferEngine();
+ *
+ * const executor: TransferExecutor = async ({ job, signal, onProgress }) => {
+ *   onProgress?.({ jobId: job.id, bytesTransferred: 0 });
+ *   // … perform the bytes here, honoring `signal` …
+ *   return { jobId: job.id, bytesTransferred: 1234, completedAt: new Date() };
+ * };
+ *
+ * const job: TransferJob = {
+ *   id: "manual-1",
+ *   operation: "upload",
+ *   source: { profile: localProfile, path: "./data.bin" },
+ *   destination: { profile: s3Profile, path: "/data/data.bin" },
+ * };
+ *
+ * const receipt = await engine.execute(job, executor, {
+ *   retry: { maxAttempts: 3, baseDelayMs: 250 },
+ * });
+ * console.log(receipt.attempts.length); // 1 on success
+ * ```
+ */
 declare class TransferEngine {
     private readonly now;
     /**
@@ -1417,9 +1452,41 @@ interface RunRouteOptions {
 /**
  * Executes an MFT route as a single transfer through the supplied client.
  *
+ * Connects the source and destination profiles, runs the route's transfer
+ * through the engine, and returns the resulting receipt. The friendly helpers
+ * {@link uploadFile}, {@link downloadFile}, and {@link copyBetween} synthesize
+ * routes and delegate to this function, so behaviour around retry, abort,
+ * progress, timeout, and bandwidth limits is identical.
+ *
  * @param options - Client, route, and optional engine/abort/retry hooks.
  * @returns Receipt produced by the underlying transfer engine.
  * @throws {@link ConfigurationError} When the route is disabled.
+ *
+ * @example Run a pre-built route with progress + retry
+ * ```ts
+ * import { createTransferClient, runRoute, type MftRoute } from "@zero-transfer/sdk";
+ *
+ * const route: MftRoute = {
+ *   id: "nightly-export",
+ *   operation: "copy",
+ *   source: {
+ *     path: "/exports/daily.csv",
+ *     profile: { host: "sftp.example.com", provider: "sftp", username: "etl" },
+ *   },
+ *   destination: {
+ *     path: "warehouse/daily.csv",
+ *     profile: { host: "warehouse", provider: "s3", s3: { region: "us-east-1" } },
+ *   },
+ * };
+ *
+ * const receipt = await runRoute({
+ *   client,
+ *   route,
+ *   onProgress: (e) => console.log(`${e.bytesTransferred}/${e.totalBytes ?? "?"}`),
+ *   retry: { maxAttempts: 3, baseDelayMs: 500 },
+ * });
+ * console.log(`Job ${receipt.jobId} moved ${receipt.bytesTransferred} bytes…`);
+ * ```
  */
 declare function runRoute(options: RunRouteOptions): Promise<TransferReceipt>;
 
@@ -1593,8 +1660,20 @@ interface ClientDiagnostics {
 /**
  * Returns a redaction-safe snapshot of the providers registered with a client.
  *
+ * Use this when rendering a setup screen, generating a support bundle, or
+ * asserting in tests that the expected provider factories were registered.
+ *
  * @param client - Transfer client to inspect.
  * @returns Provider id and capability snapshot tuples.
+ *
+ * @example List registered providers
+ * ```ts
+ * import { summarizeClientDiagnostics } from "@zero-transfer/sdk";
+ *
+ * for (const { id, capabilities } of summarizeClientDiagnostics(client).providers) {
+ *   console.log(`${id}: streaming=${capabilities.readStream} resume=${capabilities.resumeDownload}`);
+ * }
+ * ```
  */
 declare function summarizeClientDiagnostics(client: TransferClient): ClientDiagnostics;
 /** Per-step duration measurements collected by {@link runConnectionDiagnostics}. */
@@ -1647,28 +1726,116 @@ interface RunConnectionDiagnosticsOptions {
 /**
  * Connects to a profile, captures capability and listing samples, and returns a redaction-safe report.
  *
+ * Useful for connectivity "ping" pages, smoke tests, and bug reports. Secrets
+ * in the profile are redacted via {@link redactConnectionProfile} before being
+ * returned. The session is always disconnected before the function returns,
+ * including when probes throw.
+ *
  * @param options - Diagnostic probe options.
  * @returns Diagnostic report including timings and any captured error.
+ *
+ * @example Probe an SFTP connection
+ * ```ts
+ * import { runConnectionDiagnostics } from "@zero-transfer/sdk";
+ *
+ * const report = await runConnectionDiagnostics({
+ *   client,
+ *   profile: {
+ *     host: "sftp.example.com",
+ *     provider: "sftp",
+ *     username: "deploy",
+ *     ssh: { privateKey: { path: "./keys/id_ed25519" } },
+ *   },
+ *   listPath: "/uploads",
+ * });
+ *
+ * if (!report.ok) {
+ *   console.error("connection failed:", report.error);
+ * } else {
+ *   console.log(`connect=${report.timings.connectMs}ms list=${report.timings.listMs}ms`);
+ *   console.log(report.sample); // up to 5 entries from /uploads
+ * }
+ * ```
  */
 declare function runConnectionDiagnostics(options: RunConnectionDiagnosticsOptions): Promise<ConnectionDiagnosticsResult>;
 
+/** Options for {@link createPooledTransferClient}. */
+interface ConnectionPoolOptions {
+    /**
+     * Maximum number of *idle* sessions retained per pool key.
+     *
+     * Active leases are not counted against this limit — the cap only applies
+     * to sessions waiting in the pool. When more than `maxIdlePerKey` sessions
+     * become idle simultaneously, the oldest ones are disconnected. Defaults
+     * to `4`.
+     */
+    maxIdlePerKey?: number;
+    /**
+     * How long an idle session may sit unused before it is automatically
+     * disconnected. Defaults to `60_000` ms. Set to `0` to disable the timer
+     * (idle sessions persist until `drainPool()` is called).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Custom pool key derivation. Receives the resolved
+     * {@link ConnectionProfile} (after TransferClient validation) and must
+     * return a string. Sessions with matching keys are pooled together; never
+     * include secrets in the key.
+     *
+     * The default derives the key from `provider`, `host`, `port`, and
+     * `username`.
+     */
+    keyOf?: (profile: ConnectionProfile) => string;
+}
+/**
+ * Pool-aware {@link TransferClient} returned by
+ * {@link createPooledTransferClient}.
+ */
+interface PooledTransferClient {
+    /** Opens (or leases) a pooled provider session. */
+    connect(profile: ConnectionProfile): Promise<TransferSession>;
+    /** Inspects the registered providers (delegated to the underlying client). */
+    hasProvider(providerId: ProviderId): boolean;
+    /** Returns the registered capability snapshots (delegated). */
+    getCapabilities(): CapabilitySet[];
+    /** Returns a specific capability snapshot (delegated). */
+    getCapabilities(providerId: ProviderId): CapabilitySet;
+    /**
+     * Disconnects every idle session and prevents further pooling. After
+     * `drainPool()` resolves, subsequent `connect()` calls still work but
+     * always create fresh sessions (and never return them to the pool).
+     */
+    drainPool(): Promise<void>;
+    /** Returns the number of idle sessions currently held in the pool. */
+    poolSize(): number;
+}
+/**
+ * Wraps a {@link TransferClient} with connection pooling.
+ *
+ * @param inner - Underlying client used to create real provider sessions.
+ * @param options - Pool sizing, eviction, and key-derivation overrides.
+ * @returns A {@link PooledTransferClient} that reuses idle sessions.
+ */
+declare function createPooledTransferClient(inner: TransferClient, options?: ConnectionPoolOptions): PooledTransferClient;
+
 /**
  * Built-in provider capability matrix.
  *
  * Aggregates the {@link CapabilitySet} advertised by every shipped provider
  * factory so applications, docs, and diagnostics can compare features across
  * providers without instantiating each one. The S3 entry is captured twice —
- * once with multipart upload disabled (default) and once with multipart
- * upload enabled — because that flag flips `resumeUpload`.
+ * once with the new multipart-by-default configuration and once with
+ * `multipart.enabled: false` for the legacy single-shot variant — because
+ * that flag flips `resumeUpload`.
  *
  * @module providers/capabilityMatrix
  */
 
 /** Identifier for an entry in {@link getBuiltinCapabilityMatrix}. */
-type BuiltinProviderMatrixId = ProviderId | "s3:multipart";
+type BuiltinProviderMatrixId = ProviderId | "s3:single-shot";
 /** Single entry in the built-in capability matrix. */
 interface BuiltinCapabilityMatrixEntry {
-    /** Stable matrix identifier (provider id, or `s3:multipart` for the multipart variant). */
+    /** Stable matrix identifier (provider id, or `s3:single-shot` for the legacy variant). */
     id: BuiltinProviderMatrixId;
     /** Human-readable label, suitable for documentation tables. */
     label: string;
@@ -1741,7 +1908,31 @@ interface DropboxProviderOptions {
  *
  * The bearer token is resolved per-connection from `profile.password`. The
  * `profile.host` field is unused; Dropbox connections are identified solely by
- * their token.
+ * their token. Uploads go to `/2/files/upload` (single-shot); resumable upload
+ * sessions are not yet supported.
+ *
+ * @param options - Optional API base URL overrides and fetch implementation.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload a backup to Dropbox
+ * ```ts
+ * import { createDropboxProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createDropboxProviderFactory()] });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./backups/db.dump",
+ *   destination: {
+ *     path: "/Backups/2026-04-28/db.dump",
+ *     profile: {
+ *       host: "",
+ *       provider: "dropbox",
+ *       password: { env: "DROPBOX_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createDropboxProviderFactory(options?: DropboxProviderOptions): ProviderFactory;
 
@@ -1768,7 +1959,34 @@ interface GoogleDriveProviderOptions {
  * Creates a Google Drive provider factory.
  *
  * The bearer token is resolved per-connection from `profile.password`
- * (typically an OAuth 2 access token). `profile.host` is unused.
+ * (typically an OAuth 2 access token). `profile.host` is unused. Set
+ * `rootFolderId` to scope the provider to a shared-drive subtree instead
+ * of the authenticated user's My Drive root.
+ *
+ * @param options - Optional `rootFolderId`, `fetch`, and default headers.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to a shared drive folder
+ * ```ts
+ * import { createGoogleDriveProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createGoogleDriveProviderFactory({ rootFolderId: "0AB1cDeFG2HiJk" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./contracts/2026-Q2.pdf",
+ *   destination: {
+ *     path: "/Contracts/2026-Q2.pdf",
+ *     profile: {
+ *       host: "",
+ *       provider: "google-drive",
+ *       password: { env: "GOOGLE_OAUTH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createGoogleDriveProviderFactory(options?: GoogleDriveProviderOptions): ProviderFactory;
 
@@ -1791,7 +2009,40 @@ interface OneDriveProviderOptions {
  * Creates a OneDrive/SharePoint provider factory backed by Microsoft Graph.
  *
  * The bearer token is resolved per-connection from `profile.password`.
- * `profile.host` is unused.
+ * `profile.host` is unused. To target a SharePoint site or specific drive,
+ * override `driveBaseUrl` with `https://graph.microsoft.com/v1.0/drives/{driveId}`.
+ *
+ * @param options - Optional `driveBaseUrl`, `fetch`, and default headers.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to the authenticated user's OneDrive
+ * ```ts
+ * import { createOneDriveProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createOneDriveProviderFactory()],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./report.xlsx",
+ *   destination: {
+ *     path: "/Reports/Q2/report.xlsx",
+ *     profile: {
+ *       host: "",
+ *       provider: "one-drive",
+ *       password: { env: "GRAPH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Target a specific SharePoint drive
+ * ```ts
+ * createOneDriveProviderFactory({
+ *   driveBaseUrl: "https://graph.microsoft.com/v1.0/drives/b!abc123",
+ * });
+ * ```
  */
 declare function createOneDriveProviderFactory(options?: OneDriveProviderOptions): ProviderFactory;
 
@@ -1818,7 +2069,48 @@ interface AzureBlobProviderOptions {
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
 }
-/** Creates an Azure Blob Storage provider factory. */
+/**
+ * Creates an Azure Blob Storage provider factory.
+ *
+ * The container is fixed at factory construction time. Authenticate per-connection
+ * with either a SAS token (configured at factory level via {@link AzureBlobProviderOptions.sasToken})
+ * or an AAD bearer token resolved from `profile.password`. Override `endpoint` for
+ * sovereign clouds or local Azurite testing.
+ *
+ * @param options - Container plus optional endpoint, SAS token, fetch override.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example AAD-bearer upload
+ * ```ts
+ * import { createAzureBlobProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createAzureBlobProviderFactory({ container: "snapshots" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./snapshots/2026-04-28.tar.zst",
+ *   destination: {
+ *     path: "/2026/04/28/snapshot.tar.zst",
+ *     profile: {
+ *       host: "mystorageacct",
+ *       provider: "azure-blob",
+ *       password: { env: "AZURE_AAD_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example SAS-token + Azurite emulator
+ * ```ts
+ * createAzureBlobProviderFactory({
+ *   container: "devstoreaccount1",
+ *   endpoint: "http://127.0.0.1:10000/devstoreaccount1",
+ *   sasToken: "sv=2024-11-04&ss=b&srt=co&sp=rwdlac&se=...",
+ * });
+ * ```
+ */
 declare function createAzureBlobProviderFactory(options: AzureBlobProviderOptions): ProviderFactory;
 
 /** Options accepted by {@link createGcsProviderFactory}. */
@@ -1836,7 +2128,39 @@ interface GcsProviderOptions {
     /** Default headers applied before bearer auth on every request. */
     defaultHeaders?: Record<string, string>;
 }
-/** Creates a Google Cloud Storage provider factory. */
+/**
+ * Creates a Google Cloud Storage provider factory.
+ *
+ * Authentication is per-connection: pass a Google OAuth 2 access token via
+ * `profile.password`. `profile.host` is unused — the bucket is fixed at
+ * factory construction time so a single client can target multiple buckets
+ * by registering separate factories.
+ *
+ * @param options - Bucket plus optional fetch/transport overrides.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Bearer-token upload
+ * ```ts
+ * import { createGcsProviderFactory, createTransferClient, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createGcsProviderFactory({ bucket: "my-bucket" })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./build/app.tar.gz",
+ *   destination: {
+ *     path: "releases/2026.04/app.tar.gz",
+ *     profile: {
+ *       host: "my-bucket",
+ *       provider: "gcs",
+ *       password: { env: "GCP_OAUTH_ACCESS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
 declare function createGcsProviderFactory(options: GcsProviderOptions): ProviderFactory;
 
 /** Fixture entry used to seed a memory provider instance. */
@@ -1854,8 +2178,29 @@ interface MemoryProviderOptions {
 /**
  * Creates a provider factory backed by deterministic in-memory fixture entries.
  *
+ * Useful for tests and examples where you want a real `TransferSession` without
+ * touching disk or the network. Entries are pre-seeded; mutations made through
+ * the session are visible to subsequent operations on the same provider.
+ *
  * @param options - Optional fixture entries to expose through the memory provider.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Seed entries and read them back
+ * ```ts
+ * import { createMemoryProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createMemoryProviderFactory({
+ *     entries: [
+ *       { path: "/fixtures/hello.txt", content: "hello world" },
+ *       { path: "/fixtures/data.bin", content: new Uint8Array([1, 2, 3]) },
+ *     ],
+ *   })],
+ * });
+ *
+ * const session = await client.connect({ host: "fixtures", provider: "memory" });
+ * console.log(await session.fs.list("/fixtures"));
+ * ```
  */
 declare function createMemoryProviderFactory(options?: MemoryProviderOptions): ProviderFactory;
 
@@ -1875,8 +2220,45 @@ interface HttpProviderOptions {
 /**
  * Creates a provider factory backed by HTTP(S) GET/HEAD.
  *
- * @param options - Optional provider configuration.
+ * Read-only by design — use it to fetch artifacts from public URLs, signed
+ * URLs, or HTTP-only artifact servers. Range-based resume is supported when
+ * the server advertises `Accept-Ranges: bytes`. To upload to an HTTP endpoint,
+ * use the WebDAV provider, the S3 provider, or a cloud-specific provider.
+ *
+ * @param options - Optional id, base path, secure flag, fetch override.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Download a public artifact
+ * ```ts
+ * import { createHttpProviderFactory, createTransferClient, downloadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createHttpProviderFactory()] });
+ *
+ * await downloadFile({
+ *   client,
+ *   localPath: "./tmp/release.tar.gz",
+ *   source: {
+ *     path: "/releases/v1.0.0/release.tar.gz",
+ *     profile: { host: "downloads.example.com", provider: "http" },
+ *   },
+ * });
+ * ```
+ *
+ * @example Bearer-token-protected endpoint
+ * ```ts
+ * await downloadFile({
+ *   client,
+ *   localPath: "./reports/today.json",
+ *   source: {
+ *     path: "/reports/today.json",
+ *     profile: {
+ *       host: "api.example.com",
+ *       provider: "http",
+ *       password: { env: "REPORTS_TOKEN" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createHttpProviderFactory(options?: HttpProviderOptions): ProviderFactory;
 
@@ -1892,12 +2274,61 @@ interface WebDavProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied to every request. */
     defaultHeaders?: Record<string, string>;
+    /**
+     * Streaming policy for `PUT` request bodies.
+     *
+     * - `"when-known-size"` (default) — stream when the caller declares
+     *   `request.totalBytes` (an explicit `Content-Length` is sent so all
+     *   WebDAV servers accept the upload); otherwise buffer the entire body in
+     *   memory before sending. This is the safe default that does not require
+     *   the server to accept HTTP/1.1 chunked transfer-encoding.
+     * - `"always"` — always stream the body, even when the size is unknown
+     *   (the runtime will use chunked transfer-encoding). Some legacy WebDAV
+     *   servers reject `Transfer-Encoding: chunked` and will respond `411
+     *   Length Required` or `501 Not Implemented`; only enable this for
+     *   servers known to accept chunked uploads (modern Apache/nginx, IIS
+     *   with chunked transfer enabled, Nextcloud, ownCloud, sabre/dav).
+     * - `"never"` — always buffer (legacy behaviour pre-0.4.0). Use for
+     *   maximum compatibility at the cost of memory.
+     */
+    uploadStreaming?: "when-known-size" | "always" | "never";
 }
 /**
  * Creates a WebDAV provider factory.
  *
- * @param options - Optional provider configuration.
+ * Talks to any RFC 4918 server: Nextcloud, ownCloud, sabre/dav, Apache `mod_dav`,
+ * IIS WebDAV, etc. PROPFIND drives directory listings, GET supports byte-range
+ * resume on download, and PUT handles uploads. Server-side `COPY` is exposed via
+ * the capability set. Authentication is per-connection from `profile.password`.
+ *
+ * @param options - Optional id, base path, secure flag, fetch, streaming policy.
  * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Upload to Nextcloud
+ * ```ts
+ * import { createTransferClient, createWebDavProviderFactory, uploadFile } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createWebDavProviderFactory({
+ *     secure: true,
+ *     basePath: "/remote.php/dav/files/alice",
+ *   })],
+ * });
+ *
+ * await uploadFile({
+ *   client,
+ *   localPath: "./contracts/2026.pdf",
+ *   destination: {
+ *     path: "/Documents/Contracts/2026.pdf",
+ *     profile: {
+ *       host: "cloud.example.com",
+ *       provider: "webdav",
+ *       username: "alice",
+ *       password: { env: "NEXTCLOUD_APP_PASSWORD" },
+ *     },
+ *   },
+ * });
+ * ```
  */
 declare function createWebDavProviderFactory(options?: WebDavProviderOptions): ProviderFactory;
 
@@ -1926,7 +2357,14 @@ interface S3ProviderOptions {
 }
 /** Multipart upload tuning for the S3 provider. */
 interface S3MultipartOptions {
-    /** Enable multipart upload. Defaults to `false`. */
+    /**
+     * Enable multipart upload. **Defaults to `true`** so large objects stream
+     * in fixed-size parts instead of being buffered in memory before a single
+     * `PUT`. Payloads at or below {@link S3MultipartOptions.thresholdBytes}
+     * still fall back to a single-shot `PUT` automatically. Set to `false` to
+     * force the legacy single-shot behaviour (e.g. when targeting an
+     * S3-compatible endpoint that does not support `CreateMultipartUpload`).
+     */
     enabled?: boolean;
     /** Object size threshold in bytes above which multipart is used. Defaults to 8 MiB. */
     thresholdBytes?: number;
@@ -1972,6 +2410,41 @@ interface S3MultipartResumeStore {
 }
 /** Creates an in-memory {@link S3MultipartResumeStore}. */
 declare function createMemoryS3MultipartResumeStore(): S3MultipartResumeStore;
+/** Options for {@link createFileSystemS3MultipartResumeStore}. */
+interface FileSystemS3MultipartResumeStoreOptions {
+    /**
+     * Directory under which checkpoint JSON files are written. Created
+     * recursively if it does not exist. Each upload occupies a single file
+     * named after a SHA-256 hash of the resume key, so the directory is safe
+     * to share across many concurrent uploads.
+     */
+    directory: string;
+}
+/**
+ * File-system backed {@link S3MultipartResumeStore} that survives process
+ * restarts. Each in-flight multipart upload is checkpointed to a single
+ * JSON file in `options.directory` after every part. On retry the upload
+ * reuses the stored `uploadId` and skips parts that S3 has already
+ * accepted.
+ *
+ * The implementation writes atomically (`<file>.tmp` then `rename`) so a
+ * crash mid-write cannot leave a corrupt checkpoint.
+ *
+ * @example
+ * ```ts
+ * import { createFileSystemS3MultipartResumeStore, createS3ProviderFactory }
+ *   from "@zero-transfer/sdk";
+ *
+ * const resumeStore = createFileSystemS3MultipartResumeStore({
+ *   directory: "./.zt-s3-resume",
+ * });
+ *
+ * const factory = createS3ProviderFactory({
+ *   multipart: { enabled: true, resumeStore },
+ * });
+ * ```
+ */
+declare function createFileSystemS3MultipartResumeStore(options: FileSystemS3MultipartResumeStoreOptions): S3MultipartResumeStore;
 /**
  * Creates an S3-compatible provider factory.
  *
@@ -2583,286 +3056,40 @@ declare function redactValue(value: unknown): unknown;
  */
 declare function redactObject(input: Record<string, unknown>): Record<string, unknown>;
 
+/** Algorithm lists exchanged during SSH KEXINIT negotiation. */
+interface SshAlgorithmPreferences {
+    compressionClientToServer: readonly string[];
+    compressionServerToClient: readonly string[];
+    encryptionClientToServer: readonly string[];
+    encryptionServerToClient: readonly string[];
+    kexAlgorithms: readonly string[];
+    languagesClientToServer: readonly string[];
+    languagesServerToClient: readonly string[];
+    macClientToServer: readonly string[];
+    macServerToClient: readonly string[];
+    serverHostKeyAlgorithms: readonly string[];
+}
+/** Selected algorithms after intersecting client preferences with server capabilities. */
+interface NegotiatedSshAlgorithms {
+    compressionClientToServer: string;
+    compressionServerToClient: string;
+    encryptionClientToServer: string;
+    encryptionServerToClient: string;
+    kexAlgorithm: string;
+    languageClientToServer?: string;
+    languageServerToClient?: string;
+    macClientToServer: string;
+    macServerToClient: string;
+    serverHostKeyAlgorithm: string;
+}
 /**
- * FTPS control-channel TLS mode.
- *
- * `explicit` connects on a plain FTP control socket and upgrades with `AUTH TLS`;
- * `implicit` starts TLS immediately, typically on port 990.
+ * Baseline algorithm order for the initial native SSH transport implementation.
  */
-type FtpsMode = "explicit" | "implicit";
+declare const DEFAULT_SSH_ALGORITHM_PREFERENCES: Readonly<SshAlgorithmPreferences>;
 /**
- * FTPS data-channel protection level requested after TLS negotiation.
- *
- * `private` sends `PROT P` and wraps passive data sockets in TLS. `clear` sends
- * `PROT C`, keeping the control channel encrypted while leaving data sockets plain.
- */
-type FtpsDataProtection = "clear" | "private";
-/**
- * Host selection strategy for PASV data endpoints.
- *
- * `control` connects data sockets back to the control connection host, which avoids
- * broken private or unroutable PASV addresses from NATed servers. `advertised` uses
- * the host supplied by the server's PASV response for deployments that require it.
- */
-type FtpPassiveHostStrategy = "advertised" | "control";
-/** Options used to create the classic FTP provider factory. */
-interface FtpProviderOptions {
-    /** Default control port used when a connection profile omits `port`. */
-    defaultPort?: number;
-    /** PASV host selection strategy. Defaults to `control` for NAT-friendly compatibility. */
-    passiveHostStrategy?: FtpPassiveHostStrategy;
-}
-/** Options used to create the FTPS provider factory. */
-interface FtpsProviderOptions extends FtpProviderOptions {
-    /** TLS mode used for the control connection. Defaults to explicit FTPS on port 21. */
-    mode?: FtpsMode;
-    /** Data channel protection requested through PROT. Defaults to private/encrypted data. */
-    dataProtection?: FtpsDataProtection;
-}
-/**
- * Creates a provider factory for classic FTP connections.
- *
- * @param options - Optional provider defaults.
- * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
- *
- * @example Plain FTP (cleartext — prefer FTPS or SFTP whenever possible)
- * ```ts
- * import { createFtpProviderFactory, createTransferClient } from "@zero-transfer/sdk";
- *
- * const client = createTransferClient({ providers: [createFtpProviderFactory()] });
- *
- * const session = await client.connect({
- *   host: "ftp.example.com",
- *   provider: "ftp",
- *   username: "deploy",
- *   password: { env: "FTP_PASSWORD" },
- * });
- * ```
- */
-declare function createFtpProviderFactory(options?: FtpProviderOptions): ProviderFactory;
-/**
- * Creates a provider factory for explicit or implicit FTPS connections.
- *
- * The factory resolves TLS material from each connection profile, upgrades explicit
- * sessions with `AUTH TLS`, and applies the configured `PROT` data-channel policy.
- *
- * @param options - Optional provider defaults.
- * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
- *
- * @example FTPS with public-CA TLS (no extra TLS material needed)
- * ```ts
- * import { createFtpsProviderFactory, createTransferClient } from "@zero-transfer/sdk";
- *
- * const client = createTransferClient({ providers: [createFtpsProviderFactory()] });
- *
- * const session = await client.connect({
- *   host: "ftps.example.com",
- *   provider: "ftps",
- *   username: "deploy",
- *   password: { env: "FTPS_PASSWORD" },
- *   tls: { minVersion: "TLSv1.2" },
- * });
- * ```
- *
- * @example FTPS with private CA + certificate pinning (defence-in-depth)
- * ```ts
- * await client.connect({
- *   host: "ftps.internal.example",
- *   provider: "ftps",
- *   username: "audit",
- *   tls: {
- *     ca: { path: "./certs/ca-bundle.pem" },
- *     cert: { path: "./certs/client.crt" },
- *     key: { path: "./certs/client.key" },
- *     // Optional but recommended:
- *     pinnedFingerprint256: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
- *   },
- * });
- * ```
- */
-declare function createFtpsProviderFactory(options?: FtpsProviderOptions): ProviderFactory;
-
-/** FTP response status family derived from the first digit of the reply code. */
-type FtpResponseStatus = "preliminary" | "completion" | "intermediate" | "transientFailure" | "permanentFailure";
-/**
- * Complete parsed FTP response.
- */
-interface FtpResponse {
-    /** Numeric three-digit FTP reply code. */
-    code: number;
-    /** Response message with multi-line content joined by newlines. */
-    message: string;
-    /** Individual message lines without the reply-code prefix. */
-    lines: string[];
-    /** Raw response lines joined by newlines. */
-    raw: string;
-    /** Classified response status family. */
-    status: FtpResponseStatus;
-    /** Whether the response is a 1xx preliminary reply. */
-    preliminary: boolean;
-    /** Whether the response is a 2xx completion reply. */
-    completion: boolean;
-    /** Whether the response is a 3xx intermediate reply. */
-    intermediate: boolean;
-    /** Whether the response is a 4xx transient failure reply. */
-    transientFailure: boolean;
-    /** Whether the response is a 5xx permanent failure reply. */
-    permanentFailure: boolean;
-}
-/**
- * Stateful parser for socket-delivered FTP response text.
+ * Intersects client and server algorithm lists using SSH's client-priority selection model.
  */
-declare class FtpResponseParser {
-    private buffer;
-    private pendingResponse;
-    /**
-     * Adds incoming socket data and returns any complete responses.
-     *
-     * @param chunk - Buffer or string chunk from the FTP control connection.
-     * @returns Zero or more complete parsed responses.
-     * @throws {@link ParseError} When a malformed standalone response line is received.
-     */
-    push(chunk: Buffer | string): FtpResponse[];
-    /**
-     * Clears buffered text and any incomplete multi-line response state.
-     *
-     * @returns Nothing.
-     */
-    reset(): void;
-    /**
-     * Checks whether the parser is holding buffered or incomplete response data.
-     *
-     * @returns `true` when there is unconsumed text or an open multi-line response.
-     */
-    hasPendingResponse(): boolean;
-    /**
-     * Consumes one line of FTP response text.
-     *
-     * @param rawLine - Line without a trailing CRLF delimiter.
-     * @returns A complete response when the line finishes one, otherwise `undefined`.
-     * @throws {@link ParseError} When a malformed standalone line is encountered.
-     */
-    private consumeLine;
-}
-/**
- * Parses an exact set of response lines into one complete FTP response.
- *
- * @param lines - Raw response lines without trailing newline delimiters.
- * @returns A single complete parsed FTP response.
- * @throws {@link ParseError} When the lines do not contain exactly one complete response.
- */
-declare function parseFtpResponseLines(lines: string[]): FtpResponse;
-
-/**
- * FTP FEAT response parser.
- *
- * This module extracts advertised server capabilities and MLST facts from a parsed
- * FTP response, raw response string, or pre-split response lines.
- *
- * @module providers/classic/ftp/FtpFeatureParser
- */
-
-/**
- * Normalized server features returned by an FTP FEAT command.
- */
-interface FtpFeatures {
-    /** Raw normalized feature lines. */
-    raw: string[];
-    /** Uppercase feature names for fast lookup. */
-    names: Set<string>;
-    /** MLST facts advertised by the server, preserving required-fact markers. */
-    mlstFacts: string[];
-    /**
-     * Checks whether a named feature is advertised.
-     *
-     * @param featureName - Feature name to search for, case-insensitively.
-     * @returns `true` when the feature appears in the FEAT response.
-     */
-    supports(featureName: string): boolean;
-}
-/**
- * Parses FTP FEAT output into a normalized feature set.
- *
- * @param input - Parsed FTP response, raw string, or individual response lines.
- * @returns Normalized feature names, raw feature lines, and MLST fact names.
- */
-declare function parseFtpFeatures(input: FtpResponse | string | string[]): FtpFeatures;
-
-/**
- * Parses an MLSD directory listing into normalized remote entries.
- *
- * @param input - Raw MLSD response body.
- * @param directory - Parent remote directory used to build entry paths.
- * @returns Remote entries excluding the `.` and `..` pseudo entries.
- * @throws {@link ParseError} When any listing line is malformed.
- */
-declare function parseMlsdList(input: string, directory?: string): RemoteEntry[];
-/**
- * Parses a Unix-style FTP `LIST` response into normalized remote entries.
- *
- * This parser covers the common `ls -l` shape returned by classic FTP daemons and
- * is used as a compatibility fallback when a server does not support MLSD.
- *
- * @param input - Raw LIST response body.
- * @param directory - Parent remote directory used to build entry paths.
- * @param now - Reference date used when LIST entries include time but omit year.
- * @returns Remote entries excluding `.` and `..` pseudo entries.
- * @throws {@link ParseError} When any non-summary listing line is malformed.
- */
-declare function parseUnixList(input: string, directory?: string, now?: Date): RemoteEntry[];
-/**
- * Parses one Unix-style FTP `LIST` line.
- *
- * @param line - Raw listing line in an `ls -l` compatible format.
- * @param directory - Parent remote directory used to build the entry path.
- * @param now - Reference date used when the line omits a year.
- * @returns Normalized remote entry with raw LIST metadata retained.
- * @throws {@link ParseError} When the line is not a supported Unix LIST entry.
- */
-declare function parseUnixListLine(line: string, directory?: string, now?: Date): RemoteEntry;
-/**
- * Parses a single MLSD or MLST fact line.
- *
- * @param line - Raw fact line in `fact=value; name` format.
- * @param directory - Parent remote directory used to build the entry path.
- * @returns A normalized remote entry with parsed facts in `raw` metadata.
- * @throws {@link ParseError} When the line does not contain facts and a name.
- */
-declare function parseMlsdLine(line: string, directory?: string): RemoteEntry;
-/**
- * Parses the UTC timestamp format used by MLST/MLSD `modify` facts.
- *
- * @param input - Timestamp text such as `20260427010203.123`.
- * @returns A UTC Date when the timestamp is valid, otherwise `undefined`.
- */
-declare function parseMlstTimestamp(input: string | undefined): Date | undefined;
-
-/** Algorithm lists exchanged during SSH KEXINIT negotiation. */
-interface SshAlgorithmPreferences {
-    compressionClientToServer: readonly string[];
-    compressionServerToClient: readonly string[];
-    encryptionClientToServer: readonly string[];
-    encryptionServerToClient: readonly string[];
-    kexAlgorithms: readonly string[];
-    languagesClientToServer: readonly string[];
-    languagesServerToClient: readonly string[];
-    macClientToServer: readonly string[];
-    macServerToClient: readonly string[];
-    serverHostKeyAlgorithms: readonly string[];
-}
-/** Selected algorithms after intersecting client preferences with server capabilities. */
-interface NegotiatedSshAlgorithms {
-    compressionClientToServer: string;
-    compressionServerToClient: string;
-    encryptionClientToServer: string;
-    encryptionServerToClient: string;
-    kexAlgorithm: string;
-    languageClientToServer?: string;
-    languageServerToClient?: string;
-    macClientToServer: string;
-    macServerToClient: string;
-    serverHostKeyAlgorithm: string;
-}
+declare function negotiateSshAlgorithms(client: SshAlgorithmPreferences, server: SshAlgorithmPreferences): NegotiatedSshAlgorithms;
 
 /** Parsed SSH identification components from the RFC 4253 banner line. */
 interface SshIdentification {
@@ -2927,6 +3154,62 @@ interface SshTransportHandshakeResult {
      */
     inboundPacketCount: number;
 }
+/**
+ * Client-side SSH handshake coordinator for version exchange and KEXINIT negotiation.
+ */
+declare class SshTransportHandshake {
+    private readonly options;
+    private readonly clientAlgorithms;
+    private readonly clientIdentificationLine;
+    private readonly clientKexInitPayload;
+    private readonly identificationLines;
+    private readonly packetFramer;
+    private readonly pendingIdentification;
+    private phase;
+    private inboundPacketCount;
+    private outboundPacketCount;
+    private pendingCurve25519;
+    private pendingKeyExchange;
+    private serverIdentification;
+    constructor(options?: {
+        algorithms?: SshAlgorithmPreferences;
+        clientComments?: string;
+        clientSoftwareVersion?: string;
+        kexCookie?: Uint8Array;
+        /**
+         * Verifies the server's host key after the signature check passes.
+         * Receives the SSH wire-format host key blob and its SHA-256 digest.
+         * Throwing rejects the handshake; resolving accepts it.
+         *
+         * If omitted, the host key is accepted as long as its signature over the
+         * exchange hash verifies. Callers SHOULD supply this hook in production
+         * to enforce known_hosts or pinned-fingerprint policies.
+         */
+        verifyHostKey?: (input: {
+            hostKeyBlob: Buffer$1;
+            hostKeySha256: Buffer$1;
+            algorithmName: string;
+        }) => void | Promise<void>;
+    });
+    /** Creates the first outbound bytes (client identification line). */
+    createInitialClientBytes(): Buffer$1;
+    /**
+     * Feeds raw server bytes into the handshake state machine.
+     */
+    pushServerBytes(chunk: Uint8Array): {
+        outbound: Buffer$1[];
+        result?: SshTransportHandshakeResult;
+    };
+    getServerBannerLines(): readonly string[];
+    isComplete(): boolean;
+    /**
+     * Returns any bytes received after the last complete handshake packet and clears the buffer.
+     * Call this once after `pushServerBytes` returns a result to drain bytes that belong to the
+     * post-NEWKEYS encrypted phase but arrived in the same TCP segment as NEWKEYS.
+     */
+    takeRemainingBytes(): Buffer$1;
+    private pushServerBytesWithPhase;
+}
 
 /** Standard SSH disconnect reason codes (RFC 4253 §11.1). */
 declare const SshDisconnectReason: {
@@ -3048,6 +3331,78 @@ declare class SshTransportConnection {
     private sendKeepalivePing;
 }
 
+interface SshPasswordCredential {
+    type: "password";
+    username: string;
+    password: string;
+}
+interface SshPublickeyCredential {
+    type: "publickey";
+    username: string;
+    algorithmName: string;
+    /** Raw public key blob in SSH wire format (e.g. the bytes returned by ssh-keygen -e -f key.pub). */
+    publicKeyBlob: Uint8Array;
+    /**
+     * Signs the challenge data.  The data is already the complete sign-data per RFC 4252 §7.
+     * Should return the signature blob (without algorithm prefix; caller adds wrapping).
+     */
+    sign: (data: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+}
+interface SshKeyboardInteractiveCredential {
+    type: "keyboard-interactive";
+    username: string;
+    /**
+     * Called for each INFO_REQUEST round.  Return one string per prompt in order.
+     */
+    respond: (name: string, instruction: string, prompts: Array<{
+        echo: boolean;
+        prompt: string;
+    }>) => Promise<string[]> | string[];
+}
+type SshCredential = SshPasswordCredential | SshPublickeyCredential | SshKeyboardInteractiveCredential;
+interface SshAuthOptions {
+    credential: SshCredential;
+    /** SSH session id (exchange hash) from key exchange — required for publickey signing. */
+    sessionId: Uint8Array;
+    /** Maximum number of USERAUTH_FAILURE retries before giving up. Defaults to 4. */
+    maxAttempts?: number;
+}
+interface SshAuthResult {
+    /** Banner lines received from the server during authentication. */
+    bannerLines: string[];
+    /** Auth method that succeeded. */
+    method: string;
+}
+/**
+ * Runs SSH user authentication over an encrypted transport connection.
+ *
+ * Call this after `SshTransportConnection.connect()` completes.
+ * Returns a generator of inbound payloads for the upper (connection) layer to consume.
+ * Resolves with an `SshAuthResult` on success; throws `AuthenticationError` on failure.
+ */
+declare class SshAuthSession {
+    private readonly transport;
+    constructor(transport: SshTransportConnection);
+    authenticate(options: SshAuthOptions): Promise<SshAuthResult>;
+    private runKeyboardInteractiveRounds;
+    private pendingPayload;
+    private nextPayload;
+    private nextPayloadSkippingBanners;
+}
+
+interface BuildPublickeyCredentialOptions {
+    /** Username to authenticate as. */
+    username: string;
+    /** Decoded private key (OpenSSH or PKCS8 PEM accepted by `crypto.createPrivateKey`). */
+    privateKey: KeyObject;
+    /**
+     * For RSA keys, the SSH signature algorithm. Defaults to `rsa-sha2-512`.
+     * Ignored for Ed25519 keys.
+     */
+    rsaSignatureAlgorithm?: "rsa-sha2-256" | "rsa-sha2-512";
+}
+declare function buildPublickeyCredential(options: BuildPublickeyCredentialOptions): SshPublickeyCredential;
+
 /**
  * SSH session channel (RFC 4254 §6).
  *
@@ -3073,74 +3428,435 @@ interface SshSessionChannelOptions {
  * A single SSH session channel.
  * Not safe to share across concurrent callers; each SftpSession should own one.
  */
-declare class SshSessionChannel {
-    private readonly transport;
-    private phase;
-    /** Remote channel id assigned by the server in OPEN_CONFIRMATION. */
-    private remoteChannelId;
-    /** Bytes the remote side can still receive before we must stop sending. */
-    private remoteWindowRemaining;
-    /** Maximum packet data size the remote accepts. */
-    private remoteMaxPacketSize;
-    /** Local window: bytes we can still accept from remote. */
-    private localWindowConsumed;
-    private localWindowSize;
-    /** Queue of inbound data for the `receiveData()` generator. */
-    private readonly inboundQueue;
-    private waitingConsumer;
-    /** Queue of outbound data waiting for remote window space. */
-    private readonly outboundQueue;
-    /**
-     * FIFO of waiters blocked on remote window credit. Each WINDOW_ADJUST wakes
-     * exactly one waiter; concurrent senders must not lose wakeups.
-     */
-    private readonly outboundDrainedWaiters;
-    /** Serializes sendData() calls so byte order on the wire matches call order. */
-    private sendChain;
-    private readonly localChannelId;
-    constructor(transport: SshTransportConnection, options?: SshSessionChannelOptions);
-    /**
-     * Opens the channel and requests a subsystem.
-     * Resolves once the server confirms both CHANNEL_OPEN and the subsystem request.
-     */
-    openSubsystem(subsystemName: string): Promise<void>;
+declare class SshSessionChannel {
+    private readonly transport;
+    private phase;
+    /** Remote channel id assigned by the server in OPEN_CONFIRMATION. */
+    private remoteChannelId;
+    /** Bytes the remote side can still receive before we must stop sending. */
+    private remoteWindowRemaining;
+    /** Maximum packet data size the remote accepts. */
+    private remoteMaxPacketSize;
+    /** Local window: bytes we can still accept from remote. */
+    private localWindowConsumed;
+    private localWindowSize;
+    /** Queue of inbound data for the `receiveData()` generator. */
+    private readonly inboundQueue;
+    private waitingConsumer;
+    /** Queue of outbound data waiting for remote window space. */
+    private readonly outboundQueue;
+    /**
+     * FIFO of waiters blocked on remote window credit. Each WINDOW_ADJUST wakes
+     * exactly one waiter; concurrent senders must not lose wakeups.
+     */
+    private readonly outboundDrainedWaiters;
+    /** Serializes sendData() calls so byte order on the wire matches call order. */
+    private sendChain;
+    private readonly localChannelId;
+    constructor(transport: SshTransportConnection, options?: SshSessionChannelOptions);
+    /**
+     * Opens the channel and requests a subsystem.
+     * Resolves once the server confirms both CHANNEL_OPEN and the subsystem request.
+     */
+    openSubsystem(subsystemName: string): Promise<void>;
+    /**
+     * Opens the channel and executes a command.
+     */
+    openExec(command: string): Promise<void>;
+    private openChannel;
+    private requestSubsystem;
+    private requestExec;
+    private awaitChannelRequestReply;
+    /**
+     * Sends data on the channel. Respects the remote window; if there is no space,
+     * splits the data and queues the remainder for when WINDOW_ADJUST arrives.
+     *
+     * Concurrent calls are serialized so wire byte order matches call order.
+     */
+    sendData(data: Uint8Array): Promise<void>;
+    private sendDataLocked;
+    /**
+     * Async generator that yields raw data buffers from the channel.
+     * Returns (done) when the channel receives EOF or CLOSE.
+     */
+    receiveData(): AsyncGenerator<Buffer$1, void, undefined>;
+    /**
+     * Sends EOF and CLOSE.  Should be called when the client is done sending.
+     */
+    close(): void;
+    /**
+     * Feed an inbound transport payload to this channel.
+     * Called by the channel multiplexer (`SshConnectionManager`).
+     */
+    dispatch(payload: Buffer$1): void;
+    dispatchError(error: Error): void;
+    private consumeLocalWindow;
+    private enqueueInbound;
+    private dequeueInbound;
+    /** Pull the next payload from the transport (used during channel setup only). */
+    private nextPayload;
+}
+
+/**
+ * SSH connection protocol manager (RFC 4254).
+ *
+ * Drives the transport-level `receivePayloads()` generator and dispatches each
+ * payload to the right `SshSessionChannel` by recipient channel id.
+ *
+ * Lifecycle:
+ *   1. Create after auth succeeds.
+ *   2. Call `openSubsystemChannel("sftp")` or `openExecChannel(cmd)` to get a channel.
+ *   3. Drive the pump: `start()` returns a Promise that resolves when the transport
+ *      closes cleanly or rejects on a fatal error.
+ */
+
+declare class SshConnectionManager {
+    private readonly transport;
+    private readonly channels;
+    private nextLocalId;
+    private pumpPromise;
+    private pumpResolve;
+    private pumpReject;
+    /** Payloads that arrived before any channel registered (buffered for the first channel). */
+    private readonly pendingSetupPayloads;
+    private setupPayloadConsumer;
+    constructor(transport: SshTransportConnection);
+    /**
+     * Delivers the next connection-layer payload to callers during channel setup.
+     * Called by `SshSessionChannel` during `openChannel()` / `requestSubsystem()`.
+     *
+     * Channel setup happens sequentially before `start()` begins pumping, so we
+     * pull directly from the transport iterator here.
+     */
+    nextSetupPayload(): Promise<Buffer$1>;
+    /**
+     * Opens a session channel and starts the SFTP subsystem on it.
+     * Must be called before `start()`.
+     */
+    openSubsystemChannel(subsystemName: string): Promise<SshSessionChannel>;
+    /**
+     * Opens a session channel and runs the given command on it.
+     * Must be called before `start()`.
+     */
+    openExecChannel(command: string): Promise<SshSessionChannel>;
+    /**
+     * Starts the main dispatch loop.  Returns a Promise that resolves when the
+     * connection closes cleanly, or rejects on a fatal transport error.
+     *
+     * Call this after all channels have been opened and the application is ready
+     * to receive data.
+     */
+    start(): Promise<void>;
+    /**
+     * Runs channel setup (open + request) with a dedicated payload pump that
+     * pulls from the transport iterator and dispatches non-channel-setup messages
+     * to `pendingSetupPayloads` for later processing.
+     */
+    private runChannelSetup;
+    private pump;
+    private dispatch;
+    private terminateChannels;
+}
+
+/**
+ * Stateful SSH primitive decoder that reads sequential values from a packet payload.
+ */
+declare class SshDataReader {
+    private readonly source;
+    private offset;
+    constructor(source: Uint8Array);
+    get remaining(): number;
+    hasMore(): boolean;
+    readByte(): number;
+    readBoolean(): boolean;
+    readBytes(length: number): Buffer$1;
+    readUint32(): number;
+    readUint64(): bigint;
+    readString(): Buffer$1;
+    readUtf8String(): string;
+    readNameList(): string[];
+    /**
+     * Reads an SSH `mpint` value (RFC 4251 §5): a length-prefixed two's-complement
+     * big-endian integer. Returns the raw magnitude bytes (non-negative integers
+     * may have a leading 0x00 byte preserved by the caller as needed).
+     */
+    readMpint(): Buffer$1;
+    assertFinished(): void;
+    private ensureAvailable;
+}
+
+/**
+ * Minimal SSH primitive encoder for transport and authentication packets.
+ */
+declare class SshDataWriter {
+    private readonly chunks;
+    private length;
+    writeByte(value: number): this;
+    writeBoolean(value: boolean): this;
+    writeBytes(value: Uint8Array): this;
+    writeUint32(value: number): this;
+    writeUint64(value: bigint): this;
+    writeString(value: string | Uint8Array, encoding?: BufferEncoding): this;
+    writeMpint(value: Uint8Array): this;
+    writeNameList(values: readonly string[]): this;
+    toBuffer(): Buffer$1;
+    private push;
+    private assertByte;
+}
+
+/**
+ * FTPS control-channel TLS mode.
+ *
+ * `explicit` connects on a plain FTP control socket and upgrades with `AUTH TLS`;
+ * `implicit` starts TLS immediately, typically on port 990.
+ */
+type FtpsMode = "explicit" | "implicit";
+/**
+ * FTPS data-channel protection level requested after TLS negotiation.
+ *
+ * `private` sends `PROT P` and wraps passive data sockets in TLS. `clear` sends
+ * `PROT C`, keeping the control channel encrypted while leaving data sockets plain.
+ */
+type FtpsDataProtection = "clear" | "private";
+/**
+ * Host selection strategy for PASV data endpoints.
+ *
+ * `control` connects data sockets back to the control connection host, which avoids
+ * broken private or unroutable PASV addresses from NATed servers. `advertised` uses
+ * the host supplied by the server's PASV response for deployments that require it.
+ */
+type FtpPassiveHostStrategy = "advertised" | "control";
+/** Options used to create the classic FTP provider factory. */
+interface FtpProviderOptions {
+    /** Default control port used when a connection profile omits `port`. */
+    defaultPort?: number;
+    /** PASV host selection strategy. Defaults to `control` for NAT-friendly compatibility. */
+    passiveHostStrategy?: FtpPassiveHostStrategy;
+}
+/** Options used to create the FTPS provider factory. */
+interface FtpsProviderOptions extends FtpProviderOptions {
+    /** TLS mode used for the control connection. Defaults to explicit FTPS on port 21. */
+    mode?: FtpsMode;
+    /** Data channel protection requested through PROT. Defaults to private/encrypted data. */
+    dataProtection?: FtpsDataProtection;
+}
+/**
+ * Creates a provider factory for classic FTP connections.
+ *
+ * @param options - Optional provider defaults.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example Plain FTP (cleartext — prefer FTPS or SFTP whenever possible)
+ * ```ts
+ * import { createFtpProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createFtpProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "ftp.example.com",
+ *   provider: "ftp",
+ *   username: "deploy",
+ *   password: { env: "FTP_PASSWORD" },
+ * });
+ * ```
+ */
+declare function createFtpProviderFactory(options?: FtpProviderOptions): ProviderFactory;
+/**
+ * Creates a provider factory for explicit or implicit FTPS connections.
+ *
+ * The factory resolves TLS material from each connection profile, upgrades explicit
+ * sessions with `AUTH TLS`, and applies the configured `PROT` data-channel policy.
+ *
+ * @param options - Optional provider defaults.
+ * @returns Provider factory suitable for `createTransferClient({ providers: [...] })`.
+ *
+ * @example FTPS with public-CA TLS (no extra TLS material needed)
+ * ```ts
+ * import { createFtpsProviderFactory, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({ providers: [createFtpsProviderFactory()] });
+ *
+ * const session = await client.connect({
+ *   host: "ftps.example.com",
+ *   provider: "ftps",
+ *   username: "deploy",
+ *   password: { env: "FTPS_PASSWORD" },
+ *   tls: { minVersion: "TLSv1.2" },
+ * });
+ * ```
+ *
+ * @example FTPS with private CA + certificate pinning (defence-in-depth)
+ * ```ts
+ * await client.connect({
+ *   host: "ftps.internal.example",
+ *   provider: "ftps",
+ *   username: "audit",
+ *   tls: {
+ *     ca: { path: "./certs/ca-bundle.pem" },
+ *     cert: { path: "./certs/client.crt" },
+ *     key: { path: "./certs/client.key" },
+ *     // Optional but recommended:
+ *     pinnedFingerprint256: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
+ *   },
+ * });
+ * ```
+ */
+declare function createFtpsProviderFactory(options?: FtpsProviderOptions): ProviderFactory;
+
+/** FTP response status family derived from the first digit of the reply code. */
+type FtpResponseStatus = "preliminary" | "completion" | "intermediate" | "transientFailure" | "permanentFailure";
+/**
+ * Complete parsed FTP response.
+ */
+interface FtpResponse {
+    /** Numeric three-digit FTP reply code. */
+    code: number;
+    /** Response message with multi-line content joined by newlines. */
+    message: string;
+    /** Individual message lines without the reply-code prefix. */
+    lines: string[];
+    /** Raw response lines joined by newlines. */
+    raw: string;
+    /** Classified response status family. */
+    status: FtpResponseStatus;
+    /** Whether the response is a 1xx preliminary reply. */
+    preliminary: boolean;
+    /** Whether the response is a 2xx completion reply. */
+    completion: boolean;
+    /** Whether the response is a 3xx intermediate reply. */
+    intermediate: boolean;
+    /** Whether the response is a 4xx transient failure reply. */
+    transientFailure: boolean;
+    /** Whether the response is a 5xx permanent failure reply. */
+    permanentFailure: boolean;
+}
+/**
+ * Stateful parser for socket-delivered FTP response text.
+ */
+declare class FtpResponseParser {
+    private buffer;
+    private pendingResponse;
     /**
-     * Opens the channel and executes a command.
+     * Adds incoming socket data and returns any complete responses.
+     *
+     * @param chunk - Buffer or string chunk from the FTP control connection.
+     * @returns Zero or more complete parsed responses.
+     * @throws {@link ParseError} When a malformed standalone response line is received.
      */
-    openExec(command: string): Promise<void>;
-    private openChannel;
-    private requestSubsystem;
-    private requestExec;
-    private awaitChannelRequestReply;
+    push(chunk: Buffer | string): FtpResponse[];
     /**
-     * Sends data on the channel. Respects the remote window; if there is no space,
-     * splits the data and queues the remainder for when WINDOW_ADJUST arrives.
+     * Clears buffered text and any incomplete multi-line response state.
      *
-     * Concurrent calls are serialized so wire byte order matches call order.
+     * @returns Nothing.
      */
-    sendData(data: Uint8Array): Promise<void>;
-    private sendDataLocked;
+    reset(): void;
     /**
-     * Async generator that yields raw data buffers from the channel.
-     * Returns (done) when the channel receives EOF or CLOSE.
+     * Checks whether the parser is holding buffered or incomplete response data.
+     *
+     * @returns `true` when there is unconsumed text or an open multi-line response.
      */
-    receiveData(): AsyncGenerator<Buffer$1, void, undefined>;
+    hasPendingResponse(): boolean;
     /**
-     * Sends EOF and CLOSE.  Should be called when the client is done sending.
+     * Consumes one line of FTP response text.
+     *
+     * @param rawLine - Line without a trailing CRLF delimiter.
+     * @returns A complete response when the line finishes one, otherwise `undefined`.
+     * @throws {@link ParseError} When a malformed standalone line is encountered.
      */
-    close(): void;
+    private consumeLine;
+}
+/**
+ * Parses an exact set of response lines into one complete FTP response.
+ *
+ * @param lines - Raw response lines without trailing newline delimiters.
+ * @returns A single complete parsed FTP response.
+ * @throws {@link ParseError} When the lines do not contain exactly one complete response.
+ */
+declare function parseFtpResponseLines(lines: string[]): FtpResponse;
+
+/**
+ * FTP FEAT response parser.
+ *
+ * This module extracts advertised server capabilities and MLST facts from a parsed
+ * FTP response, raw response string, or pre-split response lines.
+ *
+ * @module providers/classic/ftp/FtpFeatureParser
+ */
+
+/**
+ * Normalized server features returned by an FTP FEAT command.
+ */
+interface FtpFeatures {
+    /** Raw normalized feature lines. */
+    raw: string[];
+    /** Uppercase feature names for fast lookup. */
+    names: Set<string>;
+    /** MLST facts advertised by the server, preserving required-fact markers. */
+    mlstFacts: string[];
     /**
-     * Feed an inbound transport payload to this channel.
-     * Called by the channel multiplexer (`SshConnectionManager`).
+     * Checks whether a named feature is advertised.
+     *
+     * @param featureName - Feature name to search for, case-insensitively.
+     * @returns `true` when the feature appears in the FEAT response.
      */
-    dispatch(payload: Buffer$1): void;
-    dispatchError(error: Error): void;
-    private consumeLocalWindow;
-    private enqueueInbound;
-    private dequeueInbound;
-    /** Pull the next payload from the transport (used during channel setup only). */
-    private nextPayload;
+    supports(featureName: string): boolean;
 }
+/**
+ * Parses FTP FEAT output into a normalized feature set.
+ *
+ * @param input - Parsed FTP response, raw string, or individual response lines.
+ * @returns Normalized feature names, raw feature lines, and MLST fact names.
+ */
+declare function parseFtpFeatures(input: FtpResponse | string | string[]): FtpFeatures;
+
+/**
+ * Parses an MLSD directory listing into normalized remote entries.
+ *
+ * @param input - Raw MLSD response body.
+ * @param directory - Parent remote directory used to build entry paths.
+ * @returns Remote entries excluding the `.` and `..` pseudo entries.
+ * @throws {@link ParseError} When any listing line is malformed.
+ */
+declare function parseMlsdList(input: string, directory?: string): RemoteEntry[];
+/**
+ * Parses a Unix-style FTP `LIST` response into normalized remote entries.
+ *
+ * This parser covers the common `ls -l` shape returned by classic FTP daemons and
+ * is used as a compatibility fallback when a server does not support MLSD.
+ *
+ * @param input - Raw LIST response body.
+ * @param directory - Parent remote directory used to build entry paths.
+ * @param now - Reference date used when LIST entries include time but omit year.
+ * @returns Remote entries excluding `.` and `..` pseudo entries.
+ * @throws {@link ParseError} When any non-summary listing line is malformed.
+ */
+declare function parseUnixList(input: string, directory?: string, now?: Date): RemoteEntry[];
+/**
+ * Parses one Unix-style FTP `LIST` line.
+ *
+ * @param line - Raw listing line in an `ls -l` compatible format.
+ * @param directory - Parent remote directory used to build the entry path.
+ * @param now - Reference date used when the line omits a year.
+ * @returns Normalized remote entry with raw LIST metadata retained.
+ * @throws {@link ParseError} When the line is not a supported Unix LIST entry.
+ */
+declare function parseUnixListLine(line: string, directory?: string, now?: Date): RemoteEntry;
+/**
+ * Parses a single MLSD or MLST fact line.
+ *
+ * @param line - Raw fact line in `fact=value; name` format.
+ * @param directory - Parent remote directory used to build the entry path.
+ * @returns A normalized remote entry with parsed facts in `raw` metadata.
+ * @throws {@link ParseError} When the line does not contain facts and a name.
+ */
+declare function parseMlsdLine(line: string, directory?: string): RemoteEntry;
+/**
+ * Parses the UTC timestamp format used by MLST/MLSD `modify` facts.
+ *
+ * @param input - Timestamp text such as `20260427010203.123`.
+ * @returns A UTC Date when the timestamp is valid, otherwise `undefined`.
+ */
+declare function parseMlstTimestamp(input: string | undefined): Date | undefined;
 
 /**
  * SFTP v3 file attribute encoding and decoding (draft-ietf-secsh-filexfer-02 §5).
@@ -3311,6 +4027,15 @@ interface NativeSftpProviderOptions {
      * traffic. Disabled when omitted or `0`.
      */
     keepaliveIntervalMs?: number;
+    /**
+     * Maximum concurrent file-transfer operations the engine should schedule
+     * against a single SFTP session. Each in-flight read/write occupies an
+     * outstanding SFTP request slot multiplexed over the same SSH channel; the
+     * default of `8` keeps memory bounded on commodity servers, but high-RTT
+     * links and modern OpenSSH builds can comfortably handle 16\u201364. Must be
+     * a positive integer.
+     */
+    maxConcurrency?: number;
 }
 /**
  * Low-level handles exposed by a native SFTP session for diagnostics and
@@ -3594,9 +4319,47 @@ interface TransferPlanSummary {
     /** Counts grouped by action. */
     actions: Record<string, number>;
 }
-/** Creates a transfer plan from dry-run planning input. */
+/**
+ * Creates a transfer plan from dry-run planning input.
+ *
+ * Plans are immutable, structured descriptions of intended work. Pair with
+ * {@link createSyncPlan} or {@link createAtomicDeployPlan} for end-to-end
+ * planning, or build steps by hand when you need full control. Pass the plan
+ * to {@link createTransferJobsFromPlan} to materialize executable jobs.
+ *
+ * @example Build a plan with two upload steps and inspect it
+ * ```ts
+ * import { createTransferPlan, summarizeTransferPlan } from "@zero-transfer/sdk";
+ *
+ * const plan = createTransferPlan({
+ *   id: "manual-batch",
+ *   steps: [
+ *     { action: "upload", source: "./a.bin", destination: "/lake/a.bin", expectedBytes: 1024 },
+ *     { action: "upload", source: "./b.bin", destination: "/lake/b.bin", expectedBytes: 2048 },
+ *   ],
+ * });
+ *
+ * console.table(summarizeTransferPlan(plan));
+ * ```
+ */
 declare function createTransferPlan(input: TransferPlanInput): TransferPlan;
-/** Summarizes a transfer plan for diagnostics, previews, and tests. */
+/**
+ * Summarizes a transfer plan for diagnostics, previews, and tests.
+ *
+ * Returns aggregate counts (total / executable / skipped / destructive),
+ * total expected bytes, and a per-action histogram. Useful for printing a
+ * one-line plan summary before executing or for asserting plan shape in
+ * tests.
+ *
+ * @example Print a plan preview
+ * ```ts
+ * import { summarizeTransferPlan } from "@zero-transfer/sdk";
+ *
+ * const summary = summarizeTransferPlan(plan);
+ * console.log(`${summary.executableSteps} steps, ${summary.totalExpectedBytes} bytes total`);
+ * console.log("Actions:", summary.actions);
+ * ```
+ */
 declare function summarizeTransferPlan(plan: TransferPlan): TransferPlanSummary;
 /** Converts executable plan steps into transfer jobs while preserving order. */
 declare function createTransferJobsFromPlan(plan: TransferPlan): TransferJob[];
@@ -3673,7 +4436,41 @@ interface TransferQueueSummary {
     /** Failed queue items in queue order. */
     failures: TransferQueueItem[];
 }
-/** Minimal transfer queue with concurrency, pause/resume, cancellation, and drain summaries. */
+/**
+ * Minimal transfer queue with concurrency, pause/resume, cancellation, and drain summaries.
+ *
+ * Wrap a {@link TransferEngine} with a queue when you need to run many transfers
+ * concurrently with bounded parallelism, observe per-job progress, or drive
+ * a UI from a single source of truth. Items are FIFO; failures and successes
+ * are surfaced via observers and in the final {@link TransferQueueSummary}.
+ *
+ * @example Run a batch of uploads with concurrency=4
+ * ```ts
+ * import {
+ *   TransferQueue,
+ *   createProviderTransferExecutor,
+ * } from "@zero-transfer/sdk";
+ *
+ * const queue = new TransferQueue({
+ *   concurrency: 4,
+ *   executor: createProviderTransferExecutor({ client }),
+ *   onProgress: (e) => console.log(`${e.jobId}: ${e.bytesTransferred}`),
+ *   onError: (item, err) => console.error(`${item.job.id} failed`, err),
+ * });
+ *
+ * for (const file of files) {
+ *   queue.enqueue({
+ *     id: file.name,
+ *     operation: "upload",
+ *     source: { profile: localProfile, path: file.path },
+ *     destination: { profile: s3Profile, path: `/lake/${file.name}` },
+ *   });
+ * }
+ *
+ * const summary = await queue.drain();
+ * console.log(`Completed ${summary.completed} / ${summary.total}`);
+ * ```
+ */
 declare class TransferQueue {
     private readonly engine;
     private readonly items;
@@ -3953,6 +4750,26 @@ interface DiffRemoteTreesOptions {
  * @param destinationPath - Destination-side root path being compared.
  * @param options - Optional comparison controls.
  * @returns Diff result containing entries and a summary.
+ *
+ * @example Diff two SFTP subtrees and feed the result into createSyncPlan
+ * ```ts
+ * import { createSyncPlan, diffRemoteTrees } from "@zero-transfer/sdk";
+ *
+ * const diff = await diffRemoteTrees(
+ *   srcSession.fs, "/exports",
+ *   dstSession.fs, "/exports",
+ *   { compareUniqueId: true },
+ * );
+ *
+ * console.log(diff.summary); // { added, removed, changed, unchanged }
+ *
+ * const plan = createSyncPlan({
+ *   id: "exports-sync",
+ *   diff,
+ *   source: { provider: "sftp", rootPath: "/exports" },
+ *   destination: { provider: "sftp", rootPath: "/exports" },
+ * });
+ * ```
  */
 declare function diffRemoteTrees(source: RemoteFileSystem, sourcePath: string, destination: RemoteFileSystem, destinationPath: string, options?: DiffRemoteTreesOptions): Promise<RemoteTreeDiff>;
 
@@ -4024,6 +4841,31 @@ interface CreateSyncPlanOptions {
  * @param options - Inputs and policies that shape the plan.
  * @returns Transfer plan ready for `createTransferJobsFromPlan` or queue execution.
  * @throws {@link ConfigurationError} When `conflictPolicy: "error"` encounters a conflict.
+ *
+ * @example Mirror SFTP → S3 with deletes
+ * ```ts
+ * import {
+ *   createSyncPlan,
+ *   diffRemoteTrees,
+ *   summarizeTransferPlan,
+ * } from "@zero-transfer/sdk";
+ *
+ * const diff = await diffRemoteTrees(
+ *   srcSession.fs, "/dist",
+ *   dstSession.fs, "/releases/current",
+ * );
+ *
+ * const plan = createSyncPlan({
+ *   id: "release-mirror",
+ *   diff,
+ *   source: { provider: "sftp", rootPath: "/dist" },
+ *   destination: { provider: "s3", rootPath: "/releases/current" },
+ *   deletePolicy: "mirror",
+ *   conflictPolicy: "overwrite",
+ * });
+ *
+ * console.table(summarizeTransferPlan(plan));
+ * ```
  */
 declare function createSyncPlan(options: CreateSyncPlanOptions): TransferPlan;
 
@@ -4139,9 +4981,39 @@ interface CreateAtomicDeployPlanOptions {
 /**
  * Builds an {@link AtomicDeployPlan} that stages a release, swaps it live, and prunes old releases.
  *
+ * The plan describes a blue/green-style deploy:
+ *  1. Upload to a timestamped staging directory under `<destination>/.releases/`.
+ *  2. Atomically swap the `current` symlink/rename to point at the new release.
+ *  3. Optionally prune old releases beyond `retain`.
+ *
+ * No I/O is performed — the host executes the plan steps. Pair with
+ * {@link createTransferPlan} or {@link createTransferJobsFromPlan} to execute.
+ *
  * @param options - Inputs and policies that shape the deploy.
  * @returns Structured deploy plan ready for execution by the calling host.
  * @throws {@link ConfigurationError} When `retain` is less than `1` or the destination root is empty.
+ *
+ * @example Plan a release with rollback path
+ * ```ts
+ * import { createAtomicDeployPlan } from "@zero-transfer/sdk";
+ *
+ * const plan = createAtomicDeployPlan({
+ *   id: "web-2026-04-28",
+ *   source: { rootPath: "./dist" },
+ *   destination: {
+ *     profile: { host: "web1.example.com", provider: "sftp", username: "deploy" },
+ *     rootPath: "/srv/www",
+ *   },
+ *   retain: 5,
+ *   existingReleases: [
+ *     "/srv/www/.releases/2026-04-21T00-00-00Z",
+ *     "/srv/www/.releases/2026-04-14T00-00-00Z",
+ *   ],
+ * });
+ *
+ * console.log(plan.swap);   // staging → current rename
+ * console.log(plan.prune);  // releases scheduled for removal
+ * ```
  */
 declare function createAtomicDeployPlan(options: CreateAtomicDeployPlanOptions): AtomicDeployPlan;
 
@@ -4641,9 +5513,33 @@ interface CreateWebhookAuditLogOptions {
  *
  * Entries whose `type` is not in `target.types` are silently dropped. `list()`
  * always returns an empty array because webhook deliveries are not buffered.
+ * Payloads are HMAC-signed with `target.secret` (when provided) so receivers
+ * can verify authenticity before acting on them.
  *
  * @param options - Webhook target plus optional retry/observer hooks.
  * @returns An audit log that delivers each `record` call to the webhook.
+ *
+ * @example Compose a webhook log with an in-memory log for local replay
+ * ```ts
+ * import {
+ *   InMemoryAuditLog,
+ *   composeAuditLogs,
+ *   createWebhookAuditLog,
+ * } from "@zero-transfer/sdk";
+ *
+ * const memory = new InMemoryAuditLog();
+ * const webhook = createWebhookAuditLog({
+ *   target: {
+ *     url: "https://hooks.example.com/zt",
+ *     secret: { env: "ZT_WEBHOOK_SECRET" },
+ *     types: ["transfer.success", "transfer.failure"],
+ *   },
+ *   onDelivery: ({ result }) => console.log("delivered", result.statusCode),
+ * });
+ *
+ * const audit = composeAuditLogs(memory, webhook);
+ * await audit.record({ type: "transfer.success", receipt });
+ * ```
  */
 declare function createWebhookAuditLog(options: CreateWebhookAuditLogOptions): MftAuditLog;
 
@@ -4798,7 +5694,48 @@ interface MftSchedulerOptions {
     /** Timer/clock injection used by tests. */
     timer?: ScheduleTimerHooks;
 }
-/** Runs routes on configured schedules. */
+/**
+ * Runs routes on configured schedules.
+ *
+ * Subscribes to a {@link ScheduleRegistry}, computes the next fire time for
+ * each schedule (cron or interval), and dispatches the matching route through
+ * a runner of your choice (`runRoute` by default, or a wrapped runner for
+ * approvals / rate limiting / circuit breaking). Observers fire on each cycle
+ * for telemetry. Tests can inject a deterministic timer via `timer`.
+ *
+ * @example Wire a cron schedule with audit + approval
+ * ```ts
+ * import {
+ *   ApprovalRegistry,
+ *   InMemoryAuditLog,
+ *   MftScheduler,
+ *   RouteRegistry,
+ *   ScheduleRegistry,
+ *   createApprovalGate,
+ *   runRoute,
+ * } from "@zero-transfer/sdk";
+ *
+ * const audit = new InMemoryAuditLog();
+ * const approvals = new ApprovalRegistry();
+ *
+ * const scheduler = new MftScheduler({
+ *   client,
+ *   routes: new RouteRegistry([route]),
+ *   schedules: new ScheduleRegistry([
+ *     { id: "nightly", routeId: route.id, cron: "0 2 * * *" },
+ *   ]),
+ *   runner: createApprovalGate({
+ *     registry: approvals,
+ *     approvalId: ({ route }) => `release:${route.id}`,
+ *     runner: ({ client: c, route: r, signal }) => runRoute({ client: c, route: r, signal }),
+ *   }),
+ *   onResult: ({ receipt }) => audit.record({ type: "transfer.success", receipt }),
+ *   onError:  ({ error })   => audit.record({ type: "transfer.failure", error }),
+ * });
+ *
+ * scheduler.start();
+ * ```
+ */
 declare class MftScheduler {
     private readonly options;
     private readonly now;
@@ -4942,10 +5879,33 @@ interface CreateApprovalGateOptions {
  *
  * The returned runner creates an approval request, waits for resolution, and
  * dispatches the underlying runner only when the request is approved. Rejection
- * surfaces an {@link ApprovalRejectedError}.
+ * surfaces an {@link ApprovalRejectedError}. Pair with {@link MftScheduler} to
+ * implement two-person rules and human-in-the-loop release flows.
  *
  * @param options - Registry, downstream runner, approval-id derivation, hooks.
  * @returns A {@link ScheduleRouteRunner} that gates execution behind approval.
+ *
+ * @example Two-person rule on a release route
+ * ```ts
+ * import {
+ *   ApprovalRegistry,
+ *   createApprovalGate,
+ *   runRoute,
+ * } from "@zero-transfer/sdk";
+ *
+ * const approvals = new ApprovalRegistry();
+ *
+ * const gatedRunner = createApprovalGate({
+ *   registry: approvals,
+ *   approvalId: ({ route }) => `release:${route.id}:${Date.now()}`,
+ *   onRequested: (req) => notifyOnCallChannel(req),
+ *   runner: ({ client, route, signal }) => runRoute({ client, route, signal }),
+ * });
+ *
+ * // Elsewhere, an authorized operator approves or rejects:
+ * approvals.approve(approvalId, { actor: "alice@example.com" });
+ * // approvals.reject(approvalId, { actor: "bob@example.com", reason: "hold release" });
+ * ```
  */
 declare function createApprovalGate(options: CreateApprovalGateOptions): ScheduleRouteRunner;
 
@@ -5020,4 +5980,4 @@ declare function joinRemotePath(...segments: string[]): string;
  */
 declare function basenameRemotePath(input: string): string;
 
-export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithms, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshProfile, type SshSocketFactory, type SshSocketFactoryContext, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDropboxProviderFactory, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };
+export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, DEFAULT_SSH_ALGORITHM_PREFERENCES, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileSystemS3MultipartResumeStoreOptions, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type NegotiatedSshAlgorithms, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithmPreferences, type SshAlgorithms, SshAuthSession, SshConnectionManager, SshDataReader, SshDataWriter, SshDisconnectReason, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveCredential, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshPasswordCredential, type SshProfile, type SshPublickeyCredential, SshSessionChannel, type SshSocketFactory, type SshSocketFactoryContext, SshTransportConnection, type SshTransportConnectionOptions, SshTransportHandshake, type SshTransportHandshakeResult, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildPublickeyCredential, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDropboxProviderFactory, createFileSystemS3MultipartResumeStore, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, negotiateSshAlgorithms, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };