VerseVDI-Data-Plane/AGENTS.md

VerseVDI Data Plane repository guidance

This repository is the GPLv3 implementation boundary for the separately deployed VerseVDI gateway, Apollo adapter, later Rust streaming core, and native clients. It is private in Gitea during engineering. Privacy does not change the repository's GPL boundary.

Authority and scope

• The closed Connection Server owns authentication, authorization, PostgreSQL, assignments, broker sessions, product licensing, gateway placement, grants, and durable audit.
• The Protocol repository is the sole wire-contract authority. Pin an exact immutable Protocol release; never add a sibling-checkout replace or a local wire fork.
• This repository owns provider compatibility, packet translation, gateway forwarding, and later client-side streaming code. It receives only session-scoped authority over versioned authenticated network contracts.
• Never copy proprietary Connection Server or private Planning Hub content into this repository.
• Apollo, Moonlight, and other reference trees are evidence, not dependencies or scaffolding. Use only the reviewed commits in the Planning Hub lock and record provenance before copying or deriving any implementation.

Phase 3C hard boundaries

• The gateway is a separately deployed pure-Go process. No cgo or hidden native sidecar.
• All Verse client streaming traffic crosses the authenticated gateway. Never expose or route a client to Apollo/provider DNS, IP, ports, certificates, or credentials.
• Relay encoded media without decode, encode, transcode, render, or codec conversion.
• Keep transport, framing, media profile, source-rate control, and client decode capabilities separate. Apollo/GameStream is one qualified provider profile, not the permanent Verse contract.
• Validate provider identity and negotiated protection. No insecure retry or silent capability fallback.
• Bound every parser, queue, fragment, stream, datagram, timer, goroutine, allocation, and metric label.
• A failed Apollo feasibility spike is a terminal NO-GO; preserve evidence and reopen the architecture decision rather than implementing around it.

Source and verification rules

• The Go module is git.sechmachine.io.vn/sechmachine/VerseVDI-Data-Plane and uses Go 1.26.5.
• Run make verify after changing the Go or OpenSpec baseline.
• Use test-first implementation for non-trivial behavior. Fuzz every external parser and run race/resource checks required by the approved task.
• Do not hand-edit generated Protocol bindings. Advance the Protocol pin only after its immutable release and fixture hash are recorded.
• OpenSpec changes must map exact Planning Hub requirement IDs and include failure scenarios. Archive only after canonical specs and evidence match.
• Verification is evidence-invalidated, not time-based: focused checks after a change, one affected suite per milestone, and one complete gate after code freeze. Reuse evidence while source, locks, configuration, environment, and artifact digest remain identical.

Git, CI, and publication safety

• origin/main-agentic is the private Gitea engineering authority.
• Preserve user-owned dirty work. Do not reset, discard, force-push, merge, publish, or change remotes/branch protection without explicit authorization.
• Commit cohesive verified increments with concise Conventional Commit subjects.
• Keep credentials, packet payloads, private captures, host addresses, and Planning Hub evidence out of Git and CI logs.
• Public repository creation, release tags, packages, signing, and Corresponding Source publication are separate promotion actions.