OXYGENHUB

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