Skip to content

Commit ba6ae64

Browse files
Copilothotlong
andcommitted
docs: update PROTOCOL_MAP.md and PLUGIN_STANDARDS.md with plugin system enhancements
- PROTOCOL_MAP.md: add plugin-runtime.zod.ts entry with ⭐ status, update descriptions for plugin-loading.zod.ts, plugin-lifecycle-advanced.zod.ts, and plugin-security-advanced.zod.ts - PLUGIN_STANDARDS.md: add Section 5 "Plugin Runtime Capabilities" covering hot reload (5.1), plugin isolation (5.2), dynamic loading (5.3), and full system assessment summary table (5.4) Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent a4a3688 commit ba6ae64

2 files changed

Lines changed: 67 additions & 3 deletions

File tree

packages/spec/PLUGIN_STANDARDS.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,66 @@ To help AI understand the "intent" of a file, use a standard JSDoc header.
116116
*/
117117
export const LeadObject = ...
118118
```
119+
120+
---
121+
122+
## 5. Plugin Runtime Capabilities
123+
124+
The microkernel architecture provides the following runtime capabilities for plugins. The Zod schemas governing each capability live in `src/kernel/`.
125+
126+
### 5.1 Hot Reload (`plugin-loading.zod.ts``PluginHotReloadSchema`)
127+
128+
Hot reload supports **development, staging, and production** environments. The `environment` field controls the safety level:
129+
130+
| Environment | Behavior |
131+
| :--- | :--- |
132+
| `development` | Fast reload with file watchers, no health validation required |
133+
| `staging` | Production-like reload with validation but relaxed rollback |
134+
| `production` | Full safety: health validation, auto-rollback, connection draining |
135+
136+
Production safety features (`productionSafety`):
137+
- **Health validation** — run health checks after reload before accepting traffic
138+
- **Rollback on failure** — auto-rollback if reloaded plugin fails health check
139+
- **Connection draining** — gracefully drain active requests before reloading
140+
- **Concurrency control** — limit concurrent reloads (`maxConcurrentReloads`)
141+
- **Reload cooldown** — minimum interval between reloads of the same plugin (≥1s)
142+
143+
### 5.2 Plugin Isolation (`plugin-loading.zod.ts``PluginSandboxingSchema`)
144+
145+
Sandboxing supports configurable **scope** and **isolation level**:
146+
147+
| Scope | Description |
148+
| :--- | :--- |
149+
| `automation-only` | Sandbox automation/scripting plugins only (default) |
150+
| `untrusted-only` | Sandbox plugins below a trust threshold |
151+
| `all-plugins` | Sandbox all plugins for maximum isolation |
152+
153+
Isolation levels: `none`, `process`, `vm`, `iframe`, `web-worker`.
154+
155+
**Inter-Plugin Communication (IPC):** Isolated plugins communicate with the kernel and other plugins via configurable IPC:
156+
- Transports: `message-port`, `unix-socket`, `tcp`, `memory`
157+
- Configurable message size limit, timeout, and service ACL (`allowedServices`)
158+
159+
### 5.3 Dynamic Loading (`plugin-runtime.zod.ts`)
160+
161+
Plugins can be loaded and unloaded at runtime **without restarting the kernel**:
162+
163+
- **`DynamicLoadRequestSchema`** — Load a plugin from `npm`, `local`, `url`, `registry`, or `git` sources with optional integrity verification
164+
- **`DynamicUnloadRequestSchema`** — Graceful/forceful/drain unload with dependency awareness (`cascade`, `warn`, or `block` dependents)
165+
- **`ActivationEventSchema`** — Lazy activation triggers: `onCommand`, `onRoute`, `onObject`, `onEvent`, `onService`, `onSchedule`, `onStartup`
166+
- **`PluginDiscoveryConfigSchema`** — Runtime discovery from registries and local directories with polling and trust filtering
167+
- **`DynamicLoadingConfigSchema`** — Subsystem configuration: max dynamic plugins, default sandbox policy, allowed sources, integrity requirements
168+
169+
### 5.4 Plugin System Assessment Summary
170+
171+
| Capability | Status | Schema / Details |
172+
| :--- | :--- | :--- |
173+
| Plugin Registration || `manifest.zod.ts``objectstack.config.ts` plugin array, ordered initialization |
174+
| Lifecycle Hooks || `plugin.zod.ts``init()``start()``healthCheck()``destroy()` |
175+
| Service Registry || `service-registry.zod.ts` — 17 services across 13 plugins via `ctx.registerService()` |
176+
| Event Bus || `events.zod.ts` — Pub/sub with pattern matching |
177+
| Dependency Resolution || `plugin-loading.zod.ts` — Declared dependencies with conflict resolution |
178+
| Health Checks || `plugin-lifecycle-advanced.zod.ts` — Per-plugin health + system aggregation |
179+
| Hot Reload || `plugin-loading.zod.ts` — Dev + production-safe with rollback and draining |
180+
| Plugin Isolation || `plugin-loading.zod.ts` — Configurable scope + IPC for process boundaries |
181+
| Dynamic Loading || `plugin-runtime.zod.ts` — Runtime load/unload with activation events and discovery |

packages/spec/PROTOCOL_MAP.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,12 +208,13 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
208208
| [`feature.zod.ts`](src/kernel/feature.zod.ts) | | **Feature Flags**. Toggleable system features. |
209209
| [`service-registry.zod.ts`](src/kernel/service-registry.zod.ts) | | **Service Registry**. Internal dependency injection. |
210210
| [`metadata-loader.zod.ts`](src/kernel/metadata-loader.zod.ts) | | **Loader**. Logic for loading definitions from disk/DB. |
211-
| [`plugin-loading.zod.ts`](src/kernel/plugin-loading.zod.ts) | | **Plugin Loading**. Phases of plugin initialization. |
211+
| [`plugin-loading.zod.ts`](src/kernel/plugin-loading.zod.ts) || **Plugin Loading**. Loading strategies, production-safe hot reload (`environment`, `productionSafety`), full plugin sandboxing (`scope`, `ipc`), code splitting, caching, and performance monitoring. |
212+
| [`plugin-runtime.zod.ts`](src/kernel/plugin-runtime.zod.ts) || **Dynamic Loading**. Runtime load/unload of plugins (`DynamicLoadRequest`, `DynamicUnloadRequest`), activation events, plugin discovery from registries/directories, and source resolution (npm/local/url/registry/git). |
212213
| [`plugin-versioning.zod.ts`](src/kernel/plugin-versioning.zod.ts) | | **Versioning**. Semantic versioning rules for plugins. |
213214
| [`plugin-validator.zod.ts`](src/kernel/plugin-validator.zod.ts) | | **Validation**. Integrity checks for plugins. |
214215
| [`plugin-structure.zod.ts`](src/kernel/plugin-structure.zod.ts) | | **Structure**. Zod rules for folder layout and file naming. |
215216
| [`plugin-capability.zod.ts`](src/kernel/plugin-capability.zod.ts) | | **Capabilities**. What a plugin can do. |
216217
| [`plugin-lifecycle-events.zod.ts`](src/kernel/plugin-lifecycle-events.zod.ts) | | **Lifecycle Events**. Hooks for plugin state changes. |
217-
| [`plugin-lifecycle-advanced.zod.ts`](src/kernel/plugin-lifecycle-advanced.zod.ts) | | **Advanced Lifecycle**. Deep lifecycle hooks. |
218-
| [`plugin-security-advanced.zod.ts`](src/kernel/plugin-security-advanced.zod.ts) | | **Advanced Security**. Sandboxing and isolation. |
218+
| [`plugin-lifecycle-advanced.zod.ts`](src/kernel/plugin-lifecycle-advanced.zod.ts) | | **Advanced Lifecycle**. Health monitoring, hot reload state management, graceful degradation, and update strategies. |
219+
| [`plugin-security-advanced.zod.ts`](src/kernel/plugin-security-advanced.zod.ts) | | **Advanced Security**. Permission system, sandbox configuration (V8/WASM/container/process), security scanning, and trust levels. |
219220
| [`startup-orchestrator.zod.ts`](src/kernel/startup-orchestrator.zod.ts) | | **Startup**. Boot sequence orchestration. |

0 commit comments

Comments
 (0)