hive-addon.mount.boundary — io.github.hive-agi/hive-addon 1.1.7

Effectful boundary of the addon mounter — all IO and var resolution, injected through the IMountHost port and an optional config resolver.

Collect: discover-specs scans the classpath for META-INF/hive-addons/*.edn (the no-arg arity unions in the injected-spec registry, so an addon injected from another thread's loader is still discovered). Promote: parse-spec turns an EDN string into a validated MountSpec Result. Pipeline is hive-addon.mount.solve (pure, elsewhere). Boundary: mount!/dry-run/teardown!/unregister! resolve constructors, inject already-mounted sibling instances into each dependent's config (DIP), and drive the host.

mount! GRACEFULLY DEGRADES: a spec that fails at any step is recorded in the MountReport and the loop CONTINUES; already-mounted addons are NEVER torn down on a mid-DAG failure. Given :fallback-instance, a failed spec's PREVIOUS instance is put back in order (:restored?). teardown! shuts down in reverse mount order and reports :teardown/data-preserved? true (shutdown! never deletes data). unregister! plugs torn-down addons out through the optional IMountUnregister port and reports hosts without it as :unsupported.

default-init-retry clj

Default bounded initializer retry policy. :max-attempts counts the first call.

discover-specs clj

(discover-specs)

(discover-specs classloader)

Scan the classpath for META-INF/hive-addons/*.edn and parse each into a MountSpec. Returns {:specs [MountSpec] :errors [{:url .. :errors ..}]}. Result-guarded: a bad file becomes an :errors entry, never aborts the scan.

The no-argument arity is the IMAGE's view: the calling thread's context loader UNIONED with the injected-spec registry (hive-addon.mount.injected), so an addon injected from another thread's DynamicClassLoader is still discovered here. The classpath wins a tie by id. Passing a classloader explicitly asks for exactly that loader's manifests and nothing else.

dry-run clj

(dry-run plan host)

(dry-run plan _host {:keys [license-gate resolve-program]})

Compute the MountReport that mounting would produce WITHOUT any effects: no construction, registration, or initialization. Applies the licence gate and resolves each ctor read-only, marking a spec :phase :skipped :success? true when it would mount, :phase :entitlement when the gate refuses, else :phase :resolved :success? false. Golden-replay parity: for an all-success plan, dry-run :order and :mounted ids equal mount! :order and :mounted ids. A host may supply :resolve-program (name -> path or nil) to report declared executable prerequisites; missing programs fail the preview before ctor load.

mount! clj

(mount! plan host)

(mount! plan
        host
        {:keys [resolve-config resolve-program init-retry on-event sleep-fn
                license-gate peer-specs provision fallback-instance]
         :or {resolve-config port/resolve-config-default
              init-retry {}
              on-event (constantly nil)
              sleep-fn (fn [ms] (Thread/sleep (long ms)))}})

Mount every spec in (plan :ordered) into host, in order. Returns a MountReport. For each spec: check the licence gate, resolve ctor, build config via resolve-config then inject already-mounted sibling instances under :mount/dependencies, construct, verify IAddon, register!, init!. Any failure is recorded and the loop CONTINUES — already-mounted addons are NEVER torn down (graceful degrade). :ok? is true only when every attempted spec succeeded.

opts: {:resolve-config (fn [spec] -> config-map) (default resolve-config-default) :resolve-program (fn [program-name] -> path | nil) — host executable lookup; absent fails closed for declared requirements :init-retry retry-policy override :license-gate ILicenseGate or (fn [spec] -> nil | reason) (default: the installed gate) :peer-specs the spec set used to resolve each spec's dependencies for sibling injection (default: the plan's own :ordered) :provision (fn [spec instance] -> ProvisionReport | nil), run after an addon initializes; its report lands on the result as :runtime (see hive-addon.runtime.boundary/provisioner) :fallback-instance (fn [spec] -> IAddon | nil) — the instance SPEC's addon had BEFORE this mount (a remount's snapshot). When the new one fails, that instance is put back and re-initialized IN ORDER, so the dependents mounted after it receive a live sibling. The result keeps :success? false and gains :restored? (and :restore/errors when putting it back failed too); the report lists them under :restored. A licence refusal is never restored around. :on-event (fn [event-map]) :sleep-fn (fn [milliseconds])}.

:peer-specs exists for mounting a SLICE of a larger system — a hot-reload remounts only the affected addons, but their capability-providing siblings live outside that slice. Resolving dependencies against :ordered alone would silently drop those siblings from :mount/dependencies, handing the remounted addon a thinner config than its original mount got.

parse-spec clj

(parse-spec edn-string)

Parse an EDN manifest string into a validated MountSpec. (r/ok MountSpec) on success; (r/err :mount/spec-invalid {:explanation ..}) on a read error or schema violation.

resolve-constructor clj

(resolve-constructor spec)

Resolve a MountSpec constructor without erasing load failures.

Returns tagged resolution data. :absent means no such var; :failed means requiring the constructor namespace threw (including compiler/load order failures); :invalid means the var exists but is not callable. Never throws ordinary Exceptions.

resolve-programs clj

(resolve-programs spec resolve-program)

Resolve every declared executable through the host-supplied resolver, without invoking a shell. Returns the per-program locations and missing names as data. A nil resolver is intentionally fail-closed for nonempty requirements.

teardown! clj

(teardown! host addon-ids)

(teardown! host addon-ids {:keys [deprovision]})

Shut down addon-ids in REVERSE order via (port/shutdown! host id). Returns a TeardownReport. :teardown/data-preserved? is always true (shutdown! never deletes data); a shutdown that throws is recorded in :errors but the flag stays true — we did not delete.

opts: {:deprovision (fn [addon-id] -> ProvisionReport | nil)}, run after each addon shuts down to remove the client runtime a provisioner installed for it. Reports that ran land under :runtime keyed by addon id. Generated runtime files are not addon data, so the no-nuke flag is unaffected.

unregister! clj

(unregister! host addon-ids)

Drop ADDON-IDS from HOST's registry, AFTER they were torn down. Goes through hive-addon.mount.port/IMountUnregister; a host that does not implement it is not an error — every id is reported under :unsupported, which tells the caller the host still holds an inert (shut-down) entry for it.

Returns {:unregistered [id] :unsupported [id] :errors [string]}. Never throws.