[mark1russell7]

The envelope form of a program (coeval M7)

coeval decided (D6, D9, D10) that a document is an envelope { type, value } (header keys name, own), a call is an envelope whose type is a procedure path (an array of keys) and whose value is the input, and a reference is { "type": "ref", "value": [root, step, ...] }.

This PR adds the envelope form as a surface that converts to the native $proc form. The interpreter (hydrateInput) does not change. The root of a program decides its form: an envelope inside the input of a $proc program stays plain data, so no existing program changes behavior.

What changes

• packages/client/src/procedures/envelope.ts (new): isEnvelopeProgram, fromEnvelopeProgram, toEnvelopeProgram, and the types EnvelopeProgram, EnvelopeRef, EnvelopeLiteral, EnvelopePath. Exported from ., ./browser and ./procedures.
• Client.exec() / Client.execStream() accept an envelope root. It converts first, then runs as before. exec(program, input) merges input exactly as for a $proc root. Every other form and error message is unchanged.
• PROGRAM-FORMAT.md: new section 11 "The envelope form" (mapping table, a full example, the rules). "Open questions" becomes section 12, and its references are updated (two in the document, one in deep-dive-2026-10/STATUS.md).
• Changeset: patch of the client group (additive, D13).

The mapping

Envelope form	$proc form
{ "type": ["client","add"], "value": input }	{ "$proc": ["client","add"], "input": input }
{ "type": { "type": "ref", "value": ["world","client","add"] }, "value": input }	same
{ "type": path, "value": null }	{ "$proc": path } (no input: the procedure gets undefined, and passThrough applies)
header "name": "sum"	"$name": "sum"
{ "type": "ref", "value": ["names","sum","total"] }	{ "$ref": "sum.total" }
{ "type": "ref", "value": ["names","last"] }	{ "$ref": "$last" }
{ "type": "literal", "value": x }	{ "$literal": x }
an object with a $proc, $ref or $literal key, or a runtime ProcedureRef	{ "$literal": object } (data)
(none)	$when: a program that needs it keeps the $proc form

Errors: a ref root other than names (the message names the root and says that client programs read only names), a ref key with a dot or a key that is not an integer of 0 or more, a header on a ref or a literal, own on a call, a non-string name, a call type that is a ref but not into the world, and cycles or depth over MAX_DATA_DEPTH.

toEnvelopeProgram refuses $when, extra keys on a call or a $ref, a $ref to a step named last, and data that the envelope form reads differently when that data holds a construct. The round trip fromEnvelopeProgram(toEnvelopeProgram(p)) deep-equals p, with two documented exceptions that give the same values: a call with input: null, and envelope-shaped (or $-keyed) data. Both come back wrapped in $literal.

Tests

envelope.test.ts (45 tests): the PROGRAM-FORMAT examples in both forms (strict conversion both ways, and the same results through exec), procedure.define with an envelope body, world-ref types, exec(program, input), execStream, a call without input and passThrough, the escapes, old $proc programs keeping envelopes as data, the errors, and a fast-check property: when toEnvelopeProgram accepts a program, the round trip hydrates to the same value. At 5000 runs that is about 4500 accepted programs, about 2250 of them with calls.

test/api/public-api.txt was updated on purpose with UPDATE_API_SNAPSHOT=1 (the snapshot test only). The update adds the new exports and widens the exec and execStream parameter.

Local runs: pnpm --filter @procedures/client build, typecheck and test (2112 passed), node .github/scripts/typecheck-tests.mjs client, and pnpm lint:ste (0 errors; the warnings were already on main).

🤖 Generated with Claude Code