Spec 5.1: flow-casfs serves text files as renderings cached by graph key (refs #21) 701dcbc5d468
- Author
- Andy McCall @andymccall <[email protected]>
- When
- · 2026-10-01 01:40 UTC
- Signature
- ✔ signed by Andy McCall
- Hash
701dcbc5d4688324d95fadf4968fdfad31d119e5bb516213e2485492b28f02cf- Depends on
- a083cc802892
- Depended on by
- nothing yet
- In bookmarks
- main newer-pipeline push-uses-login
- In tags
- v0.2.0 v0.3.0 v0.3.1 v0.4.0 v0.5.0 v0.5.1 v0.5.2 v0.5.3
- Edits
- 2 atoms, 0 tree operations, 1 file
Browse the tree at this change
modified docs/spec.md +26 −9
| … | 192 unchanged lines |
||
| 193 | 193 | ### 5.1 FUSE Overlay Mounting (flow-casfs) |
|
| 194 | 194 | 1. The runner receives a task targeting an Oxygen State ObjectRef (a sorted |
|
| 195 | 195 | list of maximal heads). |
|
| 196 | - | 2. The nearest Checkpoint is resolved. Uncommitted changes between the |
|
| 197 | - | checkpoint and heads are replayed into a virtual tree in-memory. |
|
| 198 | - | 3. The virtual tree is exposed to the sandbox via flow-casfs: |
|
| 199 | - | - File reads resolve chunks using the FastCDC gear table (32 KiB to 256 KiB, |
|
| 200 | - | mean 64 KiB) pinned in Oxygen Spec Section 13.2. |
|
| 201 | - | - Missing chunks are fetched lazily using the POST /objects protocol. |
|
| 202 | - | - To prevent FUSE context-switch bottlenecks on many small reads, flow-casfs aggressively mmaps chunk data and utilizes host page caching. |
|
| 203 | - | - All guest mutations are diverted to a scratch tmpfs layer; base objects |
|
| 204 | - | remain immutable. |
|
| 196 | + | 2. The state's tree is read from a state index (Oxygen's flat, checksummed |
|
| 197 | + | description of a history-only state: its changes, tree view and each |
|
| 198 | + | file's deferred history with its graph key), built once from the |
|
| 199 | + | nearest checkpoint plus the changes after it and kept beside the store. |
|
| 200 | + | Listing a directory needs nothing else. |
|
| 201 | + | 3. The tree is exposed to the sandbox read-only through flow-casfs (FUSE): |
|
| 202 | + | - An opaque file's bytes are its stored blob, whose chunks (FastCDC, |
|
| 203 | + | 32 KiB to 256 KiB, mean 64 KiB, Oxygen spec Section 13.2) are read as |
|
| 204 | + | they are needed. |
|
| 205 | + | - A text file's bytes are a rendering of its history, not a stored blob. |
|
| 206 | + | Renderings are cached by **graph key** (equal keys mean equal |
|
| 207 | + | renderings) as ordinary Blob and Chunk objects: a file is rendered on |
|
| 208 | + | first read or stat, and every later state in which it has the same |
|
| 209 | + | history finds it at once. A file added once and never edited is its |
|
| 210 | + | own text blob and needs no rendering at all. |
|
| 211 | + | - Missing objects are fetched lazily using the POST /objects protocol. |
|
| 212 | + | - To prevent FUSE context-switch bottlenecks on many small reads, |
|
| 213 | + | flow-casfs caches whole small files and mmaps chunk data, relying on |
|
| 214 | + | the host page cache. |
|
| 215 | + | - All guest mutations are diverted to an overlay on the job's ephemeral |
|
| 216 | + | disk (or a tmpfs); base objects remain immutable. |
|
| 217 | + | 4. The same mount backs web workspaces (OxygenHub spec 13.3): a |
|
| 218 | + | `workspace` job keeps it for as long as its editor is open. |
|
| 219 | + | 5. Targets, measured on the Linux tip: mount under 100 ms, a first read of |
|
| 220 | + | a file in milliseconds, and a full read of the tree no slower than a |
|
| 221 | + | checkout writing it. |
|
| 205 | 222 | ||
| 206 | 223 | ### 5.2 Artifact Capture |
|
| 207 | 224 | 1. At task completion, flow-casfs scans the paths declared in the output block. |
|
| … | 199 unchanged lines |