Service Provider Interface (SPI) protocol contracts for hive workflows.
This library is pure protocol definitions — no implementations, no runtime state, no third-party deps. It exists so that consumers can depend on stable contracts rather than concrete implementations.
The seam is grouped by domain, one namespace per family. Every protocol below is part of the 1.0 contract.
| Namespace | Protocols |
|---|---|
hive-spi.workflow.engine |
IWorkflowEngine, IWorkflowPersistence |
hive-spi.workflow.strategy |
IDispatchStrategy |
hive-spi.memory.ports |
IMemoryStore + 7 optional extensions (analytics, metadata-write, staleness, batch, routing, temporal, liveness) |
hive-spi.kg.protocol |
IKGStore, IPersistentKGStore, ITemporalKGStore |
hive-spi.kg.factory |
IStoreFactory |
hive-spi.kg.conn-init |
IConnInit |
hive-spi.addon.headless |
IHeadlessBackend, IHeadlessCapabilities |
hive-spi.addon.headless-caps |
IHookable, ICheckpointable, ISubagentHost, IBudgetGuardable |
hive-spi.editor.ports |
IEditorPort (required) + IEditorBufferPort, IEditorDocsPort, IEditorDaemonPort (optional) |
hive-spi.cider.ports |
ICiderPort |
hive-spi.guard.ports |
IGuardRuleSource, IGuard, IGuardProjection |
hive-spi.diag.ports |
IHeapProbe, IRetainedSizer, IAllocationSampler, IProfiler, ICacheProbe, IMemoryClinic |
hive-spi.lifecycle.ports |
IShutdownHook, ISweepable, IResourceOwner, IShutdownBudget |
hive-spi.embeddings.ports |
EmbeddingProvider |
hive-spi.crypto.hash / .ports |
IHasher, ISigner |
hive-spi.log.ports |
ILogger |
hive-spi.time.ports |
IClock |
hive-spi.notify |
INotify |
hive-spi.slot |
ISlot, IRegistry |
hive-spi.ingest.ports |
ISource (required) + ISourceHealth, IParserRule (optional); hive-spi.ingest.model carries the Document they promise, hive-spi.ingest.registry the owner-scoped registry, hive-spi.ingest.tck the public conformance kit. Guide: resources/hive_spi/writing-an-ingest-provider.md |
A protocol marked optional is one an implementation may leave unextended:
callers must probe with satisfies? rather than assume it.
Two shapes, for two different questions.
src/hive_spi/slot.cljc — a mutable holder. Use it when the injection
point is the process: one active implementation (single-slot) or a keyed map
of them (multi-slot), installed at boot and read from anywhere.
src/hive_spi/provider.cljc — an immutable registry of providers as data.
Use it when two of them must coexist: a request and its test, a tenant and
another tenant. A provider is an implementation plus a profile — plain data
describing its measured behaviour — and the registry is a value threaded
through a call rather than a global installed into.
(require '[hive-spi.provider :as provider])
(def RailProfile
(provider/profile-schema [[:provider/currency :keyword]]))
(def rails
(provider/registry [(provider/entry #:provider{:id :chain
:currency :xmr
:capabilities #{:poll}}
(chain-rail config))
(provider/entry #:provider{:id :cards :currency :usd}
(card-rail config))]
{:schema RailProfile
:satisfies-port? #(satisfies? IRail %)}))
;; the SUBJECT selects its provider; a caller cannot substitute one
(provider/via rails invoice :invoice/provider #(charge! % amount))
;; and a provider is never asked to do what its profile does not admit
(provider/via-capable rails invoice :invoice/provider :poll #(poll % invoice))Three rules the API enforces rather than documents:
- Profiles are validated at registration — a malformed provider fails at boot, where an operator is watching, not at the first caller.
- Capability is read off the profile, never inferred from the id. Adding a provider is an entry in a registry, not a branch in a component.
- A subject selects its provider.
for-subject/viatake the id from the subject, so a caller naming a provider is stating a claim to be checked — never the authority that resolves it.
conformance / conforming? are the Liskov check for a test: every registered
implementation is substitutable for the port, and every profile means what its
schema says.
hive-spi/
├── deps.edn
├── .hive-project.edn
├── src/hive_spi/slot.cljc (mutable injection points)
├── src/hive_spi/provider.cljc (providers as data, registry as a value)
├── src/hive_spi/schema/ (capability, derive, gen, help, registry, typed)
├── src/hive_spi/<domain>/ports.cljc (one port family per domain, see Ports)
└── test/hive_spi/ (a conformance suite per port family)
From 1.0.0 this library follows Semantic Versioning.
The public contract is: the protocol names and their method signatures, the
schemas in hive-spi.schema.*, and the slot / provider injection APIs.
- Removing a protocol, renaming a method, or changing an existing method's arity or argument order is a major change.
- Adding a protocol, or adding an optional extension protocol, is a minor change: existing implementations keep satisfying what they already satisfied.
- Adding a method to an existing protocol is a major change, because every implementation must grow it. New behaviour arrives as a new optional protocol instead.
The library carries no third-party runtime dependencies, so a consumer's version conflicts can never come from here.