Provider contract
A provider is a wasm32-wasip2 component that implements the omnifs:provider@0.4.0 WIT contract. The host calls provider operations. The provider either completes the operation or suspends with callouts for the host to run.
Operation groups
Section titled “Operation groups”The contract is larger than the three browse operations.
| Group | Operations | Purpose |
|---|---|---|
| Lifecycle | initialize, shutdown | Start and stop a provider instance. |
| Namespace | lookup-child, list-children, read-file, open-file, read-chunk, close-file | Resolve directories, files, and ranged reads. |
| Continuation | resume, cancel | Continue or cancel an operation that suspended on host callouts. |
| Notify | on-event | Handle provider events when the provider exports the notify interface. |
Provider steps
Section titled “Provider steps”A namespace operation returns a provider step:
suspended(list<callout>)returned(provider-return)suspended is not a result. It means the host must run the callouts and resume the same operation with matching callout results.
returned is terminal. It carries an operation result and effects. It cannot carry trailing callouts.
Callouts
Section titled “Callouts”Callouts are host-mediated work:
fetchgit-open-repofetch-blobopen-archiveread-blob
Providers do not perform direct network, Git, archive, or blob I/O. They ask for callouts. The host checks capabilities, runs the work, and sends results back through resume.
Effects
Section titled “Effects”Effects are terminal host mutations committed at the return boundary:
| Effect block | Meaning |
|---|---|
canonical | Store canonical upstream bytes under a logical object id. |
fs | Write materialized files or directories into the view cache. |
invalidations | Evict cached objects or listings. |
Effects are the provider-to-host storage channel. They are not background jobs and they are not ambient authority.
Errors
Section titled “Errors”Provider and callout errors use a shared error kind set: not found, not a directory, not a file, permission denied, invalid input, too large, network, timeout, denied, rate limited, version mismatch, and internal.
rate-limited can carry a structured retry-after hint. Do not bury retry policy only in an error string.