docs: describe the shipped symbolic-link surface

The filesystem specification said symbolic links were an internal
primitive, that Workspace.fs exposed neither symlink nor readlink,
that there was no lstat, and that an existing file's mode could not be
changed. The shipped API contradicts all four: WorkspaceFilesystem
exposes symlink, readlink, lstat, and chmod, the stub mirrors them
across the Workers RPC boundary, and the Dynamic Worker filesystem
adapters rely on them for the node:fs behaviour a shell expects.
Removing the methods would be a breaking change and would leave those
adapters without a way to serve ln -s, readlink, or test -L, so the
document follows the code.

Each of the four methods gains a section with its return value and its
errors, the comparison with node:fs/promises maps them rather than
striking them out, and the note on symbolic links now states the two
rules that cover the surface: intermediate segments are always
followed, and a trailing link is followed by everything except lstat
and readlink. The rename and find entries added alongside are
documented in the same pass.

Closes #118.

Author: agent

.changeset/document-symlink-surface.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": patch
+---
+
+Document the symbolic-link filesystem surface. `docs/04_filesystem_interface.md` claimed that symbolic links were internal and that `Workspace.fs` had no `symlink`, `readlink`, `lstat`, or `chmod`, none of which matched the shipped API. Those four methods now have sections of their own covering return values and the `ENOENT`, `EINVAL`, and `ELOOP` cases, the comparison with `node:fs/promises` maps them, and the specification explains that `stat` follows a trailing link while `lstat` reports the link itself.

docs/04_filesystem_interface.md

