The WIT interface

The provider contract lives in crates/omnifs-wit/wit/provider.wit. The SDK generates guest bindings from it and the host calls those exports through Wasmtime.

Operation lifecycle

Provider operations return a provider-step:

variant provider-step {
    suspended(list<callout>),
    returned(provider-return),
}

suspended means the host must run a non-empty batch of callouts and resume the same operation with the matching results. returned means the operation is complete and the host can commit its effects.

Namespace operations

The provider exports namespace operations for filesystem behavior:

• lookup-child
• list-children
• read-file
• open-file
• read-chunk
• close-file

It also exports lifecycle, continuation, and notify operations: initialize and shutdown, resume and cancel, and on-event.

Callouts

Callouts are provider requests for host work. Current callout arms include:

• HTTP fetch,
• git repo open,
• fetch blob,
• open archive,
• read blob.

There are no fire-and-forget callouts. A provider either returns a final answer or suspends and waits for callout results.

Effects

Terminal returns can carry effects:

record effects {
    canonical: list<canonical-store>,
    fs: list<fs-write>,
    invalidations: list<invalidation>,
}

Effects are committed at the return boundary. canonical stores upstream bytes, fs writes materialized view records, and invalidations evict stale cached state.

Byte sources

Small file reads can return inline bytes. Larger or ranged reads use host-managed byte sources such as blobs and streamed file handles. Do not model every file as one eager byte vector; choose the byte source that matches the file.

Where to look

Use this page for the provider-development model. Use WIT interface for the public reference summary, File attributes for file metadata rules, and crates/omnifs-wit/wit/provider.wit for exact record names and field shapes.