Module door 

The door: how a participant that is not the app enumerates what it has open and performs one of its exported operations.

Resource trees already describe an app’s surface and dispatch already performs one operation on it; the missing step was naming a thing from outside the process that built it — without which collaboration, agency and scripting stay per-app features.

survey and invoke stay separate so enumeration can never cause an effect: a descriptor carries no callback, token or handle, so read-only is the shape of the type, not a promise in a comment.

Authority stays with the host, which resolves the caller against the workspace’s capability model before offering an address: an operation the caller may not perform is absent from the survey, never a flag to ignore.

Structs

ActionAddress

The stable address of one exported operation: which resource, which action. Both halves are the app’s own ids — no screen position, no list index — so the same address names the same operation across layouts, themes, resolutions, and a caller with no display can work from ids and labels alone.

ActionDescriptor

One exported operation, as inert data: everything a caller needs to decide whether to perform it, nothing that could perform it — an ActionSpec’s closure never appears here or crosses a boundary, only the address does.

InvocationProvenance

Caller identity and optional semantic context for an invoked action.

ResourceViewDescriptor

Serializable data describing one explicitly declared resource view.

Enums

DoorError

Why an address could not be performed. Unknown deliberately covers both “no such address” and “not offered to you”, so a caller can’t map what it may not reach by probing for a different error.

InputSpec

What an invocation of one action must carry, advertised on the descriptor rather than discovered by trying — enumeration is the only thing a caller that can’t see the screen has to work from.

Functions

encode

Turn an address plus its argument into the replayable action it names. Split out from invoke so a host can build/inspect/route the encoded action itself, and so argument rules are checked in one place. Binding happens before anything runs, so a bad call is a refusal with the document untouched, never a half-applied edit.

encode_json

Build an action from the canonical typed JSON argument object advertised by ActionDescriptor::params. Binding is strict and completes before any document mutation or application effect is attempted.

invoke

Perform the operation address names, attributed to provenance.actor. Resolve, bind, decode through the app’s own registry, then dispatch_by honouring the action’s locus. The actor is the caller’s Automerge actor bytes, so the room’s history names who asked; provenance.ambient carries the task or run the call belongs to. The resource’s concrete action label and address remain authoritative; app, purpose, group, and facets of the ambient context fill only fields the resource did not supply.

invoke_confirmed

invoke after an outer policy boundary has completed the action contract’s confirmation step. This is intentionally separate from invoke, whose default is fail-closed for consequential actions.

invoke_json

Typed-argument counterpart to invoke.

invoke_json_confirmed

Typed-argument invocation after an outer policy boundary has completed the action contract’s confirmation step.

locate

resolve, with the resource that publishes the action: what a door needs to place the action in the tree it grants over.

resolve

Resolve address against resources without running anything, so a caller can check what an address currently names before committing to it.

survey

Walk a resource forest and describe every operation it exports. Depth-first, parents before children, matching flatten’s order. Borrows the tree, returns owned data — nothing handed back can act on what it described.