Callouts and effects

Providers do not perform ambient I/O. They request host work through callouts and return host mutations as effects.

Callout flow

1. The host calls a provider operation.
2. The provider returns suspended(list<callout>).
3. The host checks capabilities and executes the callouts.
4. The host calls resume with callout results.
5. The provider returns the final result and effects.

Callouts are request/response. There are no fire-and-forget callouts and no trailing callouts on a returned provider result.

Callout types

Callout	Use
fetch	HTTP request whose response body crosses WIT.
git-open-repo	Open a Git repository and return a host tree handle.
fetch-blob	Fetch large bytes into the host blob cache.
open-archive	Mount a stored blob as an archive tree.
read-blob	Bring a bounded range of blob bytes into the provider.

Effects

Effects are committed at the return boundary.

Effect	Use
canonical	Store raw upstream object bytes under a logical id.
fs	Write derived files or directories into the view cache.
invalidations	Evict cached objects or listings.

Use canonical effects when a provider has loaded an object that can render several leaves. Use fs effects for materialized files and directories. Use invalidations when an event or operation proves cached data is stale.

Authority boundary

The provider asks for an HTTP fetch, Git handoff, blob read, archive open, or cache write. The host checks and performs it. That is the core provider-authoring rule.