harmonia-file-* crates: async file tree traits, NAR via traits, cap-tokio

Introduces three new crates implementing a generic async file tree
abstraction mirroring nix's `SourceAccessor` / `FileSystemObjectSink`
architecture (NixOS/nix#15392):

**`harmonia-file-core`**: Generic types (`FileTree`, `FileSystemObject`),
async traits (`FileSystemSource`, `FileSystemSink`, `DirectorySink`,
`RegularFileSink`), in-memory implementation, listing functions, and
serde matching `nix nar ls --json`.

**`harmonia-file-fd`**: Filesystem `FileSystemSource` (`DirSource`) and
`FileSystemSink` (`DirSlotSink`) via `cap-tokio`. Uses `openat`/`fstatat`,
mmap for large files. Lazy child thunks — directory handles opened on demand.

**`harmonia-file-nar`** (renamed from `harmonia-nar`): NAR dump/restore
now goes through `FileSystemSource`/`FileSystemSink` traits via
`dump_source` and `restore_to_sink`. The old `walkdir`-based `NarDumper`
and direct-IO `NarRestorer` are replaced. `parse_nar_listing` produces
`FileTree<NarFileInfo>` from NAR streams.

Other changes:
- `harmonia-cache/narlist.rs` uses `DirSource` + `list_deep` (async,
  no `spawn_blocking`)
- All harmonia workspace deps use `{ workspace = true }`
- Dependency diagram groups `file-*` crates, shows isolated nodes
- Architecture docs updated
- Uses `cap-tokio` (bytecodealliance/cap-std#414) for async
  capability-based filesystem access

Author: Ericson2314

Cargo.lock

@@ -13,6 +13,7 @@ members = [
     "harmonia-store-remote",
     "harmonia-store-aterm",
     "harmonia-file-core",
+    "harmonia-file-fd",
     "harmonia-file-nar",
     "harmonia-protocol",
     "harmonia-protocol-derive",
@@ -38,8 +39,11 @@ version = "3.1.0"
 
 [workspace.dependencies]
 async-stream = "0.3"
-bstr = "1.11"
-bytes = "1.11"
+bstr         = "1.11"
+bytes        = "1.11"
+cap-std      = "3"
+# https://github.com/bytecodealliance/cap-std/pull/414
+cap-tokio = { git = "https://github.com/Ericson2314/cap-std.git", branch = "cap-tokio" }
 data-encoding = "2.11"
 derive_more = { version = "2.1", features = [ "display" ] }
 ed25519-dalek = "2"
@@ -92,6 +96,7 @@ tokio-test      = "0.4"
 
 # Internal crates
 harmonia-file-core           = { path = "harmonia-file-core" }
+harmonia-file-fd             = { path = "harmonia-file-fd" }
 harmonia-file-nar            = { path = "harmonia-file-nar" }
 harmonia-protocol            = { path = "harmonia-protocol" }
 harmonia-protocol-derive     = { path = "harmonia-protocol-derive" }

Cargo.toml

@@ -22,8 +22,8 @@ composed.
 ┌────────────────────────────┬─────────────────────────┐
 │  Format / File             │  Database               │
 │  harmonia-file-nar         │  harmonia-store-db      │
-│  harmonia-file-core        │                         │
-│  NAR pack/unpack, types    │  SQLite store metadata  │
+│  harmonia-file-core/fd     │                         │
+│  NAR pack/unpack, file I/O │  SQLite store metadata  │
 └────────────────────────────┴─────────────────────────┘
                          ↓
 ┌──────────────────────────────────────────────────────┐
@@ -49,7 +49,8 @@ composed.
 | [harmonia-store-aterm](../../harmonia-store-aterm/) | ATerm derivation parser |
 | [harmonia-store-path-info](../../harmonia-store-path-info/) | ValidPathInfo types (pure) |
 | [harmonia-store-db](../../harmonia-store-db/README.md) | SQLite store metadata |
-| [harmonia-file-core](../../harmonia-file-core/) | File tree types and serde (pure) |
+| [harmonia-file-core](../../harmonia-file-core/) | File tree types, traits, listing (pure) |
+| [harmonia-file-fd](../../harmonia-file-fd/) | Filesystem source via cap-std |
 | [harmonia-file-nar](../../harmonia-file-nar/README.md) | NAR archive format |
 | [harmonia-protocol](../../harmonia-protocol/README.md) | Daemon wire protocol |
 | [harmonia-protocol-derive](../../harmonia-protocol-derive/README.md) | Derive macros for protocol types |
@@ -86,14 +87,17 @@ graph BT
     end
     subgraph File
         file-core
+        file-fd
         file-nar
     end
     bench
     client
     ssh-store
+    file-fd --> file-core
+    utils-hash --> utils-base-encoding
     file-nar --> file-core
+    file-nar --> file-fd
     file-nar --> utils-io
-    utils-hash --> utils-base-encoding
     store-core --> utils-base-encoding
     store-core --> utils-hash
     store-aterm --> store-core
@@ -115,6 +119,7 @@ graph BT
     store-nar-info --> store-path-info
     store-nar-info --> utils-hash
     cache --> file-core
+    cache --> file-fd
     cache --> file-nar
     cache --> store-core
     cache --> store-db
@@ -145,14 +150,16 @@ graph BT
     end
     subgraph File
         file-core
+        file-fd
         file-nar
     end
     bench
     client
     ssh-store
-    file-nar --> file-core
-    file-nar --> utils-io
+    file-fd --> file-core
     utils-hash --> utils-base-encoding
+    file-nar --> file-fd
+    file-nar --> utils-io
     store-core --> utils-hash
     store-aterm --> store-core
     store-build-result --> store-core
@@ -190,8 +197,9 @@ intra-workspace dependencies.
 - `harmonia-store-aterm` and `harmonia-store-path-info` would typically be part of `harmonia-store-core`.
   However, since these data types / formats both have issues, they are instead placed in separate libraries to make sure they don't "infect" the rest of `harmonia-store-core`.
 
-**File** (`harmonia-file-core`, `harmonia-file-nar`)
-- `harmonia-file-core`: pure file tree types and serde matching nix's JSON format.
+**File** (`harmonia-file-core`, `harmonia-file-fd`, `harmonia-file-nar`)
+- `harmonia-file-core`: pure file tree types, `FileSystemSource`/`FileSystemSink` traits, serde matching nix's JSON format.
+- `harmonia-file-fd`: real filesystem source via `cap-std` (openat, no symlink following).
 - `harmonia-file-nar`: NAR pack/unpack against generic `AsyncRead`/`AsyncWrite`. Streaming; never requires the full input in memory. Knows nothing about derivations or signatures.
 
 **Database** (`harmonia-store-db`)

docs/architecture/harmonia-store-structure.md

@@ -40,9 +40,11 @@ zstd = "0.13"
 zstd-safe = "7"
 # Nix.rs-based crates
 bytes                    = { workspace = true }
+cap-tokio                = { workspace = true }
 futures-core             = { workspace = true }
 futures-util             = { workspace = true }
 harmonia-file-core       = { workspace = true }
+harmonia-file-fd         = { workspace = true }
 harmonia-file-nar        = { workspace = true }
 harmonia-store-core      = { workspace = true }
 harmonia-store-db        = { workspace = true }