rpc-plugin-system

src/ is the source root. Workflow state is kept separately at repo root in workflow.toml and workflow/ so code, tests, and examples are not polluted by workflow bookkeeping. Project-level documentation lives in repo-root docs/. The substrate PRD, architecture, implementation spec, downstream provider guidance, compatibility notes, roadmap, v1 freeze notes, V2 requirement registry, V2 threat model, and V2 release admission gate are canonical docs under docs/.

Classic source layout:

• src/cmd/rpcplugind/ — daemon entrypoint.
• src/cmd/rpcplugin-init/ — Linux PID-namespace init/reaper for recovery-enabled system services.
• src/cmd/rpcpluginctl/ — CLI entrypoint.
• src/internal/adminrpc/ — local admin RPC server/client.
• src/internal/cli/ — CLI formatting helpers.
• src/internal/eventlog/ — JSONL event log writer/reader plus provider observability schema, filters, and redaction helpers.
• src/internal/kernel/ — plugin manager, host routing, lifecycle, monitoring.
• src/internal/runtime/ — runtime directory, sockets, executable and peercred helpers.
• src/internal/auth/ — startup token helpers.
• src/pkg/plugin/ — public in-repo Go plugin SDK, including structured provider diagnostic emission.
• src/examples/ — example plugins.
• src/test/ — shared test fixtures/helpers.

Substrate boundary

This repo is the executable plugin substrate. It owns local process supervision, startup authentication, Unix-socket net/rpc transport, generation identity, lifecycle/heartbeat/restart behavior, routing, runtime artifacts, append-only JSONL logs, provider bundle metadata, SDK logging helpers, and local admin/CLI inspection.

Version boundaries are explicit:

• v1 is the frozen Linux-first local substrate and narrow routed-operation set;
• v2 adds dynamic lifecycle, trusted discovery/enrollment, signed replacement/upgrades, and fenced remote execution; and
• v3 is the Cross Platforms Proving Ground, requiring independent Linux, Windows, macOS, and FreeBSD admission and using Connected Fyne as the first integration product. OpenBSD and NetBSD are named extension targets with separate evidence.

The v3 contract is specified but not implemented by the current repository state. Compilation on an operating system is not platform admission.

It does not own broker admission, authority issuance, credential resolution, Lua execution, provider-specific workflow semantics, provider payload handling, or client-visible provider capability emission. Those belong to the core broker, authority owners, and provider-specific repos.

Provider observability is structured and redacted:

• provider diagnostics use the SDK/helper path, not arbitrary lifecycle log fields;
• plugin id, generation id, and pid are substrate-bound facts;
• capability id, operation id, correlation id, duration, bounded status, coarse error class, degraded/unavailable reason, counts/sizes, and non-authoritative digest facts are the safe diagnostic vocabulary;
• raw prompts, payloads, upstream response bodies, credentials, tokens, bearer strings, API keys, private keys, passwords, authority refs, handles, sockets, sessions, signer material, provider-private paths, and reusable external refs are rejected before durable provider writes or redacted before operator display.

Downstream provider docs should inherit this substrate by reference and add only provider-specific deltas. See docs/downstream-provider-guidance.md.

Provider diagnostics status

Final provider diagnostics judge sweep accepted this substrate with constraints. rpc-plugin-system owns the provider event schema, SDK helper, admin/CLI filters, and unsafe-material rejection/redaction. It still does not own provider-specific semantics, broker admission, authority issuance, routing policy, or client-visible provider surfaces. Keep provider diagnostics on Logger.ProviderDiagnostic; do not smuggle them through arbitrary lifecycle LogEvent fields.

Build all packages:

make build

Or directly from the source root:

cd src && go build ./...

Build command binaries directly from src/:

cd src
go build -buildvcs=false -o .tmp-bin/rpcplugin-init ./cmd/rpcplugin-init
go build -buildvcs=false -o .tmp-bin/rpcplugind ./cmd/rpcplugind
go build -buildvcs=false -o .tmp-bin/rpcpluginctl ./cmd/rpcpluginctl
go build -buildvcs=false -o .tmp-bin/rpcplugin-echo ./examples/rpcplugin-echo
go build -buildvcs=false -o .tmp-bin/rpcplugin-failure ./examples/rpcplugin-failure

Coverage policy:

• Every feature, issue fix, and regression fix must aim for 100% relevant test coverage of the behavior it touches.
• Relevant coverage means changed behavior, edge cases, regressions, and failure paths. It is not fake repository-wide line coverage theater.
• Any coverage gap must be recorded with reason, risk, and the smallest next coverage increment before the work can be considered done.
• Project coverage posture is tracked in workflow/artifacts/global-coverage-map.md.

Run the current package coverage report and write reusable evidence:

make coverage

The coverage target writes:

• workflow/artifacts/coverage.out — Go coverage profile for go tool cover/HTML inspection.
• workflow/artifacts/coverage-summary.txt — package coverage plus go tool cover -func totals, also printed to the terminal.

Run tests:

make test

Or directly from the source root:

cd src && go test ./...

Kernel-focused tests:

cd src && go test ./internal/kernel/...

The public Go plugin SDK lives at:

import plugin "rpc_plugin_system/pkg/plugin"

That import path is the local Go module path used by this source release. It is meant for packages built inside this repository checkout; it is not a fetchable external module path and should not be used with go get as a published SDK dependency.

Provider-owned diagnostics should use the structured SDK helper:

err := logger.ProviderDiagnostic(plugin.ProviderDiagnostic{
    CapabilityID:  "mail.send",
    OperationID:   "send_message",
    CorrelationID: "corr-123",
    Status:        plugin.ProviderStatusDegraded,
    ErrorClass:    "upstream_unavailable",
})

The helper routes through the shared provider event validation/redaction contract and returns validation errors instead of writing unsafe events.

Plugin capability strings are small routing/status vocabulary emitted by the SDK/runtime code:

• heartbeat — required core health check support.
• shutdown — required graceful shutdown support.
• echo — optional echo RPC support.
• sleep — optional sleep RPC support used by timeout/failure tests.
• crash — optional crash RPC support used by supervision/failure tests.

TemplatePlugin reports the required core capabilities (heartbeat, shutdown) through SDK detection. Plugins that implement optional interfaces add echo, sleep, and/or crash; plugins may also provide an explicit Capabilities() []string override for test and compatibility scenarios.