pluginabi API

pub fn valid_op(op: text) -> boolean

Is this one of the six? THE gate on the host side: an unknown op is a version skew between plugin and host, and the only safe answer is to refuse rather than to interpret.

pub fn takes_arg(op: text) -> boolean

Which operations read the arg slot. Recorded here rather than in each host so the two sides cannot drift: a host that sends arg for snapshot is confused about the contract, and a plugin that reads it would be reading whatever the host happened to leave there.

pub fn request(op: text, state_b64: text, arg_b64: text) -> vector<u8>

{ "op": text, "state": bytes, "arg": bytes }

state is always present (the empty byte string for initial_state), so the plugin never has to distinguish "absent" from "empty" — an absent-vs-empty ambiguity across a wire is exactly the kind of thing that produces a plausible wrong answer instead of an error.

⚠ A payload that is not base64 answers an EMPTY frame, which check_request refuses as malformed-frame. Handing over a raw string by mistake ("hello" for its base64) is then an error at the front door, not a state that arrives as nothing — only "" decodes to the empty byte string.

pub fn req_op(frame: vector<u8>) -> text

Read the operation out of a request frame. Answers "" for a frame that does not decode, which valid_op then rejects — so a corrupt frame and an unknown op take the same path.

pub fn req_state_b64(frame: vector<u8>) -> text

The state the host is handing over, base64. Always present — the empty byte string for initial_state — so a plugin never has to tell absent from empty.

pub fn req_arg_b64(frame: vector<u8>) -> text

The operation's argument, base64. Only apply_op and make_op carry one; ask takes_arg first, because for the other four this is whatever the host left in the slot.

pub fn reply_ok(out_b64: text) -> vector<u8>

success: { "ok": true, "out": bytes } failure: { "ok": false, "err": text }

A failure carries a CODE, not a message: the host shows it to a person, and a free-form string from the plugin would be the one channel out of the sandbox that is neither bytes-the-host- inspects (render) nor a value it asked for: render output stays the only rich channel.

pub fn reply_err(code: text) -> vector<u8>

The failure reply. code is a CODE and not a message: a free-form string would be a channel out of the sandbox that nothing inspects, and the host is what turns a code into words a person reads.

pub fn reply_is_ok(frame: vector<u8>) -> boolean

true only for a well-formed success reply. A frame that does not decode, or whose ok is not the boolean true, reads as failure — the fail-closed direction.

pub fn reply_out_b64(frame: vector<u8>) -> text

The success payload, base64. Only meaningful once reply_is_ok says yes — on a failure reply it answers "", which is indistinguishable from an empty success.

pub fn reply_err_code(frame: vector<u8>) -> text

The failure code. The other half of the same pair: check reply_is_ok, then read exactly one of these two.

pub fn check_request(frame: vector<u8>) -> text

Validate an inbound request frame the way a host must, BEFORE dispatching it: decode, then check the vocabulary. Returns "" when the frame is acceptable, else the error code to reply with. Centralised so every host does the same two checks in the same order rather than each re-deriving them — the contract has one front door.