Paths, objects, and rendered views

Paths are the public interface. Objects and rendered views are how providers make those paths coherent.

The user asks for a path:

cat /omnifs/linear/teams/ENG/issues/open/ENG-1421/title

The host strips the mount prefix, chooses the linear mount, and sends the provider path:

/teams/ENG/issues/open/ENG-1421/title

The provider router matches literal segments and typed captures. Literal prefixes auto-navigate so provider authors do not need to write empty handlers for every intermediate directory. If a capture parser rejects a segment, that route is not a candidate. This lets a provider express useful path shapes without writing manual validation at every handler.

Lookup, list, read

Filesystem tools do not only call read-file. A normal cat path may trigger several lookups before the final read. A normal ls may ask whether one child exists, then ask for a directory listing.

The provider contract supports this shape:

• lookup-child: resolve one child name below a parent path.
• list-children: list a directory, optionally with a cursor and cached validator.
• read-file: read a complete file response.
• open-file, read-chunk, close-file: read ranged or streamed files.

Those operations return a provider step. The step is either suspended with host-run callouts or returned with the final result and effects.

Directories can be partial

A listing can be exhaustive or open. Exhaustive means the provider is saying “these are the names I know here.” Open means a later lookup may resolve a name that was not listed.

That matters for API-backed systems. A provider may list the first page of issues but still allow lookup of a specific issue number. The host should not turn a non-exhaustive list into a permanent not-found answer.

Objects and leaves

Many provider paths are object-shaped. A GitHub issue is one object. Its title, body, state, comments directory, JSON representation, and Markdown representation are leaves derived from that object.

The provider declares the object identity and renderable leaves. The host stores canonical bytes and rendered filesystem records. This split is what lets a later read of title or item.json come from cached canonical bytes without another upstream fetch.

Rendered views

The object cache stores canonical upstream bytes under a logical id. The view cache stores rendered filesystem records: files, directories, attributes, content types, and dirents. A view record can be rebuilt from canonical bytes when the provider knows how to render that object locally.

The cache split matters because rendered paths are not the source of truth. They are derived views over canonical bytes.

Provider contract

This page explains the path and object model. Provider contract covers the WIT operation surface. For exact path schemes, use Path schemes.