Filesystem behavior
The generated reference lists exact names and types. This page explains the behavior expected across different remote services.
Connection and paths
Memona creates one component instance per connection. open receives the
provider ID and that connection’s configuration and returns its capabilities.
The host owns connection IDs; the plugin receives connection-relative paths.
/ is the connection root. Paths use / separators, cannot traverse above the
root and must never be interpreted as local OS paths. File names are returned
as names, not HTML. A listing is paginated with an opaque cursor and a bounded
limit. Do not reuse a cursor across unrelated listing requests.
Read and revisions
stat identifies a file or directory and may return an opaque revision token.
read takes an offset and maximum length and returns bytes, an optional revision
and an end-of-file flag. Use bounded range reads rather than loading an entire
remote file into guest memory. Do not silently truncate data while claiming EOF.
Revision values are provider-defined. They could be a service ETag or an immutable content identifier. Consumers compare them for equality; they must not parse them as timestamps or assume they are ordered.
Write and conflict handling
The initial write operation replaces a complete file within the host’s transfer limit. It is not an append or streaming-write operation. Large-file publishing must not be simulated by repeated calls that accidentally overwrite each other.
The caller chooses one of three conditions:
create-only: fail if the target already exists.if-match(revision): replace only that revision atomically.overwrite: replacement explicitly requested without a revision condition.
Only advertise conditional-write support if the remote service can enforce it.
A read followed by an unconditional write is not an atomic conditional write.
Return unsupported when you cannot honor the requested condition.
If a connection fails after a write or other mutation may have reached the
server, report outcome-unknown. Do not retry automatically: the operation might
already have succeeded. Consumers can inspect the remote state before deciding
what to do next.
Read-only stores return unsupported for mutations. They still implement all exported methods so the component has a predictable shape. Write permission from the user never overrides a provider’s missing capability.
Changes and cleanup
Providers that support change polling advertise that capability. A poll returns a bounded batch and optional cursor; it must finish promptly. The initial API exposes explicit poll calls. A caller retains its cursor and decides when to poll again; there is no automatic watcher subscription in this version.
close releases provider-owned connection state. Timeouts, disable, disconnect,
update or uninstall may terminate the instance even if cleanup cannot finish.
Never rely on an eventual close callback to commit a pending write.
Errors
Return the closest typed error category. Host/UI messages are generic and localized. Do not put credentials into log messages. An unsupported operation, permission denial, missing file and version conflict are different outcomes; turning all of them into an internal error prevents useful recovery.