A COMPOSITE IAddon — an addon whose members are themselves addons.
Every host registry in the ecosystem is FLAT: a host holds addons, and an addon holds tools. There was no way to say "this one addon IS a catalog of addons", so a family of related capabilities had to arrive as N sibling entries in the host registry, versioned, mounted and reasoned about apart.
A CompositeAddon closes that. It satisfies IAddon on its outer face, so a host mounts it as ONE addon; inside, it owns a private IMountHost sub-registry and drives its members through the same protocol. Because the composite is itself an IAddon, a composite may be a MEMBER of another composite, to arbitrary depth — the structure is a tree, not two layers.
What is projected upward, and why the two halves differ:
Member failure is GRACEFUL by default, the same bargain hive-addon.mount already strikes: a member that fails to initialize is recorded, the rest still mount, and the composite reports :degraded rather than vanishing. Set :on-member-failure :fail to make any member failure fail the composite.
Ordering is hive-addon.mount.solve, reused rather than reimplemented: a member may declare :member/depends-on over its siblings and the solver topologically orders them, with the same graceful cycle handling.
Pure .cljc — no JVM-only construction path. Members arrive as INSTANCES, so the composite never resolves a ctor, reads a manifest or touches a classpath. A host that wants classpath discovery already has hive-addon.mount.compose; this namespace is what that machinery mounts INTO.
Rationale lives in hive memory (KG-linked), not here.
A COMPOSITE IAddon — an addon whose members are themselves addons. Every host registry in the ecosystem is FLAT: a host holds addons, and an addon holds tools. There was no way to say "this one addon IS a catalog of addons", so a family of related capabilities had to arrive as N sibling entries in the host registry, versioned, mounted and reasoned about apart. A CompositeAddon closes that. It satisfies IAddon on its outer face, so a host mounts it as ONE addon; inside, it owns a private IMountHost sub-registry and drives its members through the same protocol. Because the composite is itself an IAddon, a composite may be a MEMBER of another composite, to arbitrary depth — the structure is a tree, not two layers. What is projected upward, and why the two halves differ: - DECLARATIONS (capabilities) are the union over EVERY member, initialized or not. A capability is a static claim about what the addon offers, and a host reads it for routing before anything is initialized. - CONTRIBUTIONS (tools, schema-extensions, hooks, excluded-tools) come from INITIALIZED members only. A member that failed to start must not advertise a tool it cannot serve; that is the difference between a degraded catalog and a lying one. Member failure is GRACEFUL by default, the same bargain hive-addon.mount already strikes: a member that fails to initialize is recorded, the rest still mount, and the composite reports :degraded rather than vanishing. Set :on-member-failure :fail to make any member failure fail the composite. Ordering is hive-addon.mount.solve, reused rather than reimplemented: a member may declare :member/depends-on over its siblings and the solver topologically orders them, with the same graceful cycle handling. Pure .cljc — no JVM-only construction path. Members arrive as INSTANCES, so the composite never resolves a ctor, reads a manifest or touches a classpath. A host that wants classpath discovery already has hive-addon.mount.compose; this namespace is what that machinery mounts INTO. Rationale lives in hive memory (KG-linked), not here.
(aggregate-tools members naming on-error)Fold member tool-defs into one surface.
:prefix (the default) qualifies every tool with its member's prefix, so a
catalog of siblings that all export render stays addressable. :flat
leaves names alone, which is what a curated catalog with no overlap wants.
Returns {:tools [tool-def] :collisions {name [member-id ...]}}. Collisions
are REPORTED, never silently resolved: under :flat two members claiming
one name is a real ambiguity, and dropping one of them quietly is how a
technique goes missing without anybody noticing.
Fold member tool-defs into one surface.
`:prefix` (the default) qualifies every tool with its member's prefix, so a
catalog of siblings that all export `render` stays addressable. `:flat`
leaves names alone, which is what a curated catalog with no overlap wants.
Returns `{:tools [tool-def] :collisions {name [member-id ...]}}`. Collisions
are REPORTED, never silently resolved: under `:flat` two members claiming
one name is a real ambiguity, and dropping one of them quietly is how a
technique goes missing without anybody noticing.(collisions named)Tool names claimed by more than one member, as {name [member-id ...]}.
Empty when the surface is unambiguous.
Tool names claimed by more than one member, as `{name [member-id ...]}`.
Empty when the surface is unambiguous.(composite id {:keys [members] :as opts})Build a CompositeAddon: one IAddon whose members are addons.
opts:
:members seq of IAddon instances or member maps (see
normalize-member). Malformed entries are dropped.
:capabilities capabilities the composite declares in its OWN right;
members' capabilities are unioned on top.
:addon-type default :native.
:tool-naming :prefix (default) or :flat — see aggregate-tools.
:on-member-failure :degrade (default) or :fail.
The returned addon is inert until initialize!; members are mounted then,
into a private IMountHost the composite owns.
Build a CompositeAddon: one IAddon whose members are addons.
opts:
:members seq of IAddon instances or member maps (see
`normalize-member`). Malformed entries are dropped.
:capabilities capabilities the composite declares in its OWN right;
members' capabilities are unioned on top.
:addon-type default :native.
:tool-naming :prefix (default) or :flat — see `aggregate-tools`.
:on-member-failure :degrade (default) or :fail.
The returned addon is inert until `initialize!`; members are mounted then,
into a private IMountHost the composite owns.(composite? x)True when x is a CompositeAddon. A host never needs this to MOUNT one —
it is an IAddon like any other — but a diagnostic that walks the tree does.
True when `x` is a CompositeAddon. A host never needs this to MOUNT one — it is an IAddon like any other — but a diagnostic that walks the tree does.
(fold-health statuses)Fold member health into the composite's.
:ok when every member is ok, :down when a composite that HAS members has
no working one left, :degraded in between. A composite with no members is
:ok — an empty catalog is empty, not broken.
Fold member health into the composite's. `:ok` when every member is ok, `:down` when a composite that HAS members has no working one left, `:degraded` in between. A composite with no members is `:ok` — an empty catalog is empty, not broken.
(live-members x)The members that INITIALIZED successfully, in mount order. [] before
initialize!, after shutdown!, or for a leaf addon.
This is the set whose contributions the composite actually projects upward, so it is also the honest answer to "what is this catalog serving right now".
The members that INITIALIZED successfully, in mount order. `[]` before `initialize!`, after `shutdown!`, or for a leaf addon. This is the set whose contributions the composite actually projects upward, so it is also the honest answer to "what is this catalog serving right now".
(member-ids x)The member ids of a composite, in declaration order. [] for a leaf addon,
so a caller can walk a mixed tree without type-testing first.
The member ids of a composite, in declaration order. `[]` for a leaf addon, so a caller can walk a mixed tree without type-testing first.
(members x)The member maps of a composite, in declaration order. [] for a leaf addon.
The instances, not just the ids: a diagnostic that walks the tree, or a
domain that asks each member whether it also satisfies some protocol of its
own, needs the objects. member-ids is this projected onto names.
The member maps of a composite, in declaration order. `[]` for a leaf addon. The instances, not just the ids: a diagnostic that walks the tree, or a domain that asks each member whether it also satisfies some protocol of its own, needs the objects. `member-ids` is this projected onto names.
(normalize-member m)Coerce one member into the canonical member map.
Accepts a bare IAddon instance, or a map carrying :member/addon plus any
of :member/id (defaults to the addon's own id), :member/config (merged
OVER the composite's config when that member initializes),
:member/depends-on (sibling ids, fed to the solver) and :member/prefix
(tool-name prefix override). Returns nil for anything that is not an addon,
so a malformed entry is dropped rather than throwing at construction.
Coerce one member into the canonical member map. Accepts a bare IAddon instance, or a map carrying `:member/addon` plus any of `:member/id` (defaults to the addon's own id), `:member/config` (merged OVER the composite's config when that member initializes), `:member/depends-on` (sibling ids, fed to the solver) and `:member/prefix` (tool-name prefix override). Returns nil for anything that is not an addon, so a malformed entry is dropped rather than throwing at construction.
(normalize-members ms)Normalize a seq of members, dropping the ones that carry no addon.
Normalize a seq of members, dropping the ones that carry no addon.
(order-members members)Order members by their declared :member/depends-on, via the mount solver.
Returns {:ordered [member] :cycles #{id} :duplicates {id count}}. Members
caught in a cycle are EXCLUDED from :ordered and reported, matching the
solver's graceful contract; the composite surfaces them as member failures.
Order members by their declared `:member/depends-on`, via the mount solver.
Returns `{:ordered [member] :cycles #{id} :duplicates {id count}}`. Members
caught in a cycle are EXCLUDED from `:ordered` and reported, matching the
solver's graceful contract; the composite surfaces them as member failures.(qualify-tool prefix tool)Prefix one tool-def's :name. A blank prefix leaves the name untouched.
Prefix one tool-def's `:name`. A blank prefix leaves the name untouched.
(tool-prefix id)The default tool-name prefix for a member id: its LAST dotted or slashed
segment, lowercased, with every other character folded to _.
"hive.prompt.chain-of-thought" -> "chain_of_thought". The last segment rather than the whole id because the host already namespaces the composite's own tools by the composite's id, so repeating the shared stem would spell every tool twice.
The default tool-name prefix for a member id: its LAST dotted or slashed segment, lowercased, with every other character folded to `_`. "hive.prompt.chain-of-thought" -> "chain_of_thought". The last segment rather than the whole id because the host already namespaces the composite's own tools by the composite's id, so repeating the shared stem would spell every tool twice.
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 |