feat: opt-in non-Candid wire format via encoder / decoder parenthetical

[ggreif]

Summary

Per-public-method, opt-in escape hatch from Candid in both directions:

persistent actor {
  (with encoder = <T -> Blob> ;
        decoder = <Blob -> A>)
  public func go(_ : A) : async T = …
}

• encoder : T -> Blob replaces Candid serialization on reply.
• decoder : Blob -> A replaces Candid deserialization on ingress.

Both fields are independently optional; either, both, or neither can appear, and unrecognised fields warn (M0212). The strategic driver is direct OpenAPI/Web2 interfacing — see .claude/plans/non-candid.md for the design memo, including the actor-level inheritance idea and the motivation. (The OpenAPI integration is its own follow-on.)

Implementation

Frontend (src/mo_frontend/typing.ml)

• check_vis_parenthetical does per-field bidirectional checking against a known-fields table [("encoder", T -> Blob); ("decoder", Blob -> A)]. Encoder type is driven by the method's return type, decoder by its ingress type. Direction (method → codec) is documented in a comment alongside the alternative inverse direction (codec types driving the method signature) for future exploration.
• M0214 type-mismatch (per-field), M0215 effect-free check named per field, M0211 redundant-empty parenthetical, M0212 unrecognised attribute.

IR (src/ir_def/ir.ml)

• FuncE's trailing exp option (* encoder *) replaced by a labeled record codecs = { encoder : exp option; decoder : exp option }. no_codecs helper for the common no-annotation case. Future codec-shaped fields (e.g. inbound-cycles caps, schema pins) land additively.
• check_ir independently type-checks both fields.

IR passes

• rename, subst_var, freevars, await, async, const, tailcall, erase_typ_field, eq, show — pass-through, retyped from exp option to codecs.
• arrange_ir.ml prints both fields side by side.

Desugaring (src/lowering/desugar.ml)

• find_codec_in_par factored out from the existing find_encoder_in_par.
• New find_decoder_in_par mirror.
• build_codecs (replacing build_encoders) returns (enc_opt, dec_opt) list.
• build_actor stamps both fields onto each public method's FuncE.codecs, preserving any pre-existing per-field override.

Async lowering (src/ir_passes/async.ml)

• The CPS transform consults codecs.encoder when synthesising the reply continuation, lifting it into ICReplyPrim(ts, Some enc). Decoder unaffected here — it lives only on FuncE.

Codegen (src/codegen/compile_classical.ml & compile_enhanced.ml)

• Encoder (existing): ICReplyPrim branches on enc_opt — Some → call closure, IC.reply_with_data; None → Serialization.serialize.
• Decoder (new): FuncDec.{lit, closed, compile_const_message} gain a ?(decoder=None) thunk parameter (E.t -> VarEnv.t -> G.t) option. The thunk is constructed at the FuncE call site (where compile_exp_vanilla is in scope) wrapping the decoder expression. Inside compile_const_message, branch at the argument-decoding step: None → Serialization.deserialize; Some compile_dec → compile_dec env ae0 ; closure-call on raw IC.arg_data.

AST interpreter (src/mo_interpreter/interpret.ml)

• Codec parentheticals are intentionally not visited (the AST interpreter doesn't model Candid serialization). One-line comment surfaces this for reviewers.

Tests

Run-drun:

• parenthetical-public.mo — encoder, returns (), all phases.
• parenthetical-decoder.mo — full pipeline. Method's ingress is ?Nat; decoder is the flow Blob -> ?Text -> ?Nat composed via decodeUtf8 and Nat.fromText. The //CALL payload is the raw three ASCII bytes "123" (0x313233) — not a Candid envelope. With the decoder active that blob deserialises as ?123, and the reply is Candid Nat 123 (0x4449444c00017d7b). Without the decoder Candid would reject 0x313233 as malformed input — so the green test is end-to-end proof that ingress Candid is bypassed.

Fail (matched pairs, encoder ↔ decoder):

• parenthetical-{encoder,decoder}-effect.mo — M0215 effect-free check fires.
• parenthetical-{encoder,decoder}-mismatch.mo — M0095 (finer than field-level M0214) on a wrong codec signature.

Test plan

• make -C test/run-drun parenthetical-public.only passes
• make -C test/run-drun parenthetical-decoder.only passes
• make -C test/fail includes the four new fail tests with stable output

🤖 Generated with Claude Code