The form-envelope.* family (6 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.
form-envelope.create
| Property | Value |
|---|---|
| Capability | form-envelope.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
open an EXPECTED envelope addressed to a recipient. { formTemplateId, recipientPartyId? | recipientEmail?, expectedData?, dueAt? }. The template must be ACTIVE; the
version pin is resolved at SEND time (so an edit-then-send still pins the then-current version).
Call POST /v/form-envelope.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.create.
form-envelope.get
| Property | Value |
|---|---|
| Capability | form-envelope.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
one envelope. { id }.
Call POST /v/form-envelope.get with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.get.
form-envelope.list
| Property | Value |
|---|---|
| Capability | form-envelope.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
list envelopes (optionally filter by status / template). { status?, formTemplateId? }.
Call POST /v/form-envelope.list with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.list.
form-envelope.send
| Property | Value |
|---|---|
| Capability | form-envelope.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
EXPECTED->SENT. Pins the template’s CURRENT version row (R11 snapshot-not-live):
re-publishing the template does not change an in-flight envelope. { envelopeId }.
Call POST /v/form-envelope.send with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.send.
form-envelope.submit
| Property | Value |
|---|---|
| Capability | form-envelope.submit |
| Risk class | Write - autonomy L1 |
| Min. permission | External (portal / signer token) |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | Yes |
| Egress | None - in-box (pure Postgres, no outbound call) |
The public ingest door ([2026] VJS-CC-OPBOX 24):
the new submission write chokepoint that OWNS its facts. { envelopeId, data, submissionId? }.
Pipeline (mirrors form.ingest, retargeted to the envelope):
- PUBLISHED-pin gate: the envelope must be SENT|OPENED against an ACTIVE template (INV-11 fail-closed).
- Idempotency: a submitted envelope with existing facts is a replay.
- Per field: sanitise -> extract-base64-to-encrypted-Fact (INV-7) -> write a key-bound Fact (target_type=‘form_envelope’, C7) via form::write_submission_fact (promoted pub(crate)).
- SENT|OPENED -> SUBMITTED, set submitted_at.
Call POST /v/form-envelope.submit with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.submit.
form-envelope.void
| Property | Value |
|---|---|
| Capability | form-envelope.write |
| Risk class | Sensitive - autonomy L2 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | Yes |
| Egress | None - in-box (pure Postgres, no outbound call) |
the sender aborts -> VOIDED (terminal, immutable). { envelopeId }.
Idempotent: a re-void of a VOIDED envelope is a no-op success (mirrors board.archive).
Call POST /v/form-envelope.void with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool form-envelope.void.