Form ABI

This document defines a minimal interactive form ABI for modules that can run in both CLI and web hosts.

Scope:

• Single input per prompt
• No persistence
• No JSON metadata export
• Shared labels/keys between interfaces

Required Exports

• memory
• input_ptr() -> i32
• input_utf8_cap() -> i32
• run(input_size: i32) -> i32
• output_ptr() -> i32
• output_utf8_cap() -> i32
• input_key_ptr() -> i32
• input_key_size() -> i32
• input_label_ptr() -> i32
• input_label_size() -> i32
• error_message_ptr() -> i32
• error_message_size() -> i32

Input Buffer

At input_ptr:

• UTF-8 bytes for the current input value only.

Host must ensure:

• input_size <= input_utf8_cap()
• writes stay in wasm memory bounds

Prompt/Completion Semantics

For the current prompt, module provides:

• input_key (stable field key)
• input_label (human-facing label)

Form is complete when:

• input_key_size() == 0

When complete, host should treat the form as finished and read final output from output_ptr.

Run Semantics

Host flow:

1. Read current metadata (input_key, input_label, error_message).
2. If input_key_size() == 0, form is complete.
3. Otherwise, collect one input value.
4. Write value bytes to input_ptr.
5. Call run(input_size).

Module behavior:

• On validation failure:
  • keep internal state unchanged
  • set error_message_size > 0
• On success:
  • advance internal state (if any)
  • clear error_message (recommended)

run return value is UTF-8 output size in output_ptr. Final result is read when form is complete.

Invariants

Host should enforce:

• all pointer+size reads are within wasm memory bounds
• all sizes are non-negative
• all metadata strings are valid UTF-8
• output size from run is non-negative and does not exceed output_utf8_cap