[Init] Initial commit - NetMesh terminal manager

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

@@ -0,0 +1,279 @@
+# 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.