docs: record the vfs fallback work

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

AI_CHANGES.md

@@ -138,3 +138,4 @@ The test suite for `packages/http` was mostly generated by Claude Code, which al
 - **`@webnet/taildrive` — peer-probe review hardening**: `gpt-5.6-sol` addressed autonomous review findings by covering the IPN dial phase with the probe deadline, closing a connection that arrives after timeout, and requiring a valid root-directory response before accepting a nonempty WebDAV listing. Regression coverage includes a permanently stalled dial and a malformed 207 response that omits the requested root.
 - **`@webnet/taildrive` — discovery API review follow-up**: `gpt-5.6-sol` renamed the narrower discovery helper to `listDrivePeersWithShares` to distinguish it from `IpnClient.listDrivePeers`, and added the conventional package-root export alongside the existing client and server subpaths.
 - **`@webnet/vfs` — combined stat and directory listing**: `gpt-5.6-sol` added the optional `AsyncVFS.statAndReaddir()` operation, with optimized Memory, File System Access, WebDAV, and SMB2 implementations. Drive PROPFIND/COPY/MOVE and delete handling, FTP server listings, SMB2 recursive operations, and Taildrive peer discovery reuse combined metadata where available while retaining inline fallbacks for other VFS implementations. Conformance, browser, protocol, malformed-response, request-count, and integration coverage preserve existing `readdir()` semantics and verify files return their own stat with no entries. A Claude Opus 5 review found that SMB recursive deletion could accidentally request read-data access on files and identified implicit listing/native-copy contracts; `gpt-5.6-sol` fixed the access regression, aligned DAV self-resource validation, documented the contracts, and added request-level and conformance coverage. Fresh `gpt-5.6-terra` reviews then caught missing-source COPY/MOVE deleting an overwrite destination in the Drive fallback and native Node, Memory, and SFTP paths; `gpt-5.6-sol` reordered fallback handling, made each native operation source-safe, and added data-preservation regressions. A final Claude Opus 5 pass confirmed the fixes and prompted documentation that successful overwrites replace rather than merge directory destinations until #137 introduces explicit policies.
+- **`@webnet/vfs` — unsupported error code and optional-operation fallbacks (issue #82)**: Claude Code (Claude Opus 5) added the `unsupported` `VFSErrorCode` and a `@webnet/vfs/fallback` entry point. The code is documented as a capability failure, distinct from `forbidden` (permitted but denied), `precondition-failed` (state prevents it) and a backend or transport failure, and carries the requirement that rejecting with it leaves the filesystem unchanged — which is what makes answering it by doing the work another way safe. Optional `AsyncVFS` members are correspondingly documented as absent when an implementation can never perform the operation and present-but-rejecting when it can for some paths and not others, so a backend spanning several shares, servers or negotiated dialects can say so per call rather than per instance. Each protocol adapter maps the code both ways: SFTP `SSH_FX_OP_UNSUPPORTED`, FTP 502 and WebDAV 501 outbound, and the same statuses plus SMB2 `STATUS_NOT_SUPPORTED` inbound — the SMB2 status previously reached callers as `forbidden`, claiming a permission problem the server never reported, and the WebDAV and FTP clients discarded their own servers' 501/502 entirely. `withFallbacks(vfs, options)` returns a `Required<AsyncVFS>` so a consumer can call any optional operation without branching on method presence; `statAndReaddirFallback`, `readFileRangeFallback`, `copyFallback`, `moveFallback` and `setPropsFallback` are also exported individually for call sites that need one operation without wrapping the filesystem they were handed. A per-operation policy chooses when a fallback may stand in (`native-only`, `on-missing`, `on-unsupported`), and only an `unsupported` rejection of the returned promise ever triggers one: any other code, a non-`VFSError`, or a stream that errors after bytes have been delivered propagates untouched, so a permission, state or transport failure is never retried into a partial success. `setProps` has no fallback, because arbitrary property storage cannot be built from the required operations, and says `unsupported` rather than appearing absent. The copy fallback rejects overlapping source and destination paths in both directions — a destination inside the source never terminates, and a source inside the destination would be deleted by the overwrite step before being read — reuses the complete metadata `readdir` guarantees rather than restatting each child, recurses sequentially so a wide tree does not open one transfer per entry, removes a partial destination on failure, and is documented as neither transactional nor atomic. The range fallback windows `readFile` lazily, holds at most one chunk, and cancels the source as soon as the window is satisfied, so serving a short range of a large file does not read the whole thing. The three byte-identical copies of the `statAndReaddir` fallback that arrived with #172 were replaced by the shared one. The conformance suite's optional-method capabilities became tri-state so a runtime `unsupported` rejection is itself testable, including that nothing changed, and the fallbacks are exercised by running the whole suite against a `MemoryVFS` with its optional operations first removed and then rejecting. Pinning `readFileRange`'s boundary behaviour — a start at or past the end of a file, and an end below the start, yield an empty stream rather than an error — surfaced three genuine bugs, all fixed rather than excused by a capability opt-out: `NodeVFS` passed an inverted range straight to `createReadStream`, which throws a raw `ERR_OUT_OF_RANGE`; the WebDAV client reported the 416 that RFC 9110 requires for a range at or past the end of a representation as an unexpected status; and the FTP client, whose `REST` carries no end bound, transferred from the start to the end of the file instead of nothing.