Netcatty/docs/plugin-platform/runtime-extension-boundaries.md

Plugin runtime extension boundaries

Status: phase 3 internal architecture review

This document records the host-runtime decisions that later plugin-platform phases are allowed to depend on. The goal is to keep permission, contribution, terminal, connection, synchronization, and distribution work out of the runtime lifecycle core while still giving those phases stable internal seams.

These are host-internal APIs, not the public plugin API. The public contract remains 0.1.0-internal until the phase-9 API 1.0 freeze.

Runtime identity is the authority root

Every activation receives a new host-generated runtime ID. The identity used by host handlers contains the plugin ID, active version, runtime kind, package root, manifest, logger, and host-resolved security principal. It is captured when the runtime starts and cannot be supplied or replaced by plugin messages.

The RPC registry adds this identity to every request, notification, middleware call, and incoming stream. A later permission decision can therefore bind a grant to all of the following without trusting payload fields:

• plugin ID and version;
• one activation (runtimeId) for once/session grants;
• browser or advanced utility placement;
• declared manifest permissions and resources;
• the unsigned or later verified publisher security principal;
• the request cancellation and deadline context.

Host-to-plugin calls also verify that the recorded activation still matches the database's enabled active version. An update cannot accidentally deliver a command or Provider request to the old version after the active-version pointer has moved.

Placement resolution and activation repeat that version check after every asynchronous policy or startup boundary. A late crash or startup failure from an old version is emitted for cleanup and diagnostics but cannot increment the replacement version's crash counter, quarantine it, or overwrite its runtime state. If the old immutable version is still installed, the event updates that version's own runtime and crash state so a later rollback cannot mistake it for a clean or still-running release.

One capability registry, two message classes

PluginHostRpcRegistry is the composition point for plugin-to-host authority. It deliberately distinguishes request handlers from notification handlers. Storage mutations cannot be invoked as fire-and-forget notifications, and the logging notification cannot be converted into a request with a meaningful result. Reserved lifecycle and transport methods cannot be registered as capabilities.

Registrations have unique method ownership and may carry immutable metadata. Each registration may also provide a synchronous, side-effect-free parameter validator. It runs before middleware, so resource extraction, permission decisions, quotas, and audit records always consume the method's normalized parameter shape instead of attacker-controlled raw input. Middleware then runs immediately before the final handler with the host identity, method, validated parameters, metadata, cancellation signal, request ID, and deadline. Phase 3 installs permission, quota, audit, and fail-closed UI mediation here, at the final privileged boundary rather than in renderer components. Handler metadata is recursively copied and frozen when registered. Runtime identity is checked before middleware, again after any asynchronous middleware (such as an approval prompt), and once more before a result leaves the route. An old activation therefore cannot resume a privileged handler after an update, disable, quarantine, or stop transition.

Asynchronous handlers also receive context.assertActive(). A handler that prepares I/O and then commits a mutation must call it immediately before the commit and honor context.signal while waiting. The guard checks both the host-owned activation identity and the request cancellation signal, so a timed-out approval or Provider operation cannot commit merely because the same plugin version remains active. Cancellation cannot undo a side effect already issued to an external service, so this commit guard is part of the capability-handler contract.

A running activation uses a route snapshot. Registering a new host subsystem does not mutate a live plugin's authority invisibly; it applies on the next activation. This is important when a new Netcatty build adds a capability or a grant changes the available surface.

Capability middleware is not the transport quota boundary: reserved progress, cancellation, lifecycle, and stream frames do not enter a business-method handler. The supervisor therefore binds an optional synchronous raw-message guard to the same host-generated runtime identity. It runs before JSON budget walking and protocol dispatch for every message class. Phase 3 uses this seam for per-activation rate and resource accounting, while capability middleware continues to own permission and operation-specific policy. The guard must be synchronous so an untrusted message cannot accumulate an unbounded queue of pending quota decisions.

Bidirectional invocation and validation

RuntimeSupervisor.request(), notify(), and openStream() are the only general host-to-plugin entrypoints. All three can bind work to the exact authorized runtime identity; streams repeat that check before opening and again after the runtime returns the handle. Browser and utility runtimes implement the same methods over their private router. Later registries do not reach into a runtime window, utility process, MessagePort, or router.

Router requests may carry a reviewed structured-clone transfer list. This is used to establish privileged terminal interceptor ports while retaining one owner for correlation, deadlines, cancellation, validation, late responses, close cleanup, and protocol-failure containment. After the attachment request is accepted, terminal bytes travel only on the transferred dedicated port and do not enter the JSON-RPC control plane.

