Address perf bottleneck running npm install

README.md

@@ -60,6 +60,85 @@ package-specific status and usage notes.
   (`@cloudflare/workspace`) — the top-level Workspace package
   consumed by Durable Objects. Work in progress.
 
+## Performance
+
+Numbers from `script/fs-bench.sh` and a full
+`npm install` of [`cloudflare/sandbox-sdk`](https://github.com/cloudflare/sandbox-sdk)
+(854 packages, 36,675 files), running
+[`examples/wsd-container`](examples/wsd-container) on a Cloudflare
+Containers **standard-2** instance (1 vCPU, 6 GiB memory, 12 GB disk).
+The wsd FUSE mount lives at `/workspace`; the comparison columns are
+an in-memory `tmpfs` at `/tmp` and the container's ext4 root disk at
+`/var/tmp`.
+
+Ratios are `wsd / baseline` — lower is faster, values below 1.0 mean
+wsd beats the baseline.
+
+### `fs-bench` (REPS=3, WARMUP=1, randomized targets)
+
+| Scenario | wsd | tmpfs | tmpfs ratio | ext4 disk | disk ratio |
+|---|---:|---:|---:|---:|---:|
+| **tiny-file churn** | | | | | |
+| create 1000 files | 560.6 ms | 83.2 ms | 6.7x | 303.2 ms | 1.85x |
+| stat 1000 files | 1971.9 ms | 1324.2 ms | 1.49x | 2659.3 ms | **0.91x** |
+| rm 1000 files | 827.7 ms | 322.7 ms | 2.56x | 1281.8 ms | **0.66x** |
+| **directory traversal** | | | | | |
+| mkdir tree (10×10×10) | 1597.5 ms | 1585.7 ms | 1.01x | 3034.7 ms | **0.74x** |
+| find tree | 1813.6 ms | 1819.9 ms | 1.00x | 4404.2 ms | **0.72x** |
+| **large file I/O** | | | | | |
+| write 64 MiB | 230.6 ms | 47.3 ms | 4.87x | 16.8 ms | 16.93x |
+| copy 64 MiB | 1037.2 ms | 37.4 ms | 27.75x | 39.8 ms | 40.46x |
+| read 64 MiB | 437.5 ms | 22.6 ms | 19.33x | 25.6 ms | 39.72x |
+| pure read 64 MiB | 263.1 ms | 8.3 ms | 31.54x | 8.5 ms | 30.26x |
+| pure copy 64 MiB | 852.9 ms | 21.7 ms | 39.27x | 22.0 ms | 41.47x |
+| overwrite 64 MiB | 272.6 ms | 8.3 ms | 32.91x | 8.5 ms | 43.35x |
+| **git** | | | | | |
+| git init + commit 100 files | 459.2 ms | 40.3 ms | 9.56x | 635.4 ms | **0.72x** |
+| git clone (shallow, ~1MB) | 549.1 ms | 421.0 ms | 1.30x | 576.2 ms | **0.84x** |
+| **npm** | | | | | |
+| npm init + tiny install | 598.5 ms | 630.7 ms | **0.95x** | 630.7 ms | **0.95x** |
+
+### Full `cloudflare/sandbox-sdk` `npm install`
+
+| Target | Duration |
+|---|---:|
+| tmpfs (`/tmp`) | 34.3 s |
+| wsd FUSE (`/workspace`) | 124.7 s |
+| ext4 disk (`/var/tmp`) | 63.9 s |
+
+wsd is ~2x slower than the container's ext4 disk for the full
+`npm install`, and ~3.6x slower than tmpfs. The disk comparison is
+the more realistic baseline for general usage.
+
+### Where wsd is faster than the disk baseline
+
+The in-memory inode store beats real disk on metadata-heavy work:
+`stat`, `rm`, `mkdir tree`, `find tree`, `git init`, `git clone`,
+`npm init`. Those eight scenarios cover most of the day-to-day cost
+of tools like `git status`, module resolution, and incremental
+builds.
+
+### Where wsd is slower
+
+Large sequential file I/O. The wsd write path hashes each
+[`CHUNK_SIZE`](packages/dofs/src/fs/writeFile.ts) (512 KiB) chunk
+into a content-addressed blob store on every release; that's how
+the Durable Object can sync only the chunks that changed and
+deduplicate identical content. The cost lands on raw
+`dd`-style throughput numbers but rarely on real developer
+workloads, which is why `npm init + tiny install` matches the disk
+baseline despite `pure read 64 MiB` being 30x slower.
+
+### Reproducing
+
+```bash
+bash script/run-fs-bench.sh
+```
+
+or against a deployed `wsd-container` instance, upload
+[`script/fs-bench.sh`](script/fs-bench.sh) and run it with
+`MOUNT=/workspace BASE=/tmp`.
+
 ## Documentation
 
 - [`docs/`](docs/README.md) — design specification. Forward-looking;

docs/03_filesystem_schema.md

@@ -52,7 +52,8 @@ CREATE TABLE vfs_nodes (
   mount_root    TEXT,                                -- nullable; tags mount provenance
   stub_size     INTEGER,                             -- non-null while a lazy stub
   manifest_hash BLOB,                                -- references vfs_manifests.hash
-  link_target   TEXT                                 -- non-null when type = 'symlink'
+  link_target   TEXT,                                -- non-null when type = 'symlink'
+  size          INTEGER NOT NULL DEFAULT 0           -- cached file size, kept in sync on writes
 );
 CREATE INDEX vfs_nodes_by_rev ON vfs_nodes(rev);
 ```
@@ -61,7 +62,11 @@ One row per live inode. `mount_root` records the mount this row
 originated from, used for write-rejection and writable-mount mirroring.
 `stub_size` is non-null while the file is a lazy-mount stub whose
 bytes haven't been fetched yet — `stat()` reports it as the file size
-and the first read fetches the bytes.
+and the first read fetches the bytes. `size` denormalises the
+chunk-sum file size onto the node row so `stat`, `lstat`, and the
+positional read primitive can read it directly instead of running
+`SUM(size) FROM vfs_chunks` on every call. Every write path stamps
+it alongside `mode`/`mtime`/`rev`.
 
 The `vfs_nodes_by_rev` index supports `coalesceChanges`'s
 `WHERE rev > sinceRev` scan over live inodes, which the sync protocol
@@ -233,10 +238,23 @@ DO reload doesn't re-list.
 
 - The root directory is always `inode = 1`, type `dir`, with no
   parent dirent.
-- A `vfs_nodes` row with `type = 'file'` has either:
-  - `stub_size NOT NULL` and no `vfs_chunks` rows (lazy stub), **or**
-  - `manifest_hash NOT NULL`, a matching `vfs_manifests` row, and
-    one `vfs_chunks` row per chunk.
+- A `vfs_nodes` row with `type = 'file'` is in one of two shapes:
+  - **lazy stub**: `stub_size NOT NULL`, no `vfs_chunks` rows. The
+    first read fetches the bytes and migrates the row to the
+    committed shape.
+  - **committed file**: zero or more `vfs_chunks` rows (one per
+    chunk; an empty file has zero). `manifest_hash` is optional.
+    When set, a matching `vfs_manifests` row lists the same chunk
+    hashes and lets sync skip the per-chunk fetch on receivers
+    that already have the manifest. When `NULL`, sync walks
+    `vfs_chunks` directly. The buffered-write path commits chunks
+    with `manifest_hash = NULL`; the legacy whole-file
+    `writeFileSync` path stamps a manifest.
+- For every file row, `vfs_nodes.size = COALESCE(SUM(vfs_chunks.size), 0)`
+  over its `vfs_chunks` rows. Every write path stamps the column
+  in the same `UPDATE` that bumps `mode`/`mtime`/`rev`, so `stat`,
+  `lstat`, and `readRangeSync` can read it directly instead of
+  running the aggregate.
 - Every `vfs_chunks.hash` references an existing `vfs_blobs.hash`.
 - Every `vfs_blobs.hash` has a matching `vfs_blob_bytes` row.
 - Every `vfs_manifests.hash` referenced by