tensorlake 0.5.85 → 0.5.89

package/dist/index.d.cts

@@ -40,6 +40,8 @@ interface TracedJson {
 interface TracedBytes {
     traceId: string;
     data: Buffer;
+    contentId?: string;
+    fullSize?: number;
 }
 interface TracedEvents {
     traceId: string;
@@ -122,16 +124,30 @@ interface NativeRepositoryClient {
     mergeRepo(repo: string, ours: string, theirs: string, preflight: boolean, deep: boolean, materialize: boolean, message?: string | null, base?: string | null): Promise<TracedJson>;
     commitConflicts(repo: string, commit: string): Promise<TracedJson>;
     createFilesystem(name: string): Promise<string>;
+    forkFilesystem(name: string, base: string, snapshot?: string | null): Promise<TracedJson>;
     listFilesystems(): Promise<TracedJson>;
     filesystemMeta(name: string): Promise<TracedJson>;
     deleteFilesystem(name: string): Promise<string>;
     filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
-    readFilesystemFile(name: string, path: string, version: string): Promise<TracedBytes>;
+    retainFilesystemSnapshot(name: string, message: string, requestId: string): Promise<TracedJson>;
+    listFilesystemSnapshots(name: string): Promise<TracedJson>;
+    deleteFilesystemSnapshot(name: string, snapshot: string): Promise<string>;
+    readFilesystemFile(name: string, path: string, version: string, offset?: number, length?: number): Promise<TracedBytes>;
     listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
     pushFilesystemFiles(name: string, files: Array<{
         path: string;
         content: Buffer;
-    }>, deletes: string[], message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    }>, deletes: string[], moves: Array<{
+        from: string;
+        to: string;
+    }>, copies: Array<{
+        from: string;
+        to: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    pushFilesystemPaths(name: string, files: Array<{
+        path: string;
+        localPath: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
 }
 
 declare enum SandboxStatus {
@@ -1474,7 +1490,6 @@ declare function deleteFileSystem(fileSystemId: string): Promise<void>;
 interface FilesystemInfo {
     name: string;
     fullName: string;
-    defaultBranch: string;
     status: string;
     kind: string;
 }
@@ -1482,13 +1497,12 @@ interface FilesystemInfo {
 interface FilesystemStatus {
     name: string;
     status: string;
-    defaultBranch: string;
     /**
-     * Commit hash the default branch currently points at; null for an empty
-     * filesystem that has never been written to.
+     * Current native version id; null for an empty filesystem that has never
+     * been written to.
      */
-    headCommit: string | null;
-    /** Server-side movement counter for the default branch, when reported. */
+    versionId: string | null;
+    /** Server-side movement counter for the live version, when reported. */
     generation: number | null;
 }
 /** One directory entry from a filesystem listing. */
@@ -1496,26 +1510,55 @@ interface FileEntry {
     name: string;
     /** Path of the entry relative to the filesystem root. */
     path: string;
-    /** Git blob/tree object id. */
-    oid: string;
-    /** Raw git mode (0o100644 file, 0o100755 executable, 0o120000 symlink, 0o40000 dir). */
-    mode: number;
+    /** Stable native content identity for the file or directory. */
+    contentId: string;
+    /** Native entry kind. */
+    kind: "file" | "directory" | "symlink";
+    /** Whether a regular file is executable. */
+    executable: boolean;
     /** Blob size in bytes when cheaply known server-side. */
     size: number | null;
     isDir: boolean;
     isSymlink: boolean;
 }
-/** A durable version of the filesystem (a commit). */
-interface Snapshot {
-    /** Commit hash — pass as `version` to read the filesystem at this point. */
-    commit: string;
-    tree: string;
-    refName: string;
-    parent: string | null;
+/** Bytes plus immutable identity/size returned by one file request. */
+interface FilesystemFileRead {
+    data: Uint8Array;
+    /** Stable native identity for the complete file content. */
+    contentId: string;
+    /** Size of the complete file, even when `data` is a requested range. */
+    size: number;
+}
+interface FilesystemReadOptions {
+    /** Current `main` head when omitted; otherwise one retained snapshot id. */
+    version?: string;
+    /** Half-open byte selection expressed as offset + length. */
+    range?: {
+        offset: number;
+        length: number;
+    };
+}
+/** The durable live version produced by one atomic filesystem publication. */
+interface FilesystemVersion {
+    /** Native version id — pass as `version` to read the filesystem at this point. */
+    versionId: string;
+    /** Version replaced by this publication, or null for the first publication. */
+    previousVersionId: string | null;
     /** False when the write was a no-op (content identical to the parent). */
     created: boolean;
     message: string;
 }
+/** One newly retained native filesystem snapshot. */
+interface FilesystemSnapshot {
+    id: string;
+    message: string;
+}
+/** One explicitly retained native filesystem snapshot. */
+interface FilesystemSnapshotInfo {
+    id: string;
+    createdAt: Date;
+    message: string;
+}
 /**
  * Status of a local mount as reported by `tl fs status --json`.
  *
@@ -1559,13 +1602,14 @@ declare class CliNotFoundError extends MountError {
  * Client for Tensorlake filesystems.
  *
  * A filesystem is a durable, versioned file tree that lives in Tensorlake
- * Cloud. Every write produces a {@link Snapshot} (a durable version), files
- * can be read at any version, and a filesystem can be mounted to a local
- * path through the `tl` CLI's FUSE/FSKit daemon.
+ * Cloud. Every write publishes a durable live version; {@link Filesystem.snapshot}
+ * retains the current version permanently. Files can be read at any retained
+ * version, and a filesystem can be mounted to a local path through the `tl`
+ * CLI's FUSE/FSKit daemon.
  *
- * Reads and writes are served by the shared Rust cloud-sdk core (the same
- * engine behind the `tl` CLI), so uploads get content-defined chunking,
- * dedup, transient retries, and idempotent commit reattachment for free.
+ * Server-side SDK writes hash complete files locally, upload missing bytes
+ * directly to checksum-bound object-store targets, and atomically publish
+ * one durable snapshot. Payload bytes never transit the API service.
  *
  * @example
  * const client = new FilesystemClient();   // env-based auth
@@ -1618,6 +1662,11 @@ declare class FilesystemClient {
     constructor(options?: FilesystemClientOptions);
     /** Create a new filesystem and return a handle to it. */
     create(name: string): Promise<Filesystem>;
+    /**
+     * Fork a filesystem at its live head or an explicit retained snapshot.
+     * The server shares immutable content and publishes only metadata.
+     */
+    fork(name: string, baseFilesystem: string, snapshot?: string): Promise<Filesystem>;
     /** Return a handle to an existing filesystem (verifies it exists). */
     get(name: string): Promise<Filesystem>;
     /** List all filesystems in the project. */
@@ -1652,28 +1701,59 @@ declare class Filesystem {
      */
     private branch;
     /** Write one file. Returns the snapshot (version) the write produced. */
-    writeFile(path: string, data: FileData, message?: string): Promise<Snapshot>;
+    writeFile(path: string, data: FileData, message?: string): Promise<FilesystemVersion>;
     /** Write several files (and/or delete paths) in one atomic snapshot. */
-    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<Snapshot>;
-    /** Delete one file. Returns the snapshot the deletion produced. */
-    deleteFile(path: string, message?: string): Promise<Snapshot>;
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<FilesystemVersion>;
+    /**
+     * Stream one local file directly to object storage in bounded parts.
+     * This is the memory-bounded API for multi-GiB files.
+     */
+    writeFileFromPath(path: string, localPath: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Atomically publish local files without loading their complete payloads
+     * into JavaScript or Rust memory.
+     */
+    writeFilesFromPaths(files: Map<string, string> | Record<string, string>, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Move a file or directory without downloading or re-uploading its bytes.
+     * The source removal and destination creation publish as one atomic snapshot.
+     */
+    moveFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Copy a file or directory by reusing immutable content references. No
+     * payload bytes traverse the client, API server, or object store.
+     */
+    copyFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    private publishChanges;
+    /** Delete one file. Returns the durable version the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<FilesystemVersion>;
     /**
      * Return the filesystem's current version as a snapshot.
      *
-     * Writes already create snapshots implicitly; this pins the current head
-     * without changing any content.
+     * Writes publish durable live versions. This retains the current head
+     * permanently in one metadata-only server operation without changing or
+     * copying any content.
      */
-    snapshot(message?: string): Promise<Snapshot>;
+    snapshot(message?: string): Promise<FilesystemSnapshot>;
+    /** List explicitly retained snapshots without reading filesystem contents. */
+    listSnapshots(): Promise<FilesystemSnapshotInfo[]>;
+    /** Delete one permanent retention point; shared/head-reachable bytes remain. */
+    deleteSnapshot(snapshot: string): Promise<void>;
     /**
-     * Read a file's bytes at `version` (branch, ref, or snapshot commit;
-     * defaults to the filesystem's default branch).
+     * Read a file's bytes at `version` (the current `main` head or a retained
+     * snapshot id; defaults to the filesystem's current head).
      */
     readFile(path: string, version?: string): Promise<Uint8Array>;
+    /**
+     * Read bytes and immutable metadata in one request. A range is executed by
+     * Artifact Storage, so callers never download the unrequested remainder.
+     */
+    readFileWithMetadata(path: string, options?: FilesystemReadOptions): Promise<FilesystemFileRead>;
     /** Read a file as UTF-8 text at `version`. Throws on non-UTF-8 content. */
     readText(path: string, version?: string): Promise<string>;
     /** List one directory (non-recursive) at `version`. */
     listFiles(dirPath?: string, version?: string): Promise<FileEntry[]>;
-    /** Remote status: identity plus the current head snapshot. */
+    /** Remote status: identity plus the current native version. */
     status(): Promise<FilesystemStatus>;
     /** Mount this filesystem to a local path (requires the `tl` CLI). */
     mount(localPath: string, readonly?: boolean): Promise<FilesystemMount>;
@@ -1764,4 +1844,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemStatus, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type Snapshot, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };
+export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemFileRead, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemReadOptions, type FilesystemSnapshot, type FilesystemSnapshotInfo, type FilesystemStatus, type FilesystemVersion, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };

package/dist/index.d.ts

@@ -40,6 +40,8 @@ interface TracedJson {
 interface TracedBytes {
     traceId: string;
     data: Buffer;
+    contentId?: string;
+    fullSize?: number;
 }
 interface TracedEvents {
     traceId: string;
@@ -122,16 +124,30 @@ interface NativeRepositoryClient {
     mergeRepo(repo: string, ours: string, theirs: string, preflight: boolean, deep: boolean, materialize: boolean, message?: string | null, base?: string | null): Promise<TracedJson>;
     commitConflicts(repo: string, commit: string): Promise<TracedJson>;
     createFilesystem(name: string): Promise<string>;
+    forkFilesystem(name: string, base: string, snapshot?: string | null): Promise<TracedJson>;
     listFilesystems(): Promise<TracedJson>;
     filesystemMeta(name: string): Promise<TracedJson>;
     deleteFilesystem(name: string): Promise<string>;
     filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
-    readFilesystemFile(name: string, path: string, version: string): Promise<TracedBytes>;
+    retainFilesystemSnapshot(name: string, message: string, requestId: string): Promise<TracedJson>;
+    listFilesystemSnapshots(name: string): Promise<TracedJson>;
+    deleteFilesystemSnapshot(name: string, snapshot: string): Promise<string>;
+    readFilesystemFile(name: string, path: string, version: string, offset?: number, length?: number): Promise<TracedBytes>;
     listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
     pushFilesystemFiles(name: string, files: Array<{
         path: string;
         content: Buffer;
-    }>, deletes: string[], message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    }>, deletes: string[], moves: Array<{
+        from: string;
+        to: string;
+    }>, copies: Array<{
+        from: string;
+        to: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    pushFilesystemPaths(name: string, files: Array<{
+        path: string;
+        localPath: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
 }
 
 declare enum SandboxStatus {
@@ -1474,7 +1490,6 @@ declare function deleteFileSystem(fileSystemId: string): Promise<void>;
 interface FilesystemInfo {
     name: string;
     fullName: string;
-    defaultBranch: string;
     status: string;
     kind: string;
 }
@@ -1482,13 +1497,12 @@ interface FilesystemInfo {
 interface FilesystemStatus {
     name: string;
     status: string;
-    defaultBranch: string;
     /**
-     * Commit hash the default branch currently points at; null for an empty
-     * filesystem that has never been written to.
+     * Current native version id; null for an empty filesystem that has never
+     * been written to.
      */
-    headCommit: string | null;
-    /** Server-side movement counter for the default branch, when reported. */
+    versionId: string | null;
+    /** Server-side movement counter for the live version, when reported. */
     generation: number | null;
 }
 /** One directory entry from a filesystem listing. */
@@ -1496,26 +1510,55 @@ interface FileEntry {
     name: string;
     /** Path of the entry relative to the filesystem root. */
     path: string;
-    /** Git blob/tree object id. */
-    oid: string;
-    /** Raw git mode (0o100644 file, 0o100755 executable, 0o120000 symlink, 0o40000 dir). */
-    mode: number;
+    /** Stable native content identity for the file or directory. */
+    contentId: string;
+    /** Native entry kind. */
+    kind: "file" | "directory" | "symlink";
+    /** Whether a regular file is executable. */
+    executable: boolean;
     /** Blob size in bytes when cheaply known server-side. */
     size: number | null;
     isDir: boolean;
     isSymlink: boolean;
 }
-/** A durable version of the filesystem (a commit). */
-interface Snapshot {
-    /** Commit hash — pass as `version` to read the filesystem at this point. */
-    commit: string;
-    tree: string;
-    refName: string;
-    parent: string | null;
+/** Bytes plus immutable identity/size returned by one file request. */
+interface FilesystemFileRead {
+    data: Uint8Array;
+    /** Stable native identity for the complete file content. */
+    contentId: string;
+    /** Size of the complete file, even when `data` is a requested range. */
+    size: number;
+}
+interface FilesystemReadOptions {
+    /** Current `main` head when omitted; otherwise one retained snapshot id. */
+    version?: string;
+    /** Half-open byte selection expressed as offset + length. */
+    range?: {
+        offset: number;
+        length: number;
+    };
+}
+/** The durable live version produced by one atomic filesystem publication. */
+interface FilesystemVersion {
+    /** Native version id — pass as `version` to read the filesystem at this point. */
+    versionId: string;
+    /** Version replaced by this publication, or null for the first publication. */
+    previousVersionId: string | null;
     /** False when the write was a no-op (content identical to the parent). */
     created: boolean;
     message: string;
 }
+/** One newly retained native filesystem snapshot. */
+interface FilesystemSnapshot {
+    id: string;
+    message: string;
+}
+/** One explicitly retained native filesystem snapshot. */
+interface FilesystemSnapshotInfo {
+    id: string;
+    createdAt: Date;
+    message: string;
+}
 /**
  * Status of a local mount as reported by `tl fs status --json`.
  *
@@ -1559,13 +1602,14 @@ declare class CliNotFoundError extends MountError {
  * Client for Tensorlake filesystems.
  *
  * A filesystem is a durable, versioned file tree that lives in Tensorlake
- * Cloud. Every write produces a {@link Snapshot} (a durable version), files
- * can be read at any version, and a filesystem can be mounted to a local
- * path through the `tl` CLI's FUSE/FSKit daemon.
+ * Cloud. Every write publishes a durable live version; {@link Filesystem.snapshot}
+ * retains the current version permanently. Files can be read at any retained
+ * version, and a filesystem can be mounted to a local path through the `tl`
+ * CLI's FUSE/FSKit daemon.
  *
- * Reads and writes are served by the shared Rust cloud-sdk core (the same
- * engine behind the `tl` CLI), so uploads get content-defined chunking,
- * dedup, transient retries, and idempotent commit reattachment for free.
+ * Server-side SDK writes hash complete files locally, upload missing bytes
+ * directly to checksum-bound object-store targets, and atomically publish
+ * one durable snapshot. Payload bytes never transit the API service.
  *
  * @example
  * const client = new FilesystemClient();   // env-based auth
@@ -1618,6 +1662,11 @@ declare class FilesystemClient {
     constructor(options?: FilesystemClientOptions);
     /** Create a new filesystem and return a handle to it. */
     create(name: string): Promise<Filesystem>;
+    /**
+     * Fork a filesystem at its live head or an explicit retained snapshot.
+     * The server shares immutable content and publishes only metadata.
+     */
+    fork(name: string, baseFilesystem: string, snapshot?: string): Promise<Filesystem>;
     /** Return a handle to an existing filesystem (verifies it exists). */
     get(name: string): Promise<Filesystem>;
     /** List all filesystems in the project. */
@@ -1652,28 +1701,59 @@ declare class Filesystem {
      */
     private branch;
     /** Write one file. Returns the snapshot (version) the write produced. */
-    writeFile(path: string, data: FileData, message?: string): Promise<Snapshot>;
+    writeFile(path: string, data: FileData, message?: string): Promise<FilesystemVersion>;
     /** Write several files (and/or delete paths) in one atomic snapshot. */
-    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<Snapshot>;
-    /** Delete one file. Returns the snapshot the deletion produced. */
-    deleteFile(path: string, message?: string): Promise<Snapshot>;
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<FilesystemVersion>;
+    /**
+     * Stream one local file directly to object storage in bounded parts.
+     * This is the memory-bounded API for multi-GiB files.
+     */
+    writeFileFromPath(path: string, localPath: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Atomically publish local files without loading their complete payloads
+     * into JavaScript or Rust memory.
+     */
+    writeFilesFromPaths(files: Map<string, string> | Record<string, string>, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Move a file or directory without downloading or re-uploading its bytes.
+     * The source removal and destination creation publish as one atomic snapshot.
+     */
+    moveFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Copy a file or directory by reusing immutable content references. No
+     * payload bytes traverse the client, API server, or object store.
+     */
+    copyFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    private publishChanges;
+    /** Delete one file. Returns the durable version the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<FilesystemVersion>;
     /**
      * Return the filesystem's current version as a snapshot.
      *
-     * Writes already create snapshots implicitly; this pins the current head
-     * without changing any content.
+     * Writes publish durable live versions. This retains the current head
+     * permanently in one metadata-only server operation without changing or
+     * copying any content.
      */
-    snapshot(message?: string): Promise<Snapshot>;
+    snapshot(message?: string): Promise<FilesystemSnapshot>;
+    /** List explicitly retained snapshots without reading filesystem contents. */
+    listSnapshots(): Promise<FilesystemSnapshotInfo[]>;
+    /** Delete one permanent retention point; shared/head-reachable bytes remain. */
+    deleteSnapshot(snapshot: string): Promise<void>;
     /**
-     * Read a file's bytes at `version` (branch, ref, or snapshot commit;
-     * defaults to the filesystem's default branch).
+     * Read a file's bytes at `version` (the current `main` head or a retained
+     * snapshot id; defaults to the filesystem's current head).
      */
     readFile(path: string, version?: string): Promise<Uint8Array>;
+    /**
+     * Read bytes and immutable metadata in one request. A range is executed by
+     * Artifact Storage, so callers never download the unrequested remainder.
+     */
+    readFileWithMetadata(path: string, options?: FilesystemReadOptions): Promise<FilesystemFileRead>;
     /** Read a file as UTF-8 text at `version`. Throws on non-UTF-8 content. */
     readText(path: string, version?: string): Promise<string>;
     /** List one directory (non-recursive) at `version`. */
     listFiles(dirPath?: string, version?: string): Promise<FileEntry[]>;
-    /** Remote status: identity plus the current head snapshot. */
+    /** Remote status: identity plus the current native version. */
     status(): Promise<FilesystemStatus>;
     /** Mount this filesystem to a local path (requires the `tl` CLI). */
     mount(localPath: string, readonly?: boolean): Promise<FilesystemMount>;
@@ -1764,4 +1844,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemStatus, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type Snapshot, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };
+export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemFileRead, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemReadOptions, type FilesystemSnapshot, type FilesystemSnapshotInfo, type FilesystemStatus, type FilesystemVersion, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };