first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Run control channel is lightweight
+The run executor SHALL use a lightweight control channel for hello, heartbeat, capability reporting, version reporting, and capacity reporting only.
+
+#### Scenario: Run starts
+- **WHEN** run starts and reaches the platform
+- **THEN** it MUST register through hello and report capabilities before accepting jobs
+
+#### Scenario: File transfer is active
+- **WHEN** run is uploading or downloading large artifacts
+- **THEN** control heartbeats MUST remain independent from artifact transfer progress
+
+### Requirement: Job channel supports lifecycle semantics
+The run executor SHALL support job claim, ack, progress, result, cancel, and reconcile semantics for server lifecycle, config, database, backup, and plugin-triggered work.
+
+#### Scenario: Job accepted
+- **WHEN** run accepts a job
+- **THEN** it MUST return a structured ack before execution and terminal result after execution
+
+#### Scenario: Run restarts during job
+- **WHEN** run restarts or reconnects after accepting a job
+- **THEN** the platform MUST be able to request reconciliation using job identity or idempotency identity
+
+### Requirement: Logs use durable ingest
+Run SHALL collect server logs into a local spool and upload compressed batches with stream identity, monotonic sequence range, checksum, and acknowledgement handling.
+
+#### Scenario: Platform unavailable
+- **WHEN** platform log ingest is temporarily unavailable
+- **THEN** run MUST retain unacknowledged log batches locally and retry without losing sequence continuity
+
+#### Scenario: User transfers files while logs are active
+- **WHEN** artifact transfer is consuming bandwidth
+- **THEN** log flush MUST keep priority over artifact chunks so historical logs continue to advance
+
+### Requirement: Artifact transfer is isolated
+Run SHALL transfer files through an artifact channel with chunking, checksums, resume support, concurrency limits, and throttling separate from logs and control.
+
+#### Scenario: Plugin writes a config file
+- **WHEN** a plugin asks the platform to write a config file
+- **THEN** run MUST receive a scoped job that references an artifact or bounded inline content and MUST write through a safe temp-and-replace flow
+
+#### Scenario: Large file download active
+- **WHEN** a large file download is active
+- **THEN** job ack/result and log batch upload MUST NOT wait behind all artifact chunks
+
+### Requirement: Game client bridge is optional and separate
+The system SHALL support an optional game client bridge channel for games that require in-game command execution or structured snapshots, but it MUST remain separate from run lifecycle and log ingestion channels.
+
+#### Scenario: Game needs in-game command bridge
+- **WHEN** a game management plugin declares that a game needs an in-game client bridge
+- **THEN** the platform MUST route game command polling and snapshot reporting through the client bridge contract rather than the run artifact or log channels