Files
archie/docs/prds/plugin-settings-live.md
T
sam a4abafe0ad docs(prds): decide the plugin live-reload open questions
Review of the plugin-settings reconcile PRD (F1-F8) returned REVISE: the doc
stated outcomes without making the decisions behind them. This revision makes
each one, so the PRD can carry the plugin live-reload work:

- ApplyMode is set to live and the gateway's version lag moves from the
  restart banner to the per-process applied-version rows.
- The skills_dir refusal gets a check site (a pre-layer comparison on the live
  path, not the value-agnostic validator), keeping #1143's validates-nothing
  intact.
- Records the four-directory coupling and why a whole-document refusal is
  acceptable.
- Justifies stop-then-start as a module's only check, and adds the refused
  dependent-replace outcome to the apply-status taxonomy.
- States that a reconcile tick re-runs layering and provider resolution, and
  what archie-gateway actually boots.
- Adds the Verification section.

Cited package paths re-checked against the tree; the control-plane
definitions now cite internal/app/controlplane/.
2026-10-02 03:10:18 +10:00

7.3 KiB

Plugin settings reconcile live

Status: Draft Revision: 2 Tracking: GitHub #1154, epic #998 Authority: docs/prds/runtime-control-plane.md decides each feature owns how its changes take effect; docs/architecture/plugins-and-extensions.md owns the plugin engine rule; docs/prds/control-plane-apply-status.md owns where apply reports go.

Outcome

An operator drops a plugin, module or secret-engine file into a configured directory while archied runs, and the daemon loads it without a restart. An edit to an installed file replaces what is running. A delete never stops running code; apply status says so. A stored plugin-settings change applies live for plugin_dir, module_dir and secret_engine_dir; a change to skills_dir is refused.

Triggers

PluginSettingsKind joins runtimeResourceKinds in internal/app/archied/control_plane.go, and its descriptor ApplyMode becomes live in internal/app/controlplane/operational_settings.go.

A poller reconciles on the apply-status restamp interval, so a dropped file loads without a filesystem watch. Each tick re-runs both halves the boot path runs, against the directories in the running config: the directory loads (secret.Registry.LoadDir, ModuleRegistry.Register, plugin.LoadDir) and the layering (boot.runtimeConfig), which re-resolves provider credentials. A provider disabled at boot for an unresolvable engine is re-resolved on the first tick that finds it; a changed directory retargets the next tick without a restart.

Rules

  • Adding and changing load; removing never unloads. Yaegi interpreters are not reclaimed while a caller still exists and there is no unload path; the running set can only grow. A removal stays outstanding in the apply-status error until the process restarts.
  • Each file is loaded through a fresh interpreter (the boot pattern) and content-hashed, so only new and changed files load.
  • A file that fails to load is skipped and reported; already-running code keeps running, the degrade-and-skip convention plugin.LoadDir and Registry.LoadDir already apply at boot. Boot keeps its reject-at-load rule for the module directory; a broken file at runtime skips without aborting.
  • A directory that does not exist reconciles to an empty set.

The three registries

  • Secret engines (internal/secret). Reconciliation re-runs Registry.LoadDir against the live directory. Register replaces by name, so an edited engine takes effect for the next resolution and a dropped engine resolves on the next tick. A deleted engine stays registered: existing references keep resolving through it until restart. Engines are stateless resolvers, so a swap needs no lifecycle step.
  • Modules (internal/domain/eda/module). Reconciliation re-runs ModuleRegistry.Register for the kind's file. Playbook dispatch resolves through the registry at invoke time, so the swap reaches a running playbook store unchanged; a deleted file leaves the old invoker in place, running.
  • Plugins (internal/plugin). Host grows running-state operations beside Register, Start and Stop, and Register keeps its rule that registration is allowed only before the first Start, so these are new host methods rather than a relaxed Register. One adds a single module while the host is running: inserted in dependency order, started alone, and rolled back alone on failure, leaving every previously started module running. The other replaces a module whose manifest id matches: stop it, start the new one, and restart the old one when the new start fails; replacing a module another running module depends on is refused. A module's Start is its only check (plugin.Module has no probe, and one manifest id cannot be registered twice), so a replacement checks by starting and keeps a rollback rather than switching first. These operations obey the plugin engine rule: the host invokes start and stop itself and isolates the failure to one module. A deleted file makes no host call: the module runs on.

skills_dir

skills_dir is not part of this change. The daemon refuses a plugin-settings document whose skills_dir differs from the value in force. The check is a pre-layer comparison on the live path (boot.applyRuntimeResourceUpdate in internal/app/archied/control_plane.go), not an addition to validatePluginSettings in internal/app/controlplane/operational_settings.go, which stays value-agnostic per the #1143 decision recorded there: a change-immutability rule needs the running config, and #1143's validates-nothing still holds for values. The write lands, the store keeps the version, the daemon publishes nothing, the refusal is reported against that stored version, and last-known-good keeps running.

The layering assigns all four directories from one document, so a refused skills_dir refuses the whole document and the other kinds still layer. That is acceptable: skills_dir is the one field with no live consumer, a whole-document refusal is the honest signal that none of it took effect, and an operator changing skills_dir alongside another directory writes the two changes separately.

Apply status

One record per process: archied on plugin-settings, reported against the version the process is running. The record's error field carries the outstanding problem: a deleted file still running, a file that failed to load, the directory failing to read, or a refused replace of a module another running module depends on. A clean reconciliation clears the error. An add that succeeded is live even while a removal is outstanding, and the error says so rather than showing the kind as restart-required.

ApplyMode becomes live, so RestartPendingBanner no longer names plugin-settings. The gateway's lag is shown instead by the per-process applied-version rows on the Plugins page, which read the state applyStatusForKind derives from applied_version < storedVersion in ui/src/stores/control-plane.ts; that derivation is independent of ApplyMode.

archie-gateway layers the plugin-settings document at boot through boot.loadRuntimeConfig and reports it, but never calls boot.loadPlugins or boot.loadModules and never reads the four directories, so it loads no plugin, module or secret engine. With no live watch its row lags the stored version until restart; that lag is a reporting lag, not a behaviour gap.

Verification

  • A plugin, module and secret-engine file dropped while the daemon runs loads on the next tick; an unchanged file is not reloaded.
  • An edited file replaces the running interpretation; a deleted file leaves the running code running, with the process's error naming it until restart.
  • A skills_dir change refuses the document: the store keeps the version, the record carries that version and the refusal, and the running skills_dir is unchanged.
  • A plugin replacement whose new Start fails restarts the old module and reports the failure; a replacement of a depended-on module is refused and the dependent keeps running.
  • A provider disabled at boot for a missing engine resolves again after the engine file loads and a tick re-layers.
  • The gateway reports the last version it layered at boot, loads no directory, and its lag appears in its applied-version row rather than the restart banner.