[jasper-yl]

Which issue or RFC does this PR close?

This PR proposes a follow-up RFC to RFC #2549 (plugin interfaces), which leaves standalone Source plugins and collection to a separate proposal. It replaces the contracts and management mechanisms of the Source plugin framework RFC #2012; the implementation of RFC #2549 is in #2616. It builds on the plugin host processes of RFC #2549 and the plugin routes of RFC #2579.

Rationale for this change

The old Source plugin framework runs a separate management service with its own SQLite, one Runtime process per plugin instance, and poll / reply reverse channels between the service and Server. Embodied and edge deployments still need what it offers: operators configure collection for a fleet of devices from the central Server, and devices behind NAT only connect out. This proposal keeps that capability with less machinery: targets live in two central tables, and runners pull them.

What changes are included in this PR?

New RFC docs/{en,zh}/rfcs/2617-source-plugins.md (Chinese first, English translation in sync):

• Source plugins: a SourcePlugin declaration with definitions, and for collection collect, a TargetSpec (parameter model plus a declarative identity expression), and setup. The plugin name is the capability name.
• Runners: the Server's built-in server runner and powercontext source-agent on devices, named after the credential's subject. Runners sync on a schedule: they report their plugins with parameter schemas and identity expressions, and fetch every target assigned to them across Scopes. The Server never connects to devices.
• Central targets: pc_source_collect_targets (Scope, runner, capability, normalized key, parameters, enabled, and runner-written status columns) and pc_source_runners (capabilities and last_seen_at). Adding a target validates its parameters and deduplicates by the identity expression immediately. User writes and runner writes touch separate columns.
• Results: Sources go through POST /v1/source-observations, then the checkpoint through POST /v1/connector-checkpoints/commit against its old value, carrying the target's status. Failures repeat the same Sources, which the Server deduplicates.
• Large content: inline, the plugin's object storage, or the same Source plugin on the central Server receiving files through plugin routes and reading them in its Projections; devices call their central routes through ctx.center.
• Migration and mapping: one new migration revision adds the two tables and drops pc_source_write_plugins only when it is empty; the management service, instance registration, reverse channels, and source load are removed, with a table mapping each old mechanism to its replacement.

A design demo on the author's fork (https://github.com/jasper-yl/powercontext/tree/feat/source-plugins-demo, not for merging) runs a simulated robot camera through a real Server: a device runner reports its plugin and parameter schema on sync; targets added centrally are validated and deduplicated by the identity expression (same parameters return the existing target, a normalized duplicate with other parameters conflicts, invalid parameters and unknown runners return 422); the runner collects, submits Sources, and advances the checkpoint; a lost connection before the checkpoint commit leaves it unchanged and the retry repeats the same Sources without duplicates; status and failures are reported per target; disabled targets leave the sync; a target in a new Scope is collected on the next sync without a restart. The demo keeps its tables in a separate SQLite file and does not cover the Server runner, large files through a central plugin, the migration, or the Dashboard form.

Are there any user-facing changes?

This PR changes documentation only. The proposed design replaces the /v1/source-management/* instance, configuration, channel, and write-plugin APIs with runner and target APIs, keeps the MCP tools pc_source_add, pc_source_status, and pc_source_target_set_enabled, and adds pc_source_runners, pc_source_target_delete, and powercontext source-agent.

How was this change tested?

• uv run prek run --files docs/en/rfcs/2617-source-plugins.md docs/zh/rfcs/2617-source-plugins.md
• Checked that both locales have matching sections, tables, and code blocks.
• Ran the design demo's acceptance scenario tests/e2e/test_source_collection_demo.py on the fork branch against a real Server process.

AI usage statement

Drafted with Claude Code (Claude Opus 5.5) under the author's direction and review; the design decisions were made in discussion with the author.

🤖 Generated with Claude Code

[Zxf-xufeng]

Design review at d00cbb05. This PR contains an RFC, so the findings below concern the proposed contract rather than a merged collector implementation. I have not run the fork demo.

[P1] Fence collection commits against target configuration changes and deletion

The RFC allows target parameters to change, but remote result submission only compares the previous checkpoint. That checkpoint need not change when the parameters change. A runner can therefore collect using the old parameters and subsequently advance the checkpoint after the target has been edited, causing the new configuration to resume at an incompatible position and potentially skip data.

Deletion has a related gap. The existing checkpoint repository permits insertion when the checkpoint is missing and the expected value is None. A delayed first collection can therefore recreate a checkpoint after its target has been deleted unless the target is checked as part of the commit.

Please specify that a checkpoint/status commit validates the target's existence, runner ownership, enabled state, and configuration revision or digest in the same transaction as the update. Define what happens to the checkpoint when parameters change the collection identity: reject the in-place change and require a new target, or explicitly reset it with stale-attempt protection. Also state the allowed behavior for Sources already accepted by the separate observations request; checkpoint validation alone cannot undo those writes.

Acceptance should cover parameter edits, disable/delete, and delayed commits, including a first attempt with an expected None checkpoint. This can use the proposed target table rather than introducing another table.

[P2] Persist the authenticated owner of a custom runner name

The runner section permits --name, including multiple devices sharing a credential. The API section defines ownership as either a matching authenticated subject or the subject recorded when the runner was registered. However, the proposed pc_source_runners schema contains no owner-principal field or equivalent binding.

Please define and persist the authenticated owner for custom runner names, including name uniqueness/conflicts and the rule that an ordinary sync cannot replace that owner. Otherwise the specified authorization cannot reliably distinguish the owner from another principal attempting to sync under the same name and overwrite capabilities or retrieve assigned targets. Alternatively, restrict the initial implementation to names derived from the authenticated principal.

Acceptance should verify that another principal cannot claim or sync an existing custom runner name, while the original owner can reconnect.

Reference: RFC: runners, result submission, persistence, and API authorization.

[hidb4ai]

Reviewed a7c1224b (RFC only). The two contract gaps in the existing review remain: checkpoint/status commits are not fenced against target edits or deletion, and custom runner names have no persisted authenticated owner. The version-compatibility update does not address either.

I checked the reused checkpoint store with SQLite: removing a checkpoint and then submitting a delayed first commit with expected=None recreates it. Please specify transactional target/configuration validation and durable runner ownership in both locales before accepting the design. This verifies the existing persistence behavior; I have not run the fork demo or a proposed runner implementation.

[hireview001]

[P2] Authorize registered runners only through their bound subject

If subject fleet-service first registers runner robot-7 using --name, this OR rule also authorizes the distinct subject robot-7 to retrieve its targets and checkpoints, violating section 3's first-sync ownership binding. Require the persisted bound subject for subsequent syncs, document that binding in runner persistence, and correct both locales.