Runtime, cache, and identity

The host runtime is the part of omnifs that owns the operating-system boundary. It mounts FUSE on Linux, loads providers, runs callouts, injects credentials, stores cache records, and maps provider answers back into filesystem behavior.

Read path

For a normal read, the host works in this order:

1. Resolve synthetic mount roots and any real backing paths.
2. Check inode and view-cache state for already materialized filesystem records.
3. Resolve a cached object identity for the path when possible.
4. Call the provider with the path and optional cached canonical bytes.
5. Run any suspended callouts requested by the provider.
6. Commit terminal effects, then return file bytes or directory entries to FUSE.

Subtree handoffs are special. When a provider returns a tree-ref, the host records a real backing path, such as a cloned repository, and later filesystem operations can come from that backing path rather than provider dispatch.

See Subtree handoff for the backing-tree model.

Object cache

The object cache stores canonical upstream bytes under an opaque object identity. It is durable and mount-scoped. The host does not interpret the object. It stores ids, bytes, validators, path aliases, and leaf mappings.

Object identity belongs to provider and SDK code. The host treats it as opaque bytes so it can cache and invalidate without learning GitHub issue semantics, Linear issue semantics, or arXiv paper semantics.

View cache

The view cache stores derived filesystem records: file contents, directory entries, file attributes, and rendered leaves. It is derived from provider results and cached canonical objects. It is recreated on startup.

A rendered view is not the source of truth. If a view record disappears, omnifs can render it again from the object cache or ask the provider to fetch fresh data.

Blob cache

The blob cache stores large host-resident byte streams behind handles. Providers use blob-style responses for content that should not be copied through the provider as one inline byte vector, such as larger fetched files, archives, and ranged content.

Invalidation and freshness

Invalidation is explicit. Provider effects can invalidate an object id, a path, or a prefix. The host also uses generation and tombstone fences so a stale result from before an invalidation cannot write old data back into the cache.

Do not read this as a blanket “no TTLs anywhere.” The object cache is not a TTL cache, but rendered views can carry freshness information from file stability and attributes. The useful distinction is source versus view: canonical object bytes are stored as source material; rendered files are disposable views.

Traceability

omnifs can show what the runtime did for a read through omnifs inspect. This is local observability: operations, callouts, cache hits, provider returns, and errors. It is useful for debugging and for understanding what an agent or script read. It is not a compliance-grade audit log by itself.