Contexts and namespaces

Almost every “the app tools don’t work” report comes down to a missing context. This is the shape of it.

The hierarchy

• An application is installed WASM plus its ABI. Installing it creates no state.
• A namespace is the governance unit: it owns members and an upgrade policy, and is created for an application.
• A context is where state actually lives and where calls execute. It belongs to a namespace and runs one application (one service of it, for a multi-service app).

So a method call needs a context, a context needs a namespace, and a namespace needs an installed application.

Caution

Installing an application from the registry does not create a context. This is the step people miss, and it is why the app’s tools are listed while select_app finds no context to act in.

From nothing to a callable app

1. Install the application (or confirm it is installed):

   Call list_applications.

   To add one, install_application takes coords as package@version.

   For an app you have not used before, call describe_app next. Its guide can ask for a particular layout, such as a context in an open subgroup rather than straight in the namespace.

2. Create a namespace for it:

   Call create_namespace with application "kv-store".

   The result carries the namespace id.

3. Create a context in that namespace:

   Call create_context with application "kv-store" and group "<namespace-id>".

   group takes a namespace id or the id of a subgroup inside one, for an app whose guide sets its contexts up in a subgroup.

   For a multi-service application, pass service too — describe_app reports the service names existing contexts use, and that is the value this wants.

   If the app’s init takes parameters (describe_app lists init with them), pass them as args, keyed by parameter name - for example args {"name": "world-1", "seed": 42, "now": 1727000000} for mero-blocks. They are checked against the ABI before anything reaches the node. Leaving them out, getting one wrong, or passing one init does not declare returns an error naming each missing, invalid or unknown parameter, with the init signature, and creates nothing.

4. Select the app and call it:

   Select kv-store, then call its get method for key "greeting".

   With exactly one context, select_app chooses it, and the app_handle it returns names it.

Aliases

Context ids are base58 and unmemorable. An alias fixes that for the whole node, not just this session:

Create an alias "staging" for context 8Hk2….

create_alias takes alias and contextId; lookup_alias resolves one back. A lookup that misses is reported as a result, not an error — “No alias named …” is a true answer to a fair question.

Anywhere a tool takes a context, including select_app’s context, an alias works in place of the id. Resolved aliases are cached for the session.

Members

Namespace membership is governance, and lives in the governance toolset:

• invite_to_namespace mints an invitation for a namespace.
• join_namespace accepts one.
• leave_namespace leaves.
• list_group_members / add_group_members inspect and extend a group’s roster. Members are added as { identity, role } pairs.

Pass the invitation through unchanged

An invitation is signed over its own bytes. Reshaping it — renaming keys, dropping fields, re-serialising through a schema — invalidates the signature and the join fails. Hand the object invite_to_namespace returned to join_namespace exactly as it came back. The server declares it as an opaque object for this reason: declaring its fields would let validation strip the ones it did not know about.

Deleting things, in the right order

Delete contexts before their namespace. Contexts outlive the namespace they belonged to, and a context whose namespace is gone is uncallable but still present — holding its data and showing up in list_contexts:

1. delete_context for each context in the namespace
2. delete_namespace

If you already deleted the namespace first, delete_context is still the fix — it is what clears a context stranded that way.

delete_context, delete_namespace, uninstall_application, delete_blob and leave_namespace are all marked destructive, so a client that surfaces that hint can prompt before running them.

Blobs

The blobs toolset covers node storage: upload_blob (base64 bytes, optional hash, optional context to scope it), list_blobs, delete_blob, plus install_application / uninstall_application. Application bytecode is a blob, which is why they share a toolset.

Both blobs and governance are on by default and can be trimmed with CALIMERO_MCP_TOOLSETS when you want a smaller, read-mostly tool list.