Outgoing requests accept a method-specific result validator. Command and Provider adapters must validate their exact public result schema before using plugin data. The generic JSON boundary remains the first structural limit, not a substitute for operation-level validation. Connection Providers additionally validate the operation-specific result map: resize, signal, reconnect, and close must return JSON null; getStatus must return a bounded ConnectionStatusResult object and may attach structured diagnostics. Status diagnostics are propagated through the host-owned terminal finish route so later disconnect, reconnect, or authentication failures remain visible after the initial open response.

Control-plane JSON is limited to 1 MiB. Large command results, importer data, sync objects, terminal snapshots, and connection traffic must use the bounded stream transport rather than raising this limit. A cancelled request ID remains temporarily retired until one possible late response is discarded, so a slow provider cannot accidentally answer a newer request after ID wraparound.

Lifecycle methods and $/ transport methods are excluded from the general entrypoints. Only the supervisor may initialize, activate, deactivate, cancel, or account for a runtime.

Stream ownership and the terminal fast path

Incoming stream handlers are registered centrally and receive a bind function for the matched stream, an abort signal, and the same runtime identity. The first handler that recognizes a pre-authorized stream ID owns it; unknown streams are cancelled. Owner selection has the same bounded deadline as RPC, so a stalled registry cannot retain an unowned stream indefinitely. Frames are ordered per stream ID rather than through one global queue: a slow consumer backpressures its own stream without blocking unrelated connection, importer, or synchronization streams. Once a handler binds ownership, every local reject, deadline, transport failure, peer close, or host shutdown reaches its onClose cleanup boundary exactly once. The same abort signal remains live for the whole owned stream and is aborted before cleanup, so long-running Provider work can stop promptly instead of polling runtime state. Handlers registered after activation require a restart, matching RPC route snapshot semantics.

General RPC streams remain bounded control/data channels for importers, sync, connection Providers, and non-hot terminal results. Phase 6 still creates its planned direct terminal-worker-to-utility-process MessagePort; it must not put the 4 ms interceptor budget through this general JSON-RPC path.

Every outbound write either reaches the transport or rejects. Port failure, router close, peer cancellation, and local cancellation settle all queued writes and invalidate retained receive-credit callbacks. If returning receive credit itself fails, the incoming stream is removed and its owner is notified before the error escapes. Normal end/error frames await the owner's asynchronous close handler; forced synchronous router shutdown contains a rejected cleanup promise so it cannot become an unhandled process rejection. Later provider code must still release consumed chunks promptly and must not retain a release callback as an application-level acknowledgement. An outgoing stream that has sent its terminal end retains only its bounded credit state until the peer releases the final chunks. Those ordinary late window updates retire the stream instead of being misclassified as protocol violations; writes remain closed as soon as end is sent.

Placement, lifecycle, and packaged modules

Runtime placement is selected through an injectable resolver. The default continues to prefer the sandboxed browser entrypoint. Phase 3 can require an advanced-runtime grant, and phase 9 can add trust attestation, without changing activation, crash, or shutdown ownership.

The resolver receives an abort signal. Stop, disable, uninstall, and application shutdown cancel both a pending placement decision and an activation already in progress. Cancellation does not count as a plugin crash. A permission prompt introduced in phase 3 must honor this signal, so shutdown never waits for a renderer decision and no runtime can appear after the supervisor has closed. Manager shutdown starts supervisor cancellation before waiting for its serialized mutation queue, so a mutation currently blocked inside placement or activation cannot deadlock the quit path that is waiting for that same mutation. Concurrent manager or supervisor shutdown callers share the same completion promise. No caller may observe shutdown completion before runtime teardown and startup cancellation have both settled. Browser and utility runtimes recheck the same signal after every asynchronous resource-creation boundary; cancelling only the outer supervisor promise is not sufficient. Start and stop also share a per-plugin transition gate. A lazy activation waits for the previous process to finish stopping, while disable/uninstall persist the disabled state before teardown. Later activation events therefore cannot race a management operation and recreate a runtime that the user just disabled. For an advanced utility runtime, kill() is only a termination request. Its stop promise remains pending until Electron emits the child exit event. Unexpected fatal and protocol failures likewise revoke RPC immediately but are published to the supervisor only after the process is reaped. Permission, connection, synchronization, and companion state can therefore treat the stop event as a real process-containment boundary rather than an intent signal. If the process ignores graceful termination, the host escalates to an OS-level forced termination after a bounded grace period and still waits for exit. Failure to reap after escalation disables and quarantines the plugin for the rest of the application process; no replacement activation is allowed until Netcatty restarts. This fail-closed state is deliberately in-memory as well as persisted, so clearing a normal crash quarantine cannot overlap a still-live advanced process.

