fetch_body_bytecode_design.md

Fetch body on both bytecode compilers (#90)

Status: design spike. Docs only. #90 stays Partial. Promote stays DEFERRED.

This note is the design alternate Dev Lead Motoko flagged after the Assurance tip-lock. It does not implement a body, add an opcode, add a capability, or change production -compile-bc. The Owner authorizes an implementation later, as its own slice, on both bytecode compilers together.

The checklist that holds the current limit is docs/reference/lowered_hfir_prod_flip_criteria.md. The locked tip is 4d74dbcf9654caa05e0b1d9212b15bc5398359e3 (PR #71). Assurance on that SHA: Overall PASS, Promote DEFERRED (docs/journals/2026-09-30_assurance_tip_lock_4d74dbcf.md). The measurement record is docs/journals/2026-09-30_lowered_hfir_prod_flip_tip_lock.md.

Status quo

(fetch url method [body]) is one construct. The grant is network, the same name as capability.ForConstruct("fetch").

Path	What it does with a body
HFIR graph	LowerAST records a url edge, a method edge, and, when the call has a third argument, a body edge. The verifier requires url and method. body is optional.
bytecode.CompileToBytecode	Compiles child 1 (URL) and child 2 (method). Emits FETCH. Does not compile a fourth child.
hfir.LowerToBytecode	Compiles the url edge and then the method edge. Emits FETCH. Does not compile a body edge. A missing URL or method edge, or a method edge before the URL, is HFIR_BYTECODE_UNSUPPORTED and no BCProgram.
OpFetch	Name FETCH. Pops 2 (method, then URL). Pushes 1 (response bytes). Operand list empty. IntOperand is the zero value and is omitted from the JSON artifact. Capability network.
Bytecode VM	The grant check runs at the opcode, before http.NewRequest. The request body argument is nil.
Interpreter	The grant check runs before the call's children are evaluated. Three children send a nil reader. Four children send strings.NewReader of the evaluated body.
Generated Go	howlFrameFetch checks network before http.NewRequest. A missing body is a nil reader. A present body is strings.NewReader of that expression.
Generated JavaScript	howlFrameFetch checks network before fetch. A two-argument call leaves init.body unset. A third argument sets init.body, including "".

The shared conformance form is (fetch url method) with no body (tests/conformance/abi_v1/08_fetch_capability.howl, 20_nested_fetch.howl). 21_nested_multi_effect.howl has one untaken (fetch url "PUT" "phase2d-body-not-sent"). That call has a body edge. Neither bytecode artifact contains the string, and the untaken branch does not run. TestHFIRBytecodeFetchOperandOrder sends that same string on a taken PUT and records an empty request body, because both compilers drop it. TestProdFlipCriteriaLock requires OpFetch to pop 2 with an empty operand list, and its fetch_body subtest requires the body string to be absent from both artifacts.

The model-adapter transport carries kind fetch since #88. Wasm's infeasible set stays exec, spawn_agent, and http_server_start. fetch is not in that set, and this note does not add it.

Why the body is an accepted shared limit

FETCH has a fixed stack arity. The VM pops two strings. If one compiler pushed a body and the other did not, the stacks would disagree: one path would underflow or leave a value, and HFIR↔AST parity on programs that pass a body would end. The operand list is empty on purpose. The body string is absent from both artifacts, and the tip-lock records that absence.

The interpreter, Go, and JavaScript already send a body when the call has one. The lag is the two bytecode compilers and the VM handler that consumes FETCH. Keeping the drop on both compilers is what makes the bytecode hosts match each other. Lifting it on one compiler would be a parity failure, which the checklist defers.

The checklist's promote rule is: the body stays off OpFetch, and a later body design is a separate change on both compilers together. The kill row treats an OpFetch body operand, or any other fetch-body implementation, as a kill when a PR uses it to justify a production flip. A body slice that does not flip -compile-bc is that separate change. A flip PR that picks up the body in order to flip is the kill.

What a later slice has to preserve

These constraints apply to every option below. They are the contract the implementation slice has to meet. This note does not implement them.

• Both bytecode.CompileToBytecode and hfir.LowerToBytecode change in the same slice, and they emit the same operand shape for the same source.
• Compile order stays URL, then method, then the body when it is present. The VM pops in reverse, which is how FETCH already pops the method before the URL. WRITE_FILE is the same pattern: path, then data, then the opcode pops data first.
• Absent and empty stay different. No body means a nil reader on Go and an omitted init.body on JavaScript. A present "" is strings.NewReader("") on Go and init.body = "" on JavaScript. Collapsing "" into "no body" would change requests the AST hosts already send.
• The grant stays network. There is no new capability. Denial stays CAPABILITY_DENIED before http.NewRequest or fetch. The denial text omits the URL and the body, and the denial opens no connection. On the bytecode VM the grant check already runs at the opcode, after the instructions that produced the URL and the method. A body value produced by earlier instructions is the same order. The implementation slice keeps the check before the request.
• A non-string URL or method on the VM is TYPE_ERROR via popCheckedString. A popped body uses that same check. The implementation slice adds a conformance case for a non-string body on the bytecode VM. It leaves the interpreter, Go, and JavaScript conversions as they are unless that case shows a host mismatch the Owner wants closed in the same slice.
• The HFIR body edge is compiled only when it is the third data edge and its name is body. A fetch whose edges are missing or reordered stays HFIR_BYTECODE_UNSUPPORTED and no BCProgram. The AST path compiles the fourth child only when the call has one.
• The two-argument conformance cases stay body-absent: fetch_denied, fetch_granted, nested_fetch_denied, nested_fetch_granted. The untaken body in nested_multi_effect still must not be sent. A new granted case records the request body on the interpreter, the production bytecode VM, experimental -compile-hfir-bc, Go, and JavaScript. A new denial case with a body still opens no connection and does not echo the body.
• TestHFIRBytecodeFetchOperandOrder currently expects an empty server body for "phase2d-body-not-sent". The implementation slice changes that expectation because the taken PUT starts sending the string. That update is the point of the slice.
• TestProdFlipCriteriaLock currently requires pops 2, an empty operand list, and an artifact without the body string. The implementation slice updates those assertions in the same change as the compilers. This spike leaves the test alone.
• Either compiler changing expires the Assurance tip-lock. The body slice cites that expiry, does not claim the old lock, and does not flip -compile-bc. A new lock is a later measurement, taken when the Owner asks for one. The flip PR, if any, cites a fresh lock and still lists whatever accepted limits remain.
• The transport allow-list stays the Phase-1 adapter subset. nodeRoles does not gain fetch. Wasm does not gain a fetch import. #106 stays the do-not-build linker decision.

Design options

Three shapes can carry a body. All three are future work. None of them is authorized by this note.

Option A — presence flag on the existing FETCH

Keep the opcode FETCH and the capability network. Follow the EXEC precedent: EXEC carries IntOperand as a count and uses Pops: -1.

IntOperand 0 means the call has no body. The VM pops the method and then the URL and passes a nil reader. That is the zero value already stored on every FETCH in current artifacts (int_operand is omitempty, so 0 is absent from the JSON). Two-argument programs keep today's encoding.

IntOperand 1 means the call has a body. Both compilers emit the body instructions after the method. The VM pops the body, then the method, then the URL. The body is a string, and "" is a present empty body.

The registry row in that slice becomes operand list [int64], pops variable, pushes 1, capability network. The checklist sentence "empty operand list" and "pops 2" is rewritten in that same slice, because the accepted limit is being lifted by the Owner's separate change.

This option puts a body operand on OpFetch. Inside a production-flip PR, that shape is the kill row. The implementation slice is not a flip PR.

Option B — a second opcode for the three-argument call

Leave OpFetch as it is locked today: pops 2, empty operand list, capability network. Add one opcode, pops 3 (body, method, URL), pushes 1, capability network, empty operand list. A concrete name is FETCH_WITH_BODY. The grant name stays network. This is not a new capability.

bytecode.CompileToBytecode emits FETCH for three children and the new opcode for four. LowerToBytecode emits FETCH when the node has the URL and method edges only, and the new opcode when the third edge is body. The VM's existing FETCH handler stays on a nil reader. The new handler pops the body string and passes it to http.NewRequest.

Current two-argument artifacts stay valid without a flag. The cost is two opcodes for one source form, and a conformance matrix that has to cover both. A new opcode used to justify a production flip is also a kill. Fetch body is an accepted limit, not a promote-blocker name, so this opcode does not clear the fence.

Option C — always pop 3, with an absent sentinel

Change OpFetch to pop 3 unconditionally. When the source has no body, both compilers push nil before FETCH. When the source has a body, they push that value, including "". The VM treats nil as a nil reader and a string as the body.

Absent and empty stay distinct, and there is still one opcode. Every existing FETCH artifact underflows, because those artifacts push only the URL and the method. The registry pops field changes from 2 to 3, which fails TestProdFlipCriteriaLock until that test is updated in the implementation slice. There is no zero-value encoding that means "keep today's pop 2".

Constant operand, and why it does not cover the call

A StringOperand on FETCH could store a literal body. The hosts already evaluate a body expression (str_join, a variable, a call). An operand string would send literals and would still drop computed bodies, which is the split this design is trying to close. A constant operand is not a sufficient option on its own. Options A and B already carry a computed string on the stack.

Non-goals

• No implementation in this change. No edit under internal/bytecode, internal/hfir, internal/vm, internal/backend, or howlframe.go.
• No new opcode and no new capability in this change.
• No production -compile-bc flip. The *compileBc branch stays bytecode.CompileToBytecode.
• No conformance JSON edits, no lock-test edits, and no change to the tip-lock SHA 4d74dbcf9654caa05e0b1d9212b15bc5398359e3.
• #90 stays Partial. Promote stays DEFERRED. One lowered graph for every host is still Phase 2.
• This note does not choose an option for the Owner. The recommendation below is for review.

Recommendation

Non-binding. For Motoko's review, and for the Owner to accept or replace when kicking the implementation slice.

Prefer option A. One opcode, the existing network grant, and IntOperand 0 preserves the artifacts the tip-lock already measured. IntOperand 1 is the present body, including "". Both compilers emit that flag together. The VM reads it in the same slice and still denies before http.NewRequest.

Option B is the alternative if the review wants OpFetch's locked shape to stay byte-for-byte unchanged and will accept a second opcode. Option C is the alternative if a single unconditional arity is worth invalidating existing FETCH artifacts.

The implementation slice, when the Owner kicks it:

1. Lands option A (or the reviewed replacement) in bytecode.CompileToBytecode, hfir.LowerToBytecode, and the OpFetch VM handler together.
2. Adds the granted body case and the denial-with-body case on the hosts that already mediate fetch. Updates the operand-order expectation that currently records an empty body, and updates the fetch_body lock assertion, in that same slice.
3. Rewrites the Fetch body row of the checklist so it describes the shape that shipped. Leaves the promote-blocker fence, the Decision (defer), and the kill rule for flip-justifying body work in place.
4. Does not flip -compile-bc. States that the tip-lock 4d74dbcf has expired because the compilers changed. Does not mark #90 Done.

The next build slice on the promote path is still attr_escape parity (and regex_match onto REGEX_MATCH) unless the Owner says otherwise. Those names are the fence. The body is the accepted limit, and it stays a separate change.