World filesystem

Memona filesystem extension ABI 0.1.0, distributed as a WebAssembly component. Rust guests can target wasm32-wasip2. Selected WASI 0.2 CLI, clocks, random, IO and filesystem interfaces are allowed for the standard library, with empty arguments/environment, empty preopens, and discarded stdio. WASI sockets and HTTP imports are not allowed; networking uses the host interface.

Imports:
- interface memona:filesystem/host@0.1.0
Exports:
- interface memona:filesystem/provider@0.1.0

Import interface memona:filesystem/host@0.1.0

Host services scoped to the current connection. No ambient filesystem, environment, sockets, credentials, or network permissions are inherited.

Types

`enum host-error`

Stable failures without backend messages or credential-bearing URLs.

Enum Cases

denied
unavailable
invalid-input
cancelled
internal

`enum log-level`

Severity of a diagnostic event. The host may discard message contents.

Enum Cases

debug
info
warn
error

`record header`

An HTTP header. Host-controlled transport headers cannot be overridden.

Record Fields

name: string
value: string

`record request`

HTTP(S) request, at most 4 MiB body and 64 headers of 8 KiB each.

Record Fields

method: string
url: string
headers: list<header>
body: list<u8>

`record response`

Bounded HTTP response. Bodies exceeding 4 MiB fail; they are not truncated.

Record Fields

status: u16
headers: list<header>
body: list<u8>

Functions

`http: func`

Requests only hosts both declared by the package and granted on the connection. Each redirect and DNS result is checked, and DNS is pinned. Private/LAN addresses additionally require the private-network grant. Cross-origin redirects remove request headers; HTTPS cannot downgrade.

Params

request: request

Return values

result<response, host-error>

`log: func`

Emits a diagnostic event. Never include secrets or private document data.

Params

level: log-level
message: string

`config: func`

Reads configuration or a session-only secret for this connection.

Params

key: string

Return values

option<string>

Export interface memona:filesystem/provider@0.1.0

Types

`enum error-code`

Stable operation failures. A mutation interrupted after dispatch can report outcome-unknown: inspect remote state before deciding to retry.

Enum Cases

not-found
denied
unsupported
conflict
unavailable
invalid-input
cancelled
outcome-unknown
internal

`enum entry-kind`

Links and other backend object kinds are not exposed in API 0.1.

Enum Cases

file
directory

`record config-value`

A configuration field. Boolean values are serialized as true or false.

Record Fields

key: string
value: string

`record capabilities`

Optional operations. False capabilities must return unsupported. Conditional-write promises atomic create-only and revision comparisons.

Record Fields

write: bool
mkdir: bool
rename: bool
remove: bool
conditional-write: bool
watch: bool

`record file-info`

Byte length and an opaque revision (maximum 4096 UTF-8 bytes), if known.

Record Fields

kind: entry-kind
size: u64
revision: option<string>

`record entry`

One child name, without slashes, dot segments, or control characters.

Record Fields

name: string
info: file-info

`record list-page`

At most the requested number of entries. A cursor (maximum 4096 bytes) identifies another page; absence means enumeration is complete.

Record Fields

entries: list<entry>
cursor: option<string>

`record read-result`

At most the requested byte count. EOF refers to this read’s ending offset.

Record Fields

data: list<u8>
revision: option<string>
eof: bool

`variant write-condition`

Atomic preconditions: absent file, exact opaque revision, or unconditional replacement. Providers must never simulate comparisons non-atomically.

Variant Cases

create-only
if-match: string
overwrite

`enum change-kind`

Changes since a previous polling cursor.

Enum Cases

created
modified
removed

`record change`

A changed resource path relative to the connection root.

Record Fields

path: string
kind: change-kind

`record change-page`

At most 256 changes and a cursor of at most 4096 UTF-8 bytes.

Record Fields

changes: list<change>
cursor: option<string>

Functions

`open: func`

Opens exactly one host-owned connection per component instance. The host passes only this connection’s configuration and in-memory credentials.

Params

provider-id: string
config: list<config-value>

Return values

result<capabilities, error-code>

`close: func`

Best-effort cleanup before disposal. The host may dispose immediately after a trap, cancellation, permission change, or process shutdown.

`stat: func`

Reads metadata without changing the resource.

Params

path: string

Return values

result<file-info, error-code>

`list: func`

Enumerates 1–256 direct children per request, without recursive traversal.

Params

path: string
cursor: option<string>
limit: u32

Return values

result<list-page, error-code>

`read: func`

Reads a byte range, with length between 1 and 1,048,576. Larger files require repeated ranged reads; revisions let callers detect changes.

Params

path: string
offset: u64
length: u32

Return values

result<read-result, error-code>

`write: func`

Replaces one complete file, at most 1,048,576 bytes. Oversized writes are rejected, never truncated. Streaming, append, and multipart writes are not supported in API 0.1. Never automatically retry a mutation.