Runtime state listeners receive starting, running, stopped, error, and quarantined transitions with the stable activation identity. Permission scopes, commands, views, and Provider registries can release their state on one common stop boundary. Listener failures cannot break plugin shutdown.

Progress notifications have a separate supervisor event. Each event carries the host-assigned activation identity together with the schema-validated token and an immutable progress value, so simultaneous Providers from different plugins or plugin versions cannot collide on a token alone.

Browser import maps and utility-process loader mappings are generated from one reviewed host-module resource list. Adding @netcatty/plugin-ui or another host-owned SDK package does not expand arbitrary filesystem access or require a new protocol route. Plugin packages still cannot add mappings themselves.

Downstream phase matrix

Phase	Stable seam available to the phase	Work owned by that phase
PR 3 permissions	RPC middleware, immutable runtime identity, raw-message guard, placement/principal resolver, runtime stop events	principal-bound grants, resource canonicalization, secrets, credentials, companions, quotas (implemented)
PR 4 contributions	host-to-plugin request/notify, runtime events, host module resources	implemented: lazy activation, command/settings/view registries, Context Keys, UI SDK and sandboxed views
PR 5 terminal Providers	validated host requests, cancellation, lifecycle events	Provider ranking, deadlines, snapshots, built-in highlighter/autocomplete adapters
PR 6 terminal pipeline	runtime identity and placement policy	direct MessagePort fast path, sensitive-input bypass, circuit breaker
PR 7 connection/auth/import	activation-owned Provider requests, exact result validators, bounded streams, diagnostics, secret leases, credential refs	implemented: connection sessions, authentication challenges, importer preview/commit
PR 8 sync	streams, lifecycle identity, namespaced storage boundary	implemented: kind: "sync" Providers with provider.sync, encrypted-object connect/read/write/delete/capabilities, WebDAV through shared storage surface, non-cascade sidecars for sync: true settings and account/CRDT baselines
PR 9 distribution	retained immutable versions, compare-and-set restore, placement resolver, module resources	signatures, trust, health checks, audited update and user rollback policy, API 1.0, and the reproducible terminal benchmark harness/environment/release gate for the 1% throughput and 4 ms p95 / 8 ms p99 input-latency targets

Data-model decisions that must remain explicit

The phase-2 database retains every installed immutable version and provides a compare-and-set pointer restore used only when a just-installed version fails activation. Phase 9 can build audited update, health-check, and user-initiated rollback policy on this primitive without changing package layout; phase 2 does not expose that broader policy.

Crash history is keyed by plugin and version. Changing the active version starts with clean runtime state, while reinstalling identical version bytes does not clear quarantine. Phase 9 can therefore assess and roll back one bad release without inheriting or erasing another version's failure history.

Package publication exposes one internal beforeActivate commit boundary. The manager uses it to disable and stop an enabled old activation before the database pointer changes, and restores that activation if preparation fails. Phase 9 health checks and rollback must preserve this ordering instead of writing the active-version pointer directly.

plugin_kv is runtime-owned local data and is removed by explicit uninstall. Phase-3 encrypted secrets, persistent grants and security audit, plus phase-4 settings and view state, use separate non-cascade tables. PR 8 stores encrypted sync sidecars (plugin_sync_sidecars) in the same non-cascade class for sync: true settings plus plugin sync account/CRDT baselines. Missing or uninstalled plugin code must not cascade-delete those rows or coerce related sync configuration away.

Activation events are declared by the public manifest. Phase 4 now starts only onStartupFinished plugins during contribution initialization; commands, views, and Providers call the existing idempotent start() boundary at first use. This implements lazy activation without replacing process supervision.

Review checklist for changes to this boundary

Before a later phase changes the supervisor or transport, verify:

1. Can the behavior be expressed as a registry handler, middleware, placement resolver, state listener, validated request, or stream owner instead?
2. Does every privileged operation retain the host-generated runtime identity?
3. Can a request race an update, disable, quarantine, crash, or shutdown and reach a stale runtime?
4. Are request and notification semantics distinct and exactly validated?
5. Is terminal hot-path work kept off general JSON-RPC?
6. Does missing or uninstalled plugin code preserve user-owned data?
7. Does adding a host SDK module expand only an explicit trusted resource list?

If the answer requires a new public plugin concept, update the canonical JSON Schema, generated types, SDK, compatibility rules, documentation, and drift tests together. An internal shortcut must not become an accidental public API.