change-plugin-runtime

Change the Plugin Runtime

Trace the Single Contract

1. Read Plugin documentation and the focused contract for the affected area.
2. Start with source types in packages/plugin, then plugin-kit build output, host discovery/install under packages/plugin-host/src/plugin, runtime generation/dispatch under plugin-runtime, server routes, and the Web host under apps/web/src/plugin.
3. Trace definePlugin() → generated manifest/artifacts → metadata-only validation → approval review → installation transaction → contribution adapter → lazy runtime generation → invocation context/Host Service → disposer or lifecycle cleanup.
4. Load change-execution-boundaries for host capability enforcement, change-server-api for routes/SDK, change-persistence for lock/approval/config migration, and develop-frontend for the Web host.

Preserve the Architecture

1. definePlugin() is the only source of identity, compatibility, capabilities, contributions, and handlers. Do not add a source manifest, handler map, or nested permission tree. Preserve the frozen API-family decoder and its single boundary adapter rather than adding runtime compatibility branches.
2. Keep plugin ID identical across package name, artifact basename, manifest, registry, lockfile, approval, runtime generation, asset URL, and UI surface namespace. manifest.name is display text and must not participate in identity checks or artifact naming.
3. Validate generated metadata, paths, hashes, and approval before importing executable code. Derive manifest and permissions hashes only through @ericsanchezok/synergy-plugin/integrity; plugin-kit, marketplace publication, installation, and approval must not maintain private payload or canonical JSON implementations. The manifest hash protects identity/integrity and review freshness; user authorization is the structured publisher/access grant. Approval reviews are server-authoritative: clients fetch the current review, submit only target plus opaque reviewToken, and rely on the server to bind the canonical target to the current manifest hash, permissions hash, source, and signer. Stale reviews return a refreshed review without writes.
4. Treat API4 as the stable family: do not delete, rename, narrow, or change the meaning of stable public fields, contribution kinds, Host Services, hooks, or types. Plugin and plugin-kit npm package versions follow the Synergy product release version, while additive releases keep apiVersion: "4.0"; plugins raise compatibility.synergy only when using a newer host addition. Intersect every alternative of host and plugin compatibility ranges, including current and historical release lines; test the first supporting release and rejection below an explicit feature minimum. Keep deprecated stable APIs implemented and typed. experimental.* is excluded from this promise. Adding a Host Service method, hook point, or contribution kind is not by itself a transport change. Keep the runtime protocol version unchanged unless the IPC envelope or handshake semantics actually change. Any real protocol revision requires a frozen executable artifact from the previous release, a host compatibility test, and an explicit negotiation or transition strategy before implementation. The running host owns the selected protocol version. A process Runner echoes the activation value in ready rather than re-reading a mutable source-tree constant, so plugin-only development reloads cannot mix a stale host selection with newer Runner files.
5. Reconfirm only a first non-policy install, added/broadened access, unknown constraint change, or publisher/source change. Equal/narrower same-publisher updates refresh the grant silently. Do not compute or present an overall plugin risk rating. Keep runtime capability/permission/sandbox enforcement intact.
6. Keep contribution kinds flat and adapter-owned. Adding a kind means adding its public type/schema, adapter, validation, lifecycle disposal, and tests—not a branch in a central registration loop.
7. Treat generated operation, event, and tool JSON Schema as canonical metadata. Plugin-kit must convert live Zod schemas inside the definition-loader child before the descriptor crosses its JSON process boundary; never serialize Zod internals or attempt to reconstruct them in the parent. Reject schemas such as transforms that cannot be represented as JSON Schema during build. Tool inputs must be top-level objects, and AJV-backed execution validation must not round-trip schemas through Zod. Settings-gated tools are filtered for the current Scope and checked again at dispatch. Settings-gated MCP contributions use the same schema-default-aware condition contract and atomically refresh the plugin's complete MCP server set when settings change.
8. External plugins use process; only trusted built-ins may use inProcess. Do not restore worker mode or describe the process boundary as an OS sandbox.
9. Classify invocation termination by the owner that triggered it, not by the shape of AbortSignal.reason. Only the runtime manager's own deadline is TIMEOUT and may contain a hung external process; an upstream abort is CANCELLED even when its reason is a TimeoutError, and must reach the active handler before ordinary generation cleanup.
10. One active generation is shared across enabled Scopes. Inject Scope/Session per invocation and reject stale-generation responses.
11. Expose Synergy internals only through capability-gated Host Services. Do not pass a raw SDK client, server URL, token, or mutable current Scope into plugin code. Connection providers use host.connection.manage; verify both contribution gating and local human/lifecycle authority through a real process invocation. Keep pairing keys in Harness and expose only the gateway endpoint. Test final-Scope/global-reset and approved-generation withdrawal while preserving multi-Scope retention and durable pairing records. Exercise pending WebSocket open after revocation and HTTP body cancellation, not only connected sockets or returned headers. Preauthenticate body intake and verify reader/deadline/aggregate budgets, including anonymous pairing endpoints. Do not retain invocation-bound Host Service callbacks in background timers; refresh endpoint snapshots during a live operation or startup hook.