Malli schema layer for the IAddon contract.
Every data shape that crosses the IAddon protocol boundary has a schema here, so a host can validate an addon's contract outputs and an addon can validate the config it receives. Stratified: the schemas sit as pure data BELOW the protocol — they read the protocol's own constants (single source, no drift) and the protocol never depends on the schemas.
Self-contained by design (DDD): the addon bounded context owns its schemas.
Deps are malli + hive-dsl only — NO hive-spi. Schemas are registered in a
LOCAL composite registry under :addon/* keys; reach them via schema,
validate, explain (which thread {:registry registry}) or by passing
{:registry registry} yourself. The registry is NEVER installed as the malli
global default (shared-JVM safety).
Errors bridge to hive-dsl Result: the validate*/validate-addon helpers
return (r/ok x) on success and (r/err :addon/... {:explanation ...}) on
failure, with a qualified-keyword error category.
Malli schema layer for the IAddon contract.
Every data shape that crosses the IAddon protocol boundary has a schema
here, so a host can validate an addon's contract outputs and an addon can
validate the config it receives. Stratified: the schemas sit as pure data
BELOW the protocol — they read the protocol's own constants (single source,
no drift) and the protocol never depends on the schemas.
Self-contained by design (DDD): the addon bounded context owns its schemas.
Deps are malli + hive-dsl only — NO hive-spi. Schemas are registered in a
LOCAL composite registry under :addon/* keys; reach them via `schema`,
`validate`, `explain` (which thread {:registry registry}) or by passing
{:registry registry} yourself. The registry is NEVER installed as the malli
global default (shared-JVM safety).
Errors bridge to hive-dsl Result: the `validate*`/`validate-addon` helpers
return (r/ok x) on success and (r/err :addon/... {:explanation ...}) on
failure, with a qualified-keyword error category.Config map passed to (initialize! addon config). Open — contents vary by addon type; at minimum the host echoes :addon/id and :addon/config.
Config map passed to (initialize! addon config). Open — contents vary by addon type; at minimum the host echoes :addon/id and :addon/config.
Stable, non-empty string identifier — the registry key for an addon.
Stable, non-empty string identifier — the registry key for an addon.
The addon's execution type. Derived from proto/valid-addon-types so the enum can never drift from the protocol's own constant.
The addon's execution type. Derived from proto/valid-addon-types so the enum can never drift from the protocol's own constant.
A single capability keyword. OPEN: the standard set plus custom addon capabilities (:vector-search, :llm-routing, ...) are all legal (OCP).
A single capability keyword. OPEN: the standard set plus custom addon capabilities (:vector-search, :llm-routing, ...) are all legal (OCP).
Set of capability keywords an addon provides.
Set of capability keywords an addon provides.
Return shape of (excluded-tools addon): a set of tool-name strings this addon supersedes from other addons (may be empty).
Return shape of (excluded-tools addon): a set of tool-name strings this addon supersedes from other addons (may be empty).
(explain ?s x)Registry-aware explain — nil on success, error map on failure.
Registry-aware explain — nil on success, error map on failure.
Return shape of (health addon).
Return shape of (health addon).
Health status keyword. Derived from proto/health-statuses (no drift).
Health status keyword. Derived from proto/health-statuses (no drift).
Return shape of (hooks addon): namespaced hook-key -> hook value. Keys are qualified keywords matching the host ext-key surface (:cu/a, :catchup/wrap, :multi/verb, :spawn/opts-overlay, :op-schema/carto). Values are fns OR data bundles (e.g. :op-schema/* -> a schema map), so :any.
Return shape of (hooks addon): namespaced hook-key -> hook value. Keys are qualified keywords matching the host ext-key surface (:cu/a, :catchup/wrap, :multi/verb, :spawn/opts-overlay, :op-schema/carto). Values are fns OR data bundles (e.g. :op-schema/* -> a schema map), so :any.
(humanize-errors ?s x)Human-readable error data for x against ?s, or nil if x conforms.
Human-readable error data for x against ?s, or nil if x conforms.
Return shape of (initialize! addon config). Open — addons attach arbitrary :metadata; :already-initialized? marks the idempotent re-call.
Return shape of (initialize! addon config). Open — addons attach arbitrary :metadata; :already-initialized? marks the idempotent re-call.
Malli function schemas ([:=> ...]) for the IAddon methods, as DATA keyed by
fully-qualified method symbol. For scoped, reversible instrumentation only
(malli.instrument over a select-keys slice) — NEVER attach globally or call
bare malli.instrument/instrument!: that mutates var roots across the shared
JVM. this is :any (the addon instance).
Malli function schemas ([:=> ...]) for the IAddon methods, as DATA keyed by fully-qualified method symbol. For scoped, reversible instrumentation only (malli.instrument over a select-keys slice) — NEVER attach globally or call bare malli.instrument/instrument!: that mutates var roots across the shared JVM. `this` is :any (the addon instance).
Composite malli registry: malli defaults + this lib's :addon/* schemas. NOT installed as the global default (shared-JVM safety) — reach it via the wrappers below or pass {:registry registry} explicitly at call sites.
Composite malli registry: malli defaults + this lib's :addon/* schemas.
NOT installed as the global default (shared-JVM safety) — reach it via the
wrappers below or pass {:registry registry} explicitly at call sites.(schema ?s)Compile ?s against the local :addon/* registry.
Compile ?s against the local :addon/* registry.
Return shape of (schema-extensions addon). Two idioms coexist in the wild: a SEQUENCE of DataScript attribute-defs (each a map — the protocol's original contract) OR a MAP of tool-name -> param JSON-schema (the MCP inputSchema- extension seam, used by hive-knowledge). Both — and the empty case of each — are accepted; the sequential branch is constrained to a seq of MAPS so a malformed non-map element is rejected (protocol.cljc: each schema-def is a map suitable for DataScript merge).
Return shape of (schema-extensions addon). Two idioms coexist in the wild: a SEQUENCE of DataScript attribute-defs (each a map — the protocol's original contract) OR a MAP of tool-name -> param JSON-schema (the MCP inputSchema- extension seam, used by hive-knowledge). Both — and the empty case of each — are accepted; the sequential branch is constrained to a seq of MAPS so a malformed non-map element is rejected (protocol.cljc: each schema-def is a map suitable for DataScript merge).
A single MCP tool definition contributed by (tools addon). :inputSchema is the JSON-schema-ish map the host forwards; :handler is an arbitrary fn. Open — some addons carry extra keys. Only :name is required: :handler/:inputSchema are OPTIONAL BY DESIGN because a :mcp-bridge/:external addon's executable handler is supplied by the host transport, not the tool-def.
A single MCP tool definition contributed by (tools addon). :inputSchema is the JSON-schema-ish map the host forwards; :handler is an arbitrary fn. Open — some addons carry extra keys. Only :name is required: :handler/:inputSchema are OPTIONAL BY DESIGN because a :mcp-bridge/:external addon's executable handler is supplied by the host transport, not the tool-def.
Return shape of (tools addon): a sequence of tool-defs (may be empty).
Return shape of (tools addon): a sequence of tool-defs (may be empty).
(validate ?s x)Registry-aware validate — true/false.
Registry-aware validate — true/false.
(validate* ?s x)(validate* ?s x category)Validate x against ?s, bridging to hive-dsl Result.
(r/ok x) on success; (r/err category {:explanation <humanized>}) on failure.
category defaults to :addon/schema-violation and must be a qualified
keyword (hive-dsl taxonomy convention).
Validate x against ?s, bridging to hive-dsl Result.
(r/ok x) on success; (r/err category {:explanation <humanized>}) on failure.
`category` defaults to :addon/schema-violation and must be a qualified
keyword (hive-dsl taxonomy convention).(validate-addon addon)Validate a live IAddon instance's contract OUTPUTS against the schemas. Exercises only the pure, non-mutating methods (does NOT call initialize! or shutdown!). Returns (r/ok addon) when every output conforms, else the FIRST (r/err :addon/contract-violation {:method .. :value .. :explanation ..}), or (r/err :addon/method-threw ..) if a method blows up for a non-contract reason.
excluded-tools and hooks are optional per the protocol (legacy addons may omit them, defaulting to #{}/{}); an unimplemented optional method is skipped, an unimplemented required method is a violation. Non-implementation is recognized for BOTH extension mechanisms: inline deftype/defrecord/reify omission (AbstractMethodError) and extend-*/metadata omission (IllegalArgumentException "No implementation of method").
Validate a live IAddon instance's contract OUTPUTS against the schemas.
Exercises only the pure, non-mutating methods (does NOT call initialize! or
shutdown!). Returns (r/ok addon) when every output conforms, else the FIRST
(r/err :addon/contract-violation {:method .. :value .. :explanation ..}), or
(r/err :addon/method-threw ..) if a method blows up for a non-contract reason.
excluded-tools and hooks are optional per the protocol (legacy addons may
omit them, defaulting to #{}/{}); an unimplemented optional method is
skipped, an unimplemented required method is a violation. Non-implementation
is recognized for BOTH extension mechanisms: inline deftype/defrecord/reify
omission (AbstractMethodError) and extend-*/metadata omission
(IllegalArgumentException "No implementation of method").cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |