Skip to content
Soul Stack

core.module

← Module catalog

soul-sidesoulstack.systemsystem

Install a SoulModule plugin on the host from the active Sigil grant.

core.module pulls a custom plugin binary from the Keeper over the existing mTLS EventStream connection, verifies it, and atomically places it into the host's module-cache slot. It is idempotent by sha256: if the required binary is already in the slot, the step does nothing. This is how a plugin from the community ecosystem becomes available to later Destiny steps on that Soul.

Requirements

  • Rootnot required
  • Sidesoul-side
  • Collectionsoulstack.system
  • Categorysystem
Capabilitiesnetwork_outbound

States

core.module.installed — The plugin is pulled from the Keeper, verified, and installed into the host's module cache.

Changes when

The required binary (by sha256) was not in the slot and has been installed.

Stays unchanged when

A binary with the required sha256 is already in the slot.

Parameters

ParamTypeRequired / defaultDescription
namestringrequiredFull plugin name "<namespace>.<name>" (e.g. community.redis).
refstringoptionalPin check (NOT a version selector): the active Sigil grant must be on this ref, otherwise module_not_allowed.

Example — Pull a community plugin before using it

- name: Install community.redis plugin
  module: core.module.installed
  params:
    name: community.redis

Output

FieldTypeDescription
namestring
installedtrue
sha256string

Notes

  • The fetch travels over the already-established Soul→Keeper mTLS connection (ADR-065(a)) — the host needs no separate outbound network access.
  • ref is not a version selector but a pin check: the active Sigil grant must be on exactly this ref, otherwise the step fails with module_not_allowed.

Security & defaults

  • Only plugins from the incarnation's active Sigil grant are installed — an arbitrary name will not be pulled.
  • The binary is verified before installation; the cache slot is updated atomically, with no window of a partially written file.

See also