hive-addon.hot.schema — io.github.hive-agi/hive-addon 1.1.7

Malli value objects for the IAddon hot-reload bridge.

Shapes are uncompiled malli DATA (house idiom: PascalCase defs) seeded into a LOCAL composite registry that COMPOSES hive-addon.mount.schema's registry — AddonId/MountResult/MountSpec are reused, never redefined. The registry is NEVER installed as the malli global default; reach it via schema/validate/explain/validate* or by passing {:registry registry}.

Hot shapes are registered under :hot/* keys (:hot/registration, :hot/report, :hot/remount-report, :hot/inject-report, :hot/eject-report, :hot/source, :hot/strategy-id, :hot/remount-outcome).

Two invariants are carried as DATA rather than prose:

• The reports' :teardown/data-preserved? is a :boolean VERDICT computed by hive-addon.hot.report/data-preserved? over the teardowns that actually released something — never true by construction. (The per-teardown TeardownReport in hive-addon.mount.schema still pins [:= true]: that is the no-nuke claim a teardown makes; the report verdict is whether every release made it.)
• :hot/strategy-id is an open :keyword, never an enum. The strategy set is extensible by any module (OCP); closing it here would be the defect.

AddonIdSet clj/s

A set of addon ids — a reload's seed set, and the closure it produces.

AddonSource clj/s

Resolved physical source of an addon's constructor namespace. :hot/reloadable? is the decision derived from :hot/source-kind — true only for :directory. Open.

DependentsArgs clj/s

Arglist of hive-addon.hot.cascade/dependents: the specs, then the seed ids. A :cat schema, so a schema-driven test applies the subject rather than passing the pair as one argument.

DrainReport clj/s

What hive-addon.hot.drain/drain! answers: the ids whose gate it closed, the calls still in flight when the wait ended ({id n}, empty when drained), how long it waited and the bound it waited under. Open.

EjectReport clj/s

Outcome of plugging addons OUT of a running host (hive-addon.hot.inject/eject!) — what was removed, and what STAYS.

Removed: :hot/torn-down (shut down, reverse order), :hot/unregistered (dropped from the host registry through IMountUnregister), :hot/ungoverned (no longer governed by the installed lifecycle manager), :hot/unhot (deregistered from hive-hot), :hot/dirs-removed (no longer watched), :hot/forgotten (dropped from the injected-spec registry).

Stays — reported, because a caller must not assume it went: :hot/unsupported ids whose host has no IMountUnregister and still holds an inert, shut-down entry. :hot/dirs-retained source dirs still watched: shared with a surviving addon, a core dir hive-hot's initial init declared, one another owner still claims (then under :hot/dirs-shared {dir [owner]}), or hive-hot offers no remove-dirs! (see :hot/dirs-reason). :hot/classpath-retained URLs that stay on the DynamicClassLoader. A java.net.URLClassLoader cannot drop a URL; the code stays loadable until the JVM restarts. :hot/namespaces-retained constructor namespaces still loaded in the image.

:hot/refused? with :hot/blocking lists active dependents that stopped the ejection (pass :cascade? true to take them down and remount them without the ejected sibling; they are then under :hot/remounted and :mounted).

:hot/drain is the DrainReport of the wait for calls in flight that ran before any teardown. :hot/busy? true means calls were still running when :drain-ms ran out, so nothing was torn down and the gate was re-opened; :hot/forced? true means the eject went ahead anyway under :force? true. :teardown/data-preserved? is computed over the teardowns that ran. Open.

explain clj/s

(explain ?s x)

Registry-aware explain — nil on success, error map on failure.

HotRegistration clj/s

One addon's registration into the hive-hot component registry. :hot/component-id is the key hive-hot knows it by; :addon/init-ns is the namespace whose reload triggers the strategy named by :hot/strategy-id. Open.

HotReport clj/s

Outcome of wiring a spec set into hive-hot. :hot/available? is false when hive-hot is absent from the classpath — the bridge then degrades to a no-op report rather than throwing, so a consumer without hive-hot still works. :hot/dirs is the watchable source-dir set derived from the specs (what a consumer feeds hive-hot's :dirs). :ok? is true only when every spec registered. Open.

HotTrigger clj/s

What caused a reload. :manual is an explicit call (an operator, or the hive hot reload <addon-id> MCP command); :ns-reload is a hive-hot component callback; :file-change is watcher-driven.

humanize-errors clj/s

(humanize-errors ?s x)

Human-readable error data for x against ?s, or nil if x conforms.

InjectReport clj/s

Outcome of injecting addons that were not on the classpath at boot (hive-addon.hot.inject/inject!).

:hot/paths are the classpath entries the path stood for and :hot/classpath what extending the live loader with each answered. :hot/discovered is every addon whose manifest lives under those paths; :hot/already-mounted the ones the host already had (left alone — injection never resurrects or replaces), :hot/injected the ones actually mounted. :hot/affected is the ordered slice that ran: the injected addons plus every ALREADY-MOUNTED dependent that now has a new sibling to receive, which is torn down and remounted (listed in :hot/torn-down). :mounted carries the per-addon MountResult from the ordinary mount pipeline. :hot/dirs-added are the source dirs handed to hive-hot so the new addons reload like the rest; :hot/registered the ids registered as hive-hot components. :hot/specs are the injected specs as mounted, each stamped with :hot/source-dirs — what the host keeps as their effective specs, so a later reload is scoped to those dirs on any thread. :hot/remembered are the ids recorded in the injected-spec registry (so discovery from ANY thread sees them), and :hot/adopted the ids the installed lifecycle manager now governs under their manifest policy. :teardown/data-preserved? is computed over the dependent teardown that ran. Open.

MountSpecs clj/s

The mounted manifest slice a reload reasons over.

NsReloadOutcome clj/s

What hive-addon.hot.port/INsReloader's -reload-nss! reports. :failed names the namespace a reload stopped at; its absence means every namespace loaded. A scoped reloader may add :skipped / :dragged (namespaces changed outside its roots, declined / loaded as dependents), :unchanged? and :multi-file.

registry clj/s

Composite malli registry: hive-addon.mount.schema's registry (malli defaults + :addon/* + :mount/* schemas) plus this ns's :hot/* schemas. NOT installed as the global default — reach it via the wrappers below or {:registry registry}.

RemountOutcome clj/s

What hive-addon.hot.report/remount-outcome answers: which torn-down ids are back on their PREVIOUS instance, which are down, and — only when something failed — whether everything is running again.

RemountOutcomeArgs clj/s

Arglist of hive-addon.hot.report/remount-outcome: the ids a remount tore down, then the MountReport that followed.

RemountReport clj/s

Outcome of reloading an addon and its transitive dependents.

:hot/seeds are the directly-changed addon ids; :hot/affected is the topo-ordered closure actually acted on (deps before dependents) and always CONTAINS the seeds. :hot/torn-down is the reverse-order shutdown that ran first. :mounted carries the per-addon MountResult from the ORDINARY mount pipeline — hot-reload is a projection of mount!, not a second registry.

:hot/roots are the seeds' classpath source dirs the namespace reload was scoped to. :hot/ns-reloaded names every namespace the reloader loaded; :hot/ns-skipped the namespaces changed OUTSIDE the roots that it declined (they stay pending for their own root), :hot/ns-dragged the ones changed outside but loaded because they depend on a reloaded namespace, and :hot/ns-unchanged? that nothing under the roots had changed at all. :hot/widened is the addon ids that joined :hot/affected because their constructor namespace was loaded — absent when the reload stayed inside the requested slice, so "nothing else changed" and "other addons were dragged in" are distinguishable.

:hot/multi-file names a loaded namespace found in more than one file, and :hot/stale-ctors the namespaces the reload reported loaded whose constructor var provably did not change — both are the "reloaded, but the code did not" shape, and the second REFUSES the remount.

What is RUNNING afterwards is stated, not left to inference: :hot/refused? true means the remount was declined before any teardown (:hot/preflight carries the dry-run results that refused it); :hot/restored are ids whose new instance failed and whose PREVIOUS instance is live again; :hot/down are ids with neither. :hot/restored? is present only when something failed, true exactly when nothing is down.

:hot/strategy names the strategy that ran. :teardown/data-preserved? is a COMPUTED verdict (hive-addon.hot.report/data-preserved?) over the teardowns that released something — no longer true by construction. Open.

schema clj/s

(schema ?s)

Compile ?s against the local :hot/* + :mount/* + :addon/* registry.

SourceKind clj/s

Where an addon's constructor namespace physically lives, which decides whether its code can be reloaded at all.

:directory — a real directory on the classpath (a :local/root dep, or this repo's own src). clj-reload can watch and reload it. :jar — inside a JAR (an :mvn/version dep). The bytes cannot change without a restart, so hot-reload is meaningless. :absent — the namespace's source file is not on the classpath at all.

StrategyId clj/s

Identifier of a reload strategy. OPEN on purpose — modules register their own strategies (OCP), so this is a plain keyword, never an enum.

TeardownOutcome clj/s

What hive-addon.hot.port/IMountDriver's -teardown! reports.

validate clj/s

(validate ?s x)

Registry-aware validate — true/false.

validate* clj/s

(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 :hot/schema-violation and must be a qualified keyword (hive-dsl taxonomy convention).