browser/openspec/changes/implement-real-game-plugin-lifecycle-proof/design.md

Context

The current architecture stream has package-level evidence for platform APIs, run channels, plugin manifests, SDK bridge envelopes, and the management frontend. The latest baseline still found a critical product gap: it could not prove that one local game management plugin can create and manage multiple real server instances through the intended platform-mediated path.

This proof spans all four product roots. plugins/ must declare and request lifecycle capabilities without owning transport. platform/ must authorize plugin lifecycle requests, create server records, dispatch bounded jobs, persist state, and expose safe API responses. run/ must execute or simulate local lifecycle jobs through its channelized executor contract and return observable results. platform_web/ must let an authorized user install/use the plugin and inspect separate server instances without showing raw host paths, credentials, sockets, or run transport details.

Goals / Non-Goals

Goals:

• Prove one installed local game management plugin can create at least two independent server instances.
• Prove install/create/start/stop/status/log/artifact lifecycle operations are routed through platform APIs and run jobs, not direct browser/plugin access to run.
• Prove each instance has independent identity, lifecycle state, operation history, logs/artifacts where applicable, and browser-visible controls.
• Prove plugin manifest permissions and SDK bridge envelopes reject direct run URLs, host paths, raw credentials, raw AI keys, and undeclared lifecycle actions.
• Provide repeatable API, run, plugin, frontend, and browser verification commands.

Non-Goals:

• No billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated marketplace behavior.
• No production-grade game server hosting, cloud provisioning, external orchestrator, or remote game binary distribution.
• No direct browser-to-run or plugin-to-run transport.
• No new raw host path, raw socket, raw credential, or raw AI-key exposure.
• No broad redesign of the magical crystal-moonlight frontend style.

Decisions

Decision 1: Use one first-party local proof plugin

The implementation will use the existing local example/dev game plugin as the proof target or evolve it into a clearly named local lifecycle proof plugin. The plugin declares lifecycle actions and platform-mediated capabilities in its manifest, and its SDK calls produce bounded platform bridge requests.

Alternative considered: introduce several plugins for different games. Rejected because the stream needs one focused proof that the lifecycle path is real before multiplying game-specific scope.

Decision 2: Platform owns lifecycle authority and instance records

The platform remains the authority for plugin installation state, server instance records, lifecycle authorization, job creation, audit events, and safe response DTOs. Plugin requests name logical server/plugin/action identifiers; platform translates them into jobs for run and stores resulting state.

Alternative considered: allow plugin pages to call run endpoints directly for local development. Rejected because it violates the required channel boundaries and would make browser proof unsafe.

Decision 3: Multi-instance proof requires independent state and evidence

The proof is not accepted unless the same installed plugin creates at least two server instances and can start/stop them independently. Evidence must include distinct IDs/names, operation history per instance, lifecycle state projection, and browser-visible separation.

Alternative considered: create one server and assume the code generalizes. Rejected because the baseline gap is specifically multi-instance real operation.

Decision 4: Run proof can use bounded local lifecycle execution

The run-side executor may use a deterministic local fixture command or safe simulated local game process when no real game binary is available, but it must still travel through the run job channel and return job ack/result/state evidence. Any fixture must be explicit and must not expose raw host paths to plugins or platform_web.

Alternative considered: require a full real game server binary immediately. Rejected because the architecture proof is about platform-mediated lifecycle wiring and instance isolation, not a specific commercial game runtime.

Decision 5: Browser acceptance must be API-backed

The browser walkthrough must use a real platform session and local stack. Local auth fallback, static seed-only data, and demo-only plugin controls cannot satisfy this proof. The walkthrough must record the stack commands, pages visited, actions taken, visible state, and unsafe-field checks.

Alternative considered: accept unit and integration tests only. Rejected because this stream requires browser evidence for frontend-facing behavior.

Risks / Trade-offs

• [Risk] Local stack setup may remain brittle. Mitigation: tasks require exact commands, health checks, and explicit blocker recording if a service cannot bind or authenticate.
• [Risk] A simulated local lifecycle fixture could be mistaken for production hosting. Mitigation: name it as a local proof fixture and require platform/run channel evidence rather than game-specific claims.
• [Risk] Plugin bridge expansion could accidentally expose transport details. Mitigation: add negative tests for direct run URLs, host paths, raw credentials, sockets, and raw AI keys.
• [Risk] Multi-instance state can collapse into shared mutable demo data. Mitigation: require two instances with independent IDs, operation histories, and state transitions.
• [Risk] Browser proof can pass against fallback data. Mitigation: require API-backed login, platform responses, and no 本地会话/demo fallback classification for accepted proof.

Migration Plan

1. Extend the local proof plugin manifest and SDK/page code to declare lifecycle actions and platform-mediated capability envelopes.
2. Add platform service/API support or repair existing endpoints for plugin-mediated multi-instance create/install/start/stop/status operations.
3. Add run-side lifecycle handling needed to acknowledge jobs, execute bounded local fixture operations, and return instance-specific results.
4. Update platform_web server/plugin flows to expose the proof actions and state without changing the visual system.
5. Add automated tests across plugin, platform, run, and platform_web.
6. Run the full local stack and browser walkthrough, recording exact evidence before marking tasks complete.

Rollback before acceptance is to remove the proof plugin lifecycle declarations, platform/run/frontend implementation changes, and any verification fixtures added by this change.

Open Questions

• Whether the local lifecycle fixture should be a no-op process, a tiny managed process, or an existing example game command.
• Whether the browser walkthrough should use docker-compose or separate local commands as the primary evidence path.
• Whether the proof report should be a standalone artifact under this change or embedded only in tasks.md evidence.