@@ -190,8 +190,10 @@ stat(path: string): Promise<{
 `name` is the last segment of the canonicalized path. For the workspace
 root this is the empty string: `(await fs.stat("/")).name === ""`.
 
-`stat` follows symlinks transparently; there is no `lstat`. See the
-note on internal symlink support in the appendix.
+`stat` follows a trailing symbolic link, so it reports the file or
+directory the link points at. Use [`lstat`](#lstat) to inspect the link
+itself. A dangling link makes `stat` report `ENOENT` while `lstat`
+succeeds.
 
 > When a parent path segment is itself a file, `stat` reports `ENOENT`
 > (because resolution returns `null` for that case) rather than
@@ -203,6 +205,117 @@ const s = await fs.stat("/workspace/build/out.wasm");
 console.log(`${s.size} bytes, modified ${new Date(s.mtime).toISOString()}`);
 ```
 
+### `lstat`
+
+```ts
+lstat(path: string): Promise<{
+  name:            string;
+  mode:            number;
+  mtime:           number;   // ms since epoch
+  size:            number;
+  isFile:          boolean;
+  isDirectory:     boolean;
+  isSymbolicLink:  boolean;
+}>
+```
+
+Same shape as `stat`, but a trailing symbolic link is reported as the
+link rather than followed. `size` is then the byte length of the stored
+target string, and `isSymbolicLink` is true. Intermediate segments are
+still followed, so a link in the middle of the path resolves as usual.
+Throws `ENOENT` when the path does not exist and `ELOOP` when an
+intermediate chain exceeds 40 hops.
+
+```ts
+await fs.symlink("/workspace/real.txt", "/workspace/alias.txt");
+(await fs.stat("/workspace/alias.txt")).isSymbolicLink;   // false
+(await fs.lstat("/workspace/alias.txt")).isSymbolicLink;  // true
+```
+
+### `symlink`
+
+```ts
+symlink(target: string, path: string): Promise<void>
+```
+
+Creates a symbolic link at `path` pointing at `target`, with the
+argument order of `node:fs/promises`. The target is stored verbatim: it
+may be absolute or relative, and it is allowed to dangle. Reads and
+writes that walk through the link follow it, with the same 40-hop cap as
+every other resolution.
+
+Throws `EEXIST` when `path` already exists (the link is never replaced
+silently), `ENOENT` when the parent directory is missing, `ENOTDIR` when
+a parent segment is a file, and `EROFS` under a read-only mount.
+
+```ts
+await fs.symlink("../shared/config.json", "/workspace/app/config.json");
+```
+
+### `readlink`
+
+```ts
+readlink(path: string): Promise<string>
+```
+
+Returns the stored target of a symbolic link, exactly as it was
+written — relative targets are not resolved. Throws `EINVAL` when `path`
+is not a symbolic link and `ENOENT` when it does not exist.
+
+```ts
+await fs.readlink("/workspace/app/config.json"); // "../shared/config.json"
+```
+
+### `chmod`
+
+```ts
+chmod(path: string, mode: number): Promise<void>
+```
+
+Changes the permission bits of an existing path without rewriting its
+bytes. The mode is masked to twelve bits. Like POSIX `chmod`, a trailing
+symbolic link is followed, so the change lands on the target rather than
+the link. Throws `ENOENT` for a missing path and `EROFS` under a
+read-only mount.
+
+```ts
+await fs.chmod("/workspace/bin/run.sh", 0o755);
+```
+
+### `rename`
+
+```ts
+rename(oldPath: string, newPath: string): Promise<void>
+```
+
+Moves a file, directory, or symbolic link in a single transaction, so an
+interrupted call can never leave the entry at both paths or a directory
+partly copied. The moved entry keeps its inode, its bytes, and its mode;
+a directory move carries its whole subtree.
+
+Overwrite behavior follows POSIX `rename(2)`: an existing destination is
+replaced when the two ends agree on kind. A file or symbolic link
+replaces a file or symbolic link, and a directory replaces an *empty*
+directory. Nothing else is replaced.
+
+| Code | When |
+| --- | --- |
+| `ENOENT` | `oldPath` does not exist, or `newPath`'s parent directory is missing. |
+| `ENOTEMPTY` | `newPath` is a directory with children. |
+| `EISDIR` | `newPath` is a directory and `oldPath` is not. |
+| `ENOTDIR` | `oldPath` is a directory and `newPath` is not. |
+| `EINVAL` | Either end is the root, or a directory would be moved inside itself. |
+| `EROFS` | Either end falls under a read-only mount. |
+
+```ts
+// Publish a build atomically.
+await fs.writeFile("/workspace/site/index.html.tmp", html);
+await fs.rename("/workspace/site/index.html.tmp", "/workspace/site/index.html");
+
+// Move a whole tree.
+await fs.rename("/workspace/draft", "/workspace/published");
+```
+
 ### `find`
 
 ```ts
@@ -212,6 +325,7 @@ find(
   options?: {
     limit?: number;
     offset?: number;
+    exclude?: string[];
   },
 ): Promise<Array<{ path; type: "file" | "dir" }>>
 ```
@@ -225,12 +339,24 @@ its absolute path — so `**/*.ts` under `/workspace/src` matches
 The glob supports `*`, `**`, `**/`, and `?`. Character classes and
 brace expansions are matched literally.
 
+`exclude` takes globs of the same shape, matched against the same
+relative path. An exclusion is decided before the inclusion glob, so it
+always wins. When an excluded entry is a directory the walk prunes it:
+neither the directory nor anything beneath it is read, which is what
+makes skipping `node_modules` or `.git` cheap rather than merely quiet.
+`limit` and `offset` then paginate whatever survives.
+
 ```ts
 // Every TypeScript file in the project.
 const ts = await fs.find("/workspace/src", "**/*.ts");
 
 // Everything under a directory (no pattern).
 const all = await fs.find("/workspace/notes");
+
+// Skip generated trees without descending into them.
+const sources = await fs.find("/workspace", "**/*.ts", {
+  exclude: ["node_modules", "node_modules/**", ".git", ".git/**"],
+});
 ```
 
 ### `ls`
@@ -321,12 +447,12 @@ so handlers from Node code port over directly.
 | Code | When |
 | --- | --- |
 | `ENOENT` | Path does not exist and `force` is not true. Also raised by `stat` when a parent segment turns out to be a file. |
-| `ENOTEMPTY` | Path is a non-empty directory and `recursive` is not true. |
-| `ENOTDIR` | A parent path segment is a file (raised explicitly by `mkdir` and `writeFile`; `find` raises it when its `directory` argument is a file). |
-| `EISDIR` | Expected a file, got a directory (e.g. `readFile` on a dir, `writeFile` on `/`). |
-| `EEXIST` | `mkdir` without `recursive: true` on an existing path. |
-| `EINVAL` | Invalid path or unsupported options. |
-| `ELOOP` | Symlink traversal exceeded 40 hops. Thrown by the internal resolver when the `node:vfs` adapter wires up a cycle. |
+| `ENOTEMPTY` | Path is a non-empty directory and `recursive` is not true. Also raised by `rename` when the destination directory has children. |
+| `ENOTDIR` | A parent path segment is a file (raised explicitly by `mkdir` and `writeFile`; `find` raises it when its `directory` argument is a file; `rename` raises it when a directory would replace a non-directory). |
+| `EISDIR` | Expected a file, got a directory (e.g. `readFile` on a dir, `writeFile` on `/`, `rename` of a file onto a directory). |
+| `EEXIST` | `mkdir` without `recursive: true` on an existing path, or `symlink` onto an existing path. |
+| `EINVAL` | Invalid path or unsupported options: `readlink` on something that is not a symbolic link, `rename` of the root or of a directory into itself. |
+| `ELOOP` | Symbolic-link traversal exceeded 40 hops. Every path-walking method shares that budget, so a cycle surfaces from `stat`, `readFile`, `writeFile`, `mkdir`, and the rest alike. |
 | `EPERM` | Operation is forbidden, e.g. deleting the workspace root. |
 | `EIO` | Backing storage failed unexpectedly. |
 | `EACCES` | *Reserved for future mount layer (see [06. Mount Interface](./06_mount_interface.md)).* No code path in `workspace-fs` currently throws it. |
@@ -379,28 +505,35 @@ maps to `Workspace.fs`:
 | `rm` | `rm` | `{ recursive: true }` for non-empty dirs. |
 | `unlink` | `rm` | Same. |
 | `readdir` | `readdir` | Always returns dirent-shaped entries. |
-| `stat` / `lstat` | `stat` | No `lstat`; `stat` follows symlinks. See note below. |
+| `stat` / `lstat` | `stat` / `lstat` | `stat` follows a trailing symbolic link; `lstat` reports the link. |
 | `truncate` | — | Read, slice, write. |
-| `chmod` | — | Pass `mode` to `writeFile` / `mkdir` at create time. There is no way to chmod an existing file without rewriting its bytes. |
+| `chmod` | `chmod` | Mode masked to twelve bits; follows a trailing symbolic link. `mode` can also be passed to `writeFile` / `mkdir` at create time. |
 | `chown` | — | No ownership model. |
 | `utimes` | — | `mtime` is managed by the VFS. |
 | `cp` / `copyFile` | — | Read + write. |
-| `rename` | — | Read + write + delete. |
+| `rename` | `rename` | One transaction; replaces a destination of the same kind. |
 | `realpath` | — | Paths are already canonical. |
-| `symlink` / `readlink` | — | Not on the public surface; see note below. |
+| `symlink` / `readlink` | `symlink` / `readlink` | Same argument order as Node. Targets are stored verbatim and may dangle. |
 | `watch` | — | Low-level primitive in `fs/watch.ts` (`createWatcher`, `createWatchAsyncIterable`, `WatchHandle`, `WatchOptions`); not exposed on the `WorkspaceFilesystem` class. |
 | `open` / `FileHandle` | — | Use streams instead. |
-| `glob` | `find` | Limited glob support (`*`, `**`, `**/`, and `?`). |
+| `glob` | `find` | Limited glob support (`*`, `**`, `**/`, and `?`), plus `exclude` for pruning subtrees. |
 | — | `grep` | Not in `node:fs`; literal by default, with optional regular expressions. |
 | — | `find` | Recursive directory walk with an optional glob, relative-rooted. |
 | — | `ls` | Flat list of file paths under a directory (segment-aware). |
 
-### Note: symlinks
-
-Symlinks exist as an **internal primitive** used by the `node:vfs`
-adapter — the schema supports a `'symlink'` node type with a
-`link_target`, and the resolver in `fs/resolve.ts` follows them with a
-40-hop cap (throws `ELOOP` on overflow). They are **not** part of the
-public `WorkspaceFilesystem` surface: there are no `fs.symlink` or
-`fs.readlink` methods on `Workspace.fs`, and callers should treat all
-visible paths as if they pointed straight at real files.
+### Note: symbolic links
+
+Symbolic links are part of the public surface. The schema carries a
+`'symlink'` node type with a `link_target`, the resolver in
+`fs/resolve.ts` follows them with a 40-hop cap (throws `ELOOP` on
+overflow), and `Workspace.fs` exposes `symlink`, `readlink`, and
+`lstat` on top of that. `WorkspaceFilesystemStub` mirrors all three
+across the Workers RPC boundary, which is how the Dynamic Worker
+filesystem adapters provide the `node:fs` behavior a shell expects from
+`ln -s`, `readlink`, and `test -L`.
+
+Two rules cover the whole surface. Intermediate segments are always
+followed, so a link to a directory behaves like the directory for every
+method, `mkdir` included. A trailing link is followed by everything
+except `lstat` and `readlink`, which are the two methods whose purpose
+is to describe the link itself.