hive-addon.lifecycle — io.github.hive-agi/hive-addon 1.0.8

Addon lifecycle boundary: mount on first use, release after idle, keep what is pinned, and release idle parts of what stays.

(def mgr (lifecycle/manager {:host h :specs specs :defaults {:policy :eager} :overrides {"hive.carto" {:policy :lazy :idle-ms 900000}} :surface-store (store/edn-dir-store dir)})) (lifecycle/boot! mgr) ; mounts eager, stubs dormant (lifecycle/install! mgr) ; dormancy oracle + the installed manager (lifecycle/start-sweeper! mgr)

A stub call runs activate!; a real handler runs inside with-use, which counts it in flight and touches the addon. sweep! evicts what the pure plan (hive-addon.lifecycle.policy/sweep-plan) allows and closes idle parts.

Activations and evictions are serialized by one reentrant lock. An eviction moves :active to :evicting only while nothing is in flight, and a use only starts on an :active addon, so no call runs on an addon being shut down.

activate! clj

(activate! mgr id)

Mount ID and every dependency it lacks. Idempotent: an active addon answers :already-active? true. Returns an ActivationReport.

active? clj

(active? mgr id)

adopt! clj

(adopt! mgr specs)

Govern SPECS that are ALREADY mounted (hot inject, a host's own boot) as active addons under the resolved policy. Returns the adopted ids.

boot! clj

(boot! mgr)

(boot! mgr {:keys [mount-eager?] :or {mount-eager? true}})

Mount what the policy says mounts at boot and stub the rest. OPTS {:mount-eager? false} records eager addons as active without mounting them, for a host that mounted them itself. Returns a BootReport.

call-with-use clj

(call-with-use mgr id f)

Call F with ID counted in flight. An ungoverned ID runs F untracked. A dormant ID is activated first; when that fails F is not called and the ActivationReport is thrown as ex-info.

default-lock-timeout-ms clj

default-sweep-interval-ms clj

dormant? clj

(dormant? mgr id)

True for an addon this manager governs that is not mounted.

evict! clj

(evict! mgr id)

(evict! mgr id {:keys [force?]})

Release ID: shut it down, withdraw its surface, advertise stubs. Refuses while it is in flight or an active addon depends on it. OPTS {:force? true} also evicts a pinned or eager addon. Returns an EvictionReport.

install! clj

(install! mgr)

Make MGR the installed manager and the source of the dormancy oracle.

installed-manager clj

(installed-manager)

manager clj

(manager {:keys [host specs] :as opts})

A lifecycle manager. OPTS: :host ILifecycleHost (required) :specs [MountSpec ...] every addon this manager governs :defaults LifecycleDecl applied under each manifest's own :overrides {addon-id LifecycleDecl}, strongest :surface-store ISurfaceStore for learned surfaces :now-ms (fn [] ms) :reload-ns! (fn [roots ns-strs] -> reloader answer) run before an activation mounts; default uses hive-hot when present :on-activated (fn [ids]) after addons become active :on-evicted (fn [id]) after an addon becomes dormant :lock-timeout-ms

mount-host clj

(mount-host mh)

(mount-host mh mount-opts)

An ILifecycleHost over an IMountHost. Stubs are kept in an atom ({id {:surface s :activate! f}}) readable as (:stubs host).

phase clj

(phase mgr id)

set-policy! clj

(set-policy! mgr id decl)

Change ID's lifecycle at runtime (e.g. pin it). Returns the new Lifecycle.

start-sweeper! clj

(start-sweeper! mgr)

(start-sweeper! mgr {:keys [interval-ms]})

Sweep every :sweep-interval-ms on a daemon thread. Idempotent.

state clj

(state mgr id)

status clj

(status mgr)

The manager as wire-safe data.

stop-sweeper! clj

(stop-sweeper! mgr)

surface-of clj

(surface-of mgr id)

[surface source] for ID: declared, else learned, else [nil :none].

sweep! clj

(sweep! mgr)

Evict every addon the sweep plan allows, then close idle parts. Returns {:plan SweepPlan :evicted [id ...] :refused {id reason} :parts {owner [part-id]}}.

sweep-plan clj

(sweep-plan mgr)

touch! clj

(touch! mgr id)

Mark ID used now.

tracked clj

(tracked mgr id f)

F wrapped so every call counts as a use of ID.

uninstall! clj

(uninstall!)

with-use clj macro

(with-use mgr id & body)

Run BODY with addon ID counted in flight (see call-with